From 490afb1f41b1d6aef946d21613cf9fbacd79e3df Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 6 Oct 2025 18:05:02 +0100 Subject: [PATCH 01/19] initial doc structure --- .../_index.md | 10 + .../installation/_index.md | 317 ++++++++++++++++++ .../post-installation/_index.md | 10 + .../post-installation/try-it-out.md | 19 ++ .../pre-installation.md | 25 ++ .../requirements.md | 62 ++++ data/urls.toml | 4 + 7 files changed, 447 insertions(+) create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md create mode 100644 content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md new file mode 100644 index 000000000..dbbf1e8ca --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md @@ -0,0 +1,10 @@ +--- +title: "Add Configuration Portal to CORTEX" +linkTitle: "Add Configuration Portal to CORTEX" +description: "Information about pre-installation steps and installation instructions for the {{% ctx %}} Configuration Portal for {{% ctx %}}." +weight: 50 +--- + +{{< alert title="Important" color="warning" >}} +This guide currently only describe how to add the {{% ctx %}} Configuration Portal to an existing Web Application Server. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +{{% /alert %}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md new file mode 100644 index 000000000..dd9577a0f --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md @@ -0,0 +1,317 @@ +--- +title: "Install the Web Application Server" +linkTitle: "Install Web Application Server" +description: "Information about installing the Web Application Server." +weight: 40 +--- + +# {{% param title %}} + +This guide describes how to install the {{% ctx %}} Configuration Portal on the Web Application Server. + +## Perform Installation + +### Import {{% ctx %}} Flows + +The {{% ctx %}} Configuration Portal calls a set of flows to validate log-in credentials, and to manage interactions with the config reliable collections, where config data is stored. These flows are contained within the provided studio packages. + +To import the flows, perform the following steps: + +1. Log into the {{% ctx %}} Gateway that was installed within the CORTEX Web Application Server. +1. In {{% ctx %}} Gateway, click `Admin`, then `Studio Import`. +1. Import the following Studio packages which can be found in the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted: + 1. `Configuration.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Configuration Portal`. + 1. `Interaction.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Interaction Portal`. + 1. `User Access Management.Flows.studiopkg`, which can be found in the folder named `User Access Management`. +1. Once imported, Set up the access to these flows using Studio Authorisation. +{{< alert type="note" title="Note" >}} +Once the flows are imported, they should be available from the ‘Dev’ charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing +{{< /alert >}} + +### Configure the flows + +#### User Access Management flow + +1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `UAM-Get-Config` +1. Click on the first `Set Variable` block to show the properties. +1. Within the value field, update the following parameters only: + | Name | Description | Example | + |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| + | PowerShellDetails.Username | The username of an account that can run PowerShell commands on all {{% ctx %}} servers, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator across the {{% ctx %}} servers.{{< /alert >}} | `"ctx_serviceuser"` | + | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | + | PowerShellDetails.Host | The FQDN of the host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This can be `Environment.MachineName` to use the current node executing the flow.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `Environment.MachineName` | + | PowerShellDetails.Port | The PowerShell port. | `5985` | + | PowerShellDetails.SSL | Whether to use SSL for the PowerShell command. | `false` | + | RecursiveAccessControl | Whether child user groups should inherit access control granted to parents. | `false` | + | OptionalAdConfig.DomainController | The FQDN of the domain controller server. {{< alert type="note" title="Note" >}}If left empty, the domain that the node is attached to will be used.{{< /alert >}} | `"dc-machine.domain.com"` | + | OptionalAdConfig.BaseAdGroupSearch | The base path within the domain from which users can be selected. {{< alert type="note" title="Note" >}}If left empty, the entire domain will be used.{{< /alert >}} | `"CN=Builtin,DC=CortexUsers,DC=com"` | + | OptionalAdConfig.Username | The username of an account used to query Active Directory. {{< alert type="note" title="Note" >}}If left empty, the `PowerShellDetails.Username` will be used.{{< /alert >}} | `ctx_aduser` | + | OptionalAdConfig.Password | The password for the username specified for `OptionalAdConfig.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + +This should look similar to the following: + +``` json +{ + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "RecursiveAccessControl": false, + "OptionalAdConfig": { + "DomainController": "dc-machine.domain.com", + "BaseAdGroupSearch": "CN=Builtin,DC=CortexUsers,DC=com", + "Username": "ctx_aduser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#" + }, + "DataStorage": { + "UamConfigCollection": "uamConfig", + "SessionsKeysCollection": "uamSessionsKeys", + "SessionsCollection": "uamSessions", + "ServiceRequestsCollection": "serviceRequests" + } +} +``` + +1. Save and commit `UAM-Get-Config`. + +#### Configuration Management flow + +1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `CM-Config-Settings` +1. Click on the first `Set Variable` block to show the properties. +1. Within the value field, update the following parameters only: + | Name | Description | Example | + |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| + | PowerShellDetails.Username | The username of an account that can run PowerShell commands on the host specified for `PowerShellDetails.Host`, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator on the targeted Host.{{< /alert >}} | `"ctx_serviceuser"` | + | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | + | PowerShellDetails.Host | The FQDN of the host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This must target a specific {{% ctx %}} Server.{{< /alert >}} | `"cortexapp-machine.domain.com"` | + | PowerShellDetails.Port | The PowerShell port. | `5985` | + | CortexInteractionPortalPath | The path to the Cortex Interaction Portal. | `@"C:\inetpub\wwwroot\Cortex\ConfigurationPortal"` | + | ConfigurationExportsFolder | The folder containing the configuration being exported. | `@"ConfigurationModule\Exports"` | + | ConfigurationImportsFolder | The folder containing the configuration being imported. | `@"ConfigurationModule\Imports"` | + | ConfigurationBackupsFolder | The folder containing the configuration backups if scheduled. | `@"ConfigurationModule\Backups"` | | `false` | + +This should look similar to the following: + +``` json +{ + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "configCollectionName": "_cfgCollection", + "containerKeys": "_cfgContainerKeys", + "paramKeys": "_cfgParamKeys", + "CortexInteractionPortalPath": @"C:\inetpub\wwwroot\Cortex\ConfigurationPortal", + "ConfigurationExportsFolder": @"ConfigurationModule\Exports", + "ConfigurationImportsFolder": @"ConfigurationModule\Imports", + "ConfigurationBackupsFolder": @"ConfigurationModule\Backups", + "BackupBypassToken": "f2e97889-acd8-4324-9ac0-e6cc776478ed" +} +``` + +1. Save and commit `CM-Config-Settings`. + +### Create the Configuration Management Package + +1. Within {{% ctx %}} Gateway, open the `Admin` charms then click on `Packages` +1. Click on `Add Package Definition` then: + 1. Set the `Package Name` to `CORTEXConfigurationManagement` + 1. Select the flows and groups as follows: + [ ] `Cortex-Library` + --- [X] `Config Management` + --- [ ] `Cortex Interaction Portal` + ------ [ ] `Core Portal Flows` + --------- [X] `UI-Get-AD-Groups` + --------- [X] `UI-Manage-Settings` + --- [ ] `User Access Management` + ------ [ ] `Config Data Storage` + --------- [X] `UAM-Get-Settings` + --------- [X] `UAM-Update-Settings` + ------ [ ] `Session Data Storage` + --------- [X] `UAM-Create-Session` + --------- [X] `UAM-Get-Session` + ------ [X] `UAM-Authenticate-User` + ------ [X] `UAM-Check-Access-Level` + ------ [X] `UAM-Get-Config` + ------ [X] `UAM-Validate-Token` + 1. Click `Save` + 1. Once saved, click `Publish` + 1. Once published: + 1. Select the `Authorisation` tab + 1. Select the groups that should be able to execute this package +{{< alert type="note" title="Note" >}} +Keep a note of the selected groups, as they will be required when setting the access control for the {{% ctx %}} Configuration Portal. +{{< /alert >}} + +### Create the {{% ctx %}} Configuration Portal Website + +On the Web Application Server: + +1. Open the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted. +1. From there, open the `Cortex Configuration Portal` folder. +1. Open the `Cortex.Configuration.Portal.zip` file and extract the contents to where the website is to be installed +{{< alert type="note" title="Note" >}} +Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` +{{< /alert >}} +1. Copy the `web.config` and `appsettings.json` files from the `Cortex Configuration Portal` folder to the root of the extracted website folder. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` + -FeatureFlags "InnovationId" ` + -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" ` + -ServiceFabricUsingSelfSignedCertificates $false ` + -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerEndpoint 'https://server.domain.com:8722/api/' ` + -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` + -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFilePath "C:\Install\Certificate.pfx" ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirementsNew" title="Generate Encryption Key" >}} steps.{{% /alert %}} + + | Name | Description | + |-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | + | `FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Obtain a {{% ctx %}} licence file][] step during Pre-Installation, if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will set the `FeatureFlags` value in the {{% ctx %}} Gateway web.config. | + | `ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the server. The port should be specified as `8722` and there must be a trailing slash, e.g. `https://server.domain.com:8722/`.

This will set the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config. | + | `ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Server][Configure Installation Script], `$true` if you used self-signed certificates.

This will set the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config. | + | `ServiceFabricApiGatewayBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + | `ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + | `DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Web Application Server.

This will set the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config. | + | `DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + | `DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + | `DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will set the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config. | + | `GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that should be used to run the {{% ctx %}} Gateway application pool as configured in [Get {{% ctx %}} Gateway Application Pool User][Get CORTEX Gateway Application Pool User]. | + | `WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`. | + | `WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`. | + | `ImportCertificate` | Change this from `$true` to `$false` if you do not require the certificate to be imported as part of the installation process.

Note that if this is changed to `$false` you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation. | + | `CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged but you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation. | + | `CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false` this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate. | + | `ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created {{% ctx %}} site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`. | + | `ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process. | + | `UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443). | + | `AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + | `FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +### Install {{% ctx %}} Gateway + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. +1. A prompt will appear to enter the password for the user specified to run the {{% ctx %}} Gateway Application Pool. This should be entered, and then hit `Enter`. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. + +### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md">}} + +## Preserve installation files + +Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates. + +## Next Steps? + +1. [Setup Gateway][] + +[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} +[Configure CORTEX Gateway Installation Script]: {{< ref "#configure-cortex-gateway-installation-script" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScriptNew" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirementsNew" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Get CORTEX Gateway Application Pool User]: {{< ref "#get-cortex-gateway-application-pool-user" >}} +[Import Certificate Manually]: {{< ref "#import-certificate-manually" >}} +[Import Root Certificate]: {{< ref path="#import-root-certificate" >}} +[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallApplicationServerNew" >}} +[Obtain a {{% ctx %}} licence file]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ObtainLicence" >}} +[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.SetupGatewayNew" >}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md new file mode 100644 index 000000000..a1de01556 --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md @@ -0,0 +1,10 @@ +--- +title: "Post-Installation" +linkTitle: "Post-Installation" +description: "Information about the steps required to be completed after the installation has finished." +weight: 50 +--- + +This guide describes how to perform the steps to verify the installation of {{% ctx %}} and perform final configuration. Please ensure that the [Installation][] has been completed before starting this section. + +[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Installation" >}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md new file mode 100644 index 000000000..d2534a8d2 --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} for the first time." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to try out a new {{% ctx %}} installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. + +## Test Debugging Flows + + +## Test Publishing Production Flows + + +## Test Executing Production Flows + diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md new file mode 100644 index 000000000..2269a2229 --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md @@ -0,0 +1,25 @@ +--- +title: "Pre-Installation" +linkTitle: "Pre-Installation" +description: "Information about the steps required to be completed prior to starting the installation." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to perform the steps required before starting the installation of the {{% ctx %}} Configuration Portal. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the Web Application Server: + * Cortex Innovation {{< version >}} - Configuration Portal.zip + + {{< alert title="Important" color="warning" >}}Only the files for the version to be installed should be in the containing folder. There should not be any other versions of the files in this folder or a subfolder.{{% /alert %}} + +1. Extract the `Cortex Innovation {{< version >}} - Configuration Portal.zip` file to a folder with the same name. + +## Next Steps? + +1. [Installation][] + +[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation.MainDoc" >}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md new file mode 100644 index 000000000..bfb09f538 --- /dev/null +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md @@ -0,0 +1,62 @@ +--- +title: "Requirements" +linkTitle: "Requirements" +description: "Information about the requirements required." +weight: 10 +--- + +# {{% param title %}} + +The requirements for a server installation of the {{% ctx %}} Configuration Portal are laid out in this guide. These must be considered before undertaking installation. + +## Domain Requirements + +The server must be on a domain and cannot be a domain controller. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|------------------------|-----------|---------------------|-----------------| +| Windows Server 2016 | | {{% ctx %}} v2025.3 | To be evaluated | +| Windows Server 2019 | ✓ | {{% ctx %}} v2025.3 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2025.3 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server. + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Security Requirements + +### Installation User + +A domain user with the necessary administrative permissions to log on to the Configuration Portal host server via Remote Desktop and execute PowerShell scripts. + +### PowerShell User + +A service user with the necessary permissions to execute PowerShell scripts on the Configuration Portal host server, and has right to query Active Directory. + +### IIS Application Pool User + +For the Configuration Portal, a domain user must be available to run the IIS Application Pool. This user must be given `Log on as a service` and `Log on as a batch job` permissions otherwise the Application Pool will not be able to run. Information about how to do this will be given during installation. + +### Domain Groups + +The Active Directory groups to which access to the Configuration Portal should be granted must be known prior to installation. + +## Next Steps? + +1. [Pre-Installation][] + +[Pre-Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PreInstallation" >}} diff --git a/data/urls.toml b/data/urls.toml index 0a955f718..ad8d2ca2e 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -539,6 +539,10 @@ ConfigureAlloy = "/docs/getting-started/on-premise/add-observability-to-innovation/grafana/install-alloy/configure-alloy" [Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallAlloy.InstallAlloy] MainDoc = "/docs/getting-started/on-premise/add-observability-to-innovation/grafana/install-alloy/install-alloy" + [Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex] + PreInstallation = "/docs/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation" + [Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation] + MainDoc = "/docs/getting-started/on-premise/add-configuration-portal-to-cortex/installation" [Cortex.GettingStarted.Cloud] MainDoc = "/docs/getting-started/cloud" [Cortex.GettingStarted.Cloud.AddObservabilityToInnovation] From e2cdad87da8b8b8b73375336c1a4ce7aefa84ea3 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Tue, 7 Oct 2025 14:38:53 +0100 Subject: [PATCH 02/19] initial version of the doc with all steps --- .../installation/_index.md | 286 ++++++++++-------- .../post-installation/_index.md | 4 +- .../post-installation/try-it-out.md | 66 +++- .../requirements.md | 4 - data/urls.toml | 2 + 5 files changed, 229 insertions(+), 133 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md index dd9577a0f..809c151f2 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md @@ -1,7 +1,7 @@ --- -title: "Install the Web Application Server" -linkTitle: "Install Web Application Server" -description: "Information about installing the Web Application Server." +title: "Install the Configuration Portal" +linkTitle: "Install Configuration Portal" +description: "Information about installing the Configuration Portal." weight: 40 --- @@ -155,163 +155,203 @@ Keep a note of the selected groups, as they will be required when setting the ac ### Create the {{% ctx %}} Configuration Portal Website +#### Copy and configure relevant files + On the Web Application Server: 1. Open the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted. 1. From there, open the `Cortex Configuration Portal` folder. -1. Open the `Cortex.Configuration.Portal.zip` file and extract the contents to where the website is to be installed +1. Open the `Cortex.Configuration.Portal.zip` file and extract the contents to where the website is to be installed. {{< alert type="note" title="Note" >}} Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` {{< /alert >}} 1. Copy the `web.config` and `appsettings.json` files from the `Cortex Configuration Portal` folder to the root of the extracted website folder. +1. Once copied, open the `appsettings.json` file then update the following parameters only: + | Name | Description | Example | + |--------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------| + | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | + | UseOAuth | Whether to use OAuth for authentication. | `true` | + | CortexUrl | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | + | CortexPort | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | + | CortexTenant | The tenant defining the scope of the Configuration storage and user sessions at the tenant level. | `"default"` | + | CortexEnvironment | The system defining the scope of the Configuration storage and user sessions at the system level. | `"default"` | + | ConfigManagementPackageName | The name of the package containing the flows used by the {{% ctx %}} Configuration Portal. | `CORTEXConfigurationManagement` | + | ConfigManagementPackageVersion | The version of the package to be used. | `""` | + | ConfigPortalPath | The folder name containing the {{% ctx %}} Configuration Portal. | `"ConfigurationPortal"` | + | ConfigPortalPort | The port to communicate with the {{% ctx %}} Configuration Portal. | `"4443"` | + | ConfigPortalUrl | The {{% ctx %}} Configuration Portal base URL. | `"https://cortexwebapp-machine.domain.com"` | +This should look similar to the following: +``` json +{ + "ApplicationName": "CortexConfigurationDev", + "UseOAuth": true, + + "CortexUrl": "https://cortexapp-machine.domain.com", + "CortexPort": "8722", + "CortexTenant": "default", + "CortexEnvironment": "default", + + "ConfigManagementPackageName": "CORTEXConfigurationManagement", + "ConfigManagementPackageVersion": "", + "ConfigPortalPath": "ConfigurationPortal", + "ConfigPortalPort": "", + "ConfigPortalUrl": "https://cortexwebapp-machine.domain.com", + + "FlowAuthBase64": "", + "TableBreakpoint": "1224", + "MobileBreakpoint": 769, + "ConfigSet": true +} +``` +#### Create the application +On the Web Application Server: +1. Open IIS. +1. Expand the current node, then `Sites`. +1. Locate the website that contains the `Cortex` application, typically named `Cortex`. +1. To convert the {{% ctx %}} Configuration Portal folder to an Application: + 1. Locate the `ConfigurationPortal` folder + 1. Right-click on the `ConfigurationPortal`. + 1. Click `Convert to Application`. + 1. Change the Application pool to be the same as `Cortex Gateway`, typically named `Cortex Gateway`. + 1. Click `OK`. +1. Enable directory browsing: + 1. Select the newly created `ConfigurationPortal` application. + 1. Double-click on `Directory Browsing` under the `IIS` section. + 1. Ensure that it is Enabled in the `Actions` panel on the right-hand side. +{{< alert type="note" title="Note" >}} +If it is not, click on the `Enable` button. +{{< /alert >}} +### Configure the {{% ctx %}} Configuration Portal Website +#### Configure the Redirect rule +On the Web Application Server: +1. Navigate to the `Cortex` website directory, typically `C:\inetpub\wwwroot\Cortex`. +1. If a `web.config` file is present, and a `Redirect Cortex to gateway` rule present, add a condition as follows: + ``` xml + + ``` +1. Save the file. +#### CORS Configuration +{{< alert type="note" title="Note" >}} +These steps are only needed if the {{% ctx %}} Interaction Portal is not already installed. +{{< /alert >}} +{{< alert color="warning" title="Important" >}} +These steps will need to be repeated on all Application Servers. +{{< /alert >}} +On the Application Server: +1. Navigate to `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.` +{{< alert type="note" title="Note" >}} +`` and `` will depend on how the node was configured during the installation of {{% ctx %}}. +{{< /alert >}} +1. Open the `appsettings.json` file. +1. Under the `Cors` section, update the following parameters: + | Name | Description | Example | + |-------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------| + | Enabled | Whether CORS is enabled, this MUST be set to `true`. | `true` | + | AllowedOrigins | List of Strings containing all the allowed origins. | `[ "https://*.domain.com", "https://cortexwebapp-machine.domain.com" ]` | + | AllowCredentials | Whether to allow credentials, this MUST be set to `true`. | `true` | + | AllowWildCardSubDomains | Whether to allow wildcard subdomains, this MUST be set to `true`. | `true` | +The CORS section should look similar to the following: +``` json +"Cors": { + "Enabled": true, + "AllowedOrigins": [ + "https://*.ad.cortex.uk", + "https://*.appgyver.com" + ], + "AllowedRequestHeaders": [ + "*" + ], + "AllowedResponseHeaders": [ + ], + "AllowedMethods": [ + "*" + ], + "AllowCredentials": true, + "AllowWildcardSubdomains": true, + "PreflightMaxAgeInMs": 5000 +}, +``` +1. Save the file. +#### Restart the code package +{{< alert color="warning" title="Important" >}} +These steps will need to be repeated on all Application Servers. +{{< /alert >}} +On the Application Server: +1. Navigate to the Service Fabric Explorer, typically `http://localhost:9080/Explorer`. +1. Restart the `ApiGatewayPkg`: + 1. Expand the `Nodes` + 1. Select the current node + 1. Expand `fabric:/Core/Services` + 1. Expand the `ApiGatewayPkg` service package + 1. Expand `Code Packages` + 1. Hover over `Code` and click on the `▼` button + 1. Click `Restart` +{{< alert type="note" title="Note" >}} +It may take a few minutes for the `Code` package to restart. +{{< /alert >}} +### Set up User Access Control +On the Web Application Server: - - - - - - - - - -1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. -1. Configure the script according to the details given below: - - ```powershell - .\Cortex.Install.Gateway.ps1 ` - -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` - -FeatureFlags "InnovationId" ` - -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" ` - -ServiceFabricUsingSelfSignedCertificates $false ` - -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` - -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` - -DotNetFlowDebuggerEndpoint 'https://server.domain.com:8722/api/' ` - -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` - -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` - -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` - -GatewayApplicationPoolUsername "Domain\Username" ` - -WebRootFolder "C:\inetpub\wwwroot" ` - -WebsitePort "443" ` - -ImportCertificate $false ` - -CertificateFilePath "C:\Install\Certificate.pfx" ` - -CertificateFriendlyName "CertificateName" ` - -ConfigureSiteRedirect $true ` - -ApplySecurityMeasures $true ` - -UsingWindowsDefender $false ` - -AcceptEULA:$AcceptEula ` - *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" - ``` - - {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirementsNew" title="Generate Encryption Key" >}} steps.{{% /alert %}} - - | Name | Description | - |-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | - | `FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Obtain a {{% ctx %}} licence file][] step during Pre-Installation, if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will set the `FeatureFlags` value in the {{% ctx %}} Gateway web.config. | - | `ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the server. The port should be specified as `8722` and there must be a trailing slash, e.g. `https://server.domain.com:8722/`.

This will set the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config. | - | `ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Server][Configure Installation Script], `$true` if you used self-signed certificates.

This will set the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config. | - | `ServiceFabricApiGatewayBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | - | `ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | - | `DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Web Application Server.

This will set the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config. | - | `DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | - | `DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | - | `DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will set the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config. | - | `GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that should be used to run the {{% ctx %}} Gateway application pool as configured in [Get {{% ctx %}} Gateway Application Pool User][Get CORTEX Gateway Application Pool User]. | - | `WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`. | - | `WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`. | - | `ImportCertificate` | Change this from `$true` to `$false` if you do not require the certificate to be imported as part of the installation process.

Note that if this is changed to `$false` you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation. | - | `CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged but you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation. | - | `CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false` this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate. | - | `ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created {{% ctx %}} site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`. | - | `ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process. | - | `UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443). | - | `AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | - | `FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | - -1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. - -### Install {{% ctx %}} Gateway - -1. Open a Windows PowerShell (x64) window as administrator. -1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: - - ```powershell - cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" - ``` - -1. Type the following command into PowerShell: - - ```powershell - .\Cortex.Innovation.Install.Gateway.ps1 - ``` - -1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: - - ```powershell - .\.ps1 -AcceptEULA +1. Open a `Windows PowerShell ISE` (x64) window as administrator. +1. Change the location to where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted, inside the `Cortex Configuration Portal` folder, e.g. `cd "C:\Install\Cortex Innovation {{< version >}} - Configuration Portal\Cortex Configuration Portal"`. +1. In the script section, copy the following script: + + ``` powershell + \Deploy.Cortex.Configuration.Portal.ps1 ` + -URL "https://cortexapp-machine.domain.com" ` + -Port "8722" ` + -Username "BasicAuthUser" ` + -Password "" ` + -Tenant "default" ` + -Environment "default" ` + -adminAdGroups @("Domain Admins Group") ` + -userAdGroups @("Domain Users Group") ` + -ApplicationName "CortexConfigurationDev" ``` -1. Run the PowerShell command to install {{% ctx %}} Gateway. -1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. -1. A prompt will appear to enter the password for the user specified to run the {{% ctx %}} Gateway Application Pool. This should be entered, and then hit `Enter`. -1. Check that there have been no errors in the script; these would appear in red in the console. - - If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. - - If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. - -1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). -1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. - -### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User - -{{< section "/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md">}} - -## Preserve installation files - -Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates. +1. Update the following parameters: + | Name | Description | Example | + |-----------------|------------------------------------------------------------------------------------------------|------------------------------------------| + | URL | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | + | Port | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | + | Username | The username used to authenticate against the Application Server APIGateway. | `"BasicAuthUser"` | + | Password | The password for the username specified for `Username`. | `""` | + | Tenant | The tenant defining the scope of the Configuration storage and user sessions. | `"default"` | + | Environment | The system defining the scope of the Configuration storage and user sessions. | `"default"` | + | adminAdGroups | An array of Active Directory groups that should have admin access to the Configuration Portal. | `@("Domain Admins Group")` | + | userAdGroups | An array of Active Directory groups that should have user access to the Configuration Portal. | `@("Domain Users Group")` | + | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | + +1. Once updated, run the script and verify that it completes without errors. ## Next Steps? -1. [Setup Gateway][] - -[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} -[Configure CORTEX Gateway Installation Script]: {{< ref "#configure-cortex-gateway-installation-script" >}} -[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScriptNew" >}} -[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} -[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} -[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirementsNew" >}} -[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} -[Get CORTEX Gateway Application Pool User]: {{< ref "#get-cortex-gateway-application-pool-user" >}} -[Import Certificate Manually]: {{< ref "#import-certificate-manually" >}} -[Import Root Certificate]: {{< ref path="#import-root-certificate" >}} -[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallApplicationServerNew" >}} -[Obtain a {{% ctx %}} licence file]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ObtainLicence" >}} -[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} -[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.SetupGatewayNew" >}} +1. [Try it out][] + +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md index a1de01556..fa805caed 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md @@ -5,6 +5,6 @@ description: "Information about the steps required to be completed after the ins weight: 50 --- -This guide describes how to perform the steps to verify the installation of {{% ctx %}} and perform final configuration. Please ensure that the [Installation][] has been completed before starting this section. +This guide describes how to perform the steps to verify the installation of the {{% ctx %}} Configuration Portal. Please ensure that the [Installation][] has been completed before starting this section. -[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Installation" >}} +[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation.MainDoc" >}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md index d2534a8d2..56073ea5c 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -7,13 +7,71 @@ weight: 10 # {{% param title %}} -This guide describes how to try out a new {{% ctx %}} installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. +This guide describes how to try out a new {{% ctx %}} Configuration Portal installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. -## Test Debugging Flows +## Test Access to Configuration Portal +1. Open a web browser and navigate to the URL of the Configuration Portal. This is typically in the format `http:///ConfigurationPortal`. +1. Log in using your Active Directory credentials. Ensure that the account you are using is part of one of the Active Directory groups specified during installation. -## Test Publishing Production Flows +## Test adding a new Configuration Container and Data +1. Once logged in, you should be able to add a container by doing as follows: + 1. Click on the `+ Add Container` button. + 1. Fill in the `Name` field with the value `TestContainer`. + 1. Click `Confirm` to create the container. +1. Using the values of the table below, add a some data to the created container as follows: +| Name | Value | Type | +|---------------|------------------------|---------| +| `TestText` | `This is a test value` | Text | +| `TestInteger` | `22` | Integer | +| `TestBool` | `true` | Bool | +| `TestObject` | `{"test":22}` | Object | + 1. Click the container you just created. + 1. For each of row, do the following: + 1. Click on the `+ Add Parameter/Value Pair` button. + 1. Fill in the `Name`. + 1. Select the `Type`. + 1. Click `CONFIRM` to add the parameter/value pair. -## Test Executing Production Flows +## Test reading data from Configuration Portal +1. Open a web browser and navigate to the URL of {{% ctx %}} Gateway. This is typically in the format `http:///gateway`. +1. Log in using your Active Directory credentials. +1. Click on the `Dev` charms, then search for `CM-Get-Config`. +1. Click on the flow `CM-Get-Config`. +1. Once the flow opened, in the Settings tab, set the `ContainersNames` field to `["TestContainer"]`. +1. Add a breakpoint to the `End Flow` block. +1. Click on the `Run` button to execute the flow. +1. When the flow hits the breakpoint, click on the `Variables` tab. +1. Select the variable `ConfigItems`. +1. Verify that the variable contains the data you added in the previous section, it should look like the following: + +``` json +{ + "Parameters": [ + { + "ParamID": "e440c1ee-29ee-4b70-9660-60f518a10339", + "ParamName": "TestInteger", + "ParamValue": 22 + }, + { + "ParamID": "b0cedd5c-e832-4fd2-8292-462be9b0ab71", + "ParamName": "TestText", + "ParamValue": "This is a test value" + }, + { + "ParamID": "5f760269-41e4-4f99-8b82-96ac1ccfbb49", + "ParamName": "TestBool", + "ParamValue": true + }, + { + "ParamID": "e967217d-4ca0-4a77-b357-2b3ccf1335d7", + "ParamName": "TestObject", + "ParamValue": { + "test": 22 + } + } + ] +} +``` diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md index bfb09f538..6659c6158 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md @@ -47,10 +47,6 @@ A domain user with the necessary administrative permissions to log on to the Con A service user with the necessary permissions to execute PowerShell scripts on the Configuration Portal host server, and has right to query Active Directory. -### IIS Application Pool User - -For the Configuration Portal, a domain user must be available to run the IIS Application Pool. This user must be given `Log on as a service` and `Log on as a batch job` permissions otherwise the Application Pool will not be able to run. Information about how to do this will be given during installation. - ### Domain Groups The Active Directory groups to which access to the Configuration Portal should be granted must be known prior to installation. diff --git a/data/urls.toml b/data/urls.toml index ad8d2ca2e..ca0f00972 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -543,6 +543,8 @@ PreInstallation = "/docs/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation" [Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation] MainDoc = "/docs/getting-started/on-premise/add-configuration-portal-to-cortex/installation" + [Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation] + TryItOut = "/docs/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out" [Cortex.GettingStarted.Cloud] MainDoc = "/docs/getting-started/cloud" [Cortex.GettingStarted.Cloud.AddObservabilityToInnovation] From 2472ae564be1796392d121c61422553fe2f179b4 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Wed, 8 Oct 2025 14:12:19 +0100 Subject: [PATCH 03/19] after first run --- .../_index.md | 2 +- .../installation/_index.md | 72 ++++++++++--------- .../requirements.md | 4 ++ 3 files changed, 44 insertions(+), 34 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md index dbbf1e8ca..0b2764726 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md @@ -6,5 +6,5 @@ weight: 50 --- {{< alert title="Important" color="warning" >}} -This guide currently only describe how to add the {{% ctx %}} Configuration Portal to an existing Web Application Server. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +This guide currently only describe how to add the {{% ctx %}} Configuration Portal to an existing Web Application Server with {{% ctx %}} Gateway installed. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. {{% /alert %}} diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md index 809c151f2..709375580 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md @@ -23,9 +23,10 @@ To import the flows, perform the following steps: 1. `Configuration.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Configuration Portal`. 1. `Interaction.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Interaction Portal`. 1. `User Access Management.Flows.studiopkg`, which can be found in the folder named `User Access Management`. -1. Once imported, Set up the access to these flows using Studio Authorisation. +1. Once imported, set up the access to these flows using Studio Authorisation. + {{< alert type="note" title="Note" >}} -Once the flows are imported, they should be available from the ‘Dev’ charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing +Once the flows are imported, they should be available from the ‘Dev’ charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing. {{< /alert >}} ### Configure the flows @@ -33,6 +34,7 @@ Once the flows are imported, they should be available from the ‘Dev’ charms #### User Access Management flow 1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `UAM-Get-Config` +1. Open the flow. 1. Click on the first `Set Variable` block to show the properties. 1. Within the value field, update the following parameters only: | Name | Description | Example | @@ -40,7 +42,7 @@ Once the flows are imported, they should be available from the ‘Dev’ charms | PowerShellDetails.Username | The username of an account that can run PowerShell commands on all {{% ctx %}} servers, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator across the {{% ctx %}} servers.{{< /alert >}} | `"ctx_serviceuser"` | | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | - | PowerShellDetails.Host | The FQDN of the host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This can be `Environment.MachineName` to use the current node executing the flow.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `Environment.MachineName` | + | PowerShellDetails.Host | The host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This can be `Environment.MachineName` to use the current node executing the flow.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` or `Environment.MachineName` | | PowerShellDetails.Port | The PowerShell port. | `5985` | | PowerShellDetails.SSL | Whether to use SSL for the PowerShell command. | `false` | | RecursiveAccessControl | Whether child user groups should inherit access control granted to parents. | `false` | @@ -82,6 +84,7 @@ This should look similar to the following: #### Configuration Management flow 1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `CM-Config-Settings` +1. Open the flow. 1. Click on the first `Set Variable` block to show the properties. 1. Within the value field, update the following parameters only: | Name | Description | Example | @@ -89,9 +92,9 @@ This should look similar to the following: | PowerShellDetails.Username | The username of an account that can run PowerShell commands on the host specified for `PowerShellDetails.Host`, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator on the targeted Host.{{< /alert >}} | `"ctx_serviceuser"` | | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | - | PowerShellDetails.Host | The FQDN of the host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This must target a specific {{% ctx %}} Server.{{< /alert >}} | `"cortexapp-machine.domain.com"` | + | PowerShellDetails.Host | The host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This must target a specific {{% ctx %}} Server.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` | | PowerShellDetails.Port | The PowerShell port. | `5985` | - | CortexInteractionPortalPath | The path to the Cortex Interaction Portal. | `@"C:\inetpub\wwwroot\Cortex\ConfigurationPortal"` | + | CortexInteractionPortalPath | The path to the Cortex Configuration Portal. | `@"C:\inetpub\wwwroot\Cortex\ConfigurationPortal"` | | ConfigurationExportsFolder | The folder containing the configuration being exported. | `@"ConfigurationModule\Exports"` | | ConfigurationImportsFolder | The folder containing the configuration being imported. | `@"ConfigurationModule\Imports"` | | ConfigurationBackupsFolder | The folder containing the configuration backups if scheduled. | `@"ConfigurationModule\Backups"` | | `false` | @@ -149,6 +152,8 @@ This should look similar to the following: 1. Once published: 1. Select the `Authorisation` tab 1. Select the groups that should be able to execute this package + 1. Click `Save` + {{< alert type="note" title="Note" >}} Keep a note of the selected groups, as they will be required when setting the access control for the {{% ctx %}} Configuration Portal. {{< /alert >}} @@ -161,12 +166,12 @@ On the Web Application Server: 1. Open the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted. 1. From there, open the `Cortex Configuration Portal` folder. -1. Open the `Cortex.Configuration.Portal.zip` file and extract the contents to where the website is to be installed. +1. Extract the contents of the `Cortex.Configuration.Portal.zip` file to where the website is to be installed. {{< alert type="note" title="Note" >}} Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` {{< /alert >}} -1. Copy the `web.config` and `appsettings.json` files from the `Cortex Configuration Portal` folder to the root of the extracted website folder. -1. Once copied, open the `appsettings.json` file then update the following parameters only: +1. Copy the `web.config` and `config.json` files from the `Cortex Configuration Portal` folder to the root of the extracted website folder. +1. Once copied, open the `config.json` file then update the following parameters only: | Name | Description | Example | |--------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------| | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | @@ -254,7 +259,7 @@ These steps will need to be repeated on all Application Servers. On the Application Server: -1. Navigate to `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.` +1. Navigate to `C:\ProgramData\SF\.\Fabric\work\Applications\Cortex.Innovation.Core_App0\ApiGatewayPkg.Code.` {{< alert type="note" title="Note" >}} `` and `` will depend on how the node was configured during the installation of {{% ctx %}}. {{< /alert >}} @@ -267,30 +272,31 @@ On the Application Server: | AllowCredentials | Whether to allow credentials, this MUST be set to `true`. | `true` | | AllowWildCardSubDomains | Whether to allow wildcard subdomains, this MUST be set to `true`. | `true` | -The CORS section should look similar to the following: - -``` json -"Cors": { - "Enabled": true, - "AllowedOrigins": [ - "https://*.ad.cortex.uk", - "https://*.appgyver.com" - ], - "AllowedRequestHeaders": [ - "*" - ], - "AllowedResponseHeaders": [ - ], - "AllowedMethods": [ - "*" - ], - "AllowCredentials": true, - "AllowWildcardSubdomains": true, - "PreflightMaxAgeInMs": 5000 -}, -``` + The CORS section should look similar to the following: + + ``` json + "Cors": { + "Enabled": true, + "AllowedOrigins": [ + "https://*.domain.com", + "https://*.appgyver.com" + ], + "AllowedRequestHeaders": [ + "*" + ], + "AllowedResponseHeaders": [ + ], + "AllowedMethods": [ + "*" + ], + "AllowCredentials": true, + "AllowWildcardSubdomains": true, + "PreflightMaxAgeInMs": 5000 + }, + ``` 1. Save the file. +1. Repeat these steps for the appsettings.json file located in `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.`. #### Restart the code package @@ -301,7 +307,7 @@ These steps will need to be repeated on all Application Servers. On the Application Server: 1. Navigate to the Service Fabric Explorer, typically `http://localhost:9080/Explorer`. -1. Restart the `ApiGatewayPkg`: +1. Restart the `ApiGatewayPkg` by following these steps: 1. Expand the `Nodes` 1. Select the current node 1. Expand `fabric:/Core/Services` @@ -323,7 +329,7 @@ On the Web Application Server: 1. In the script section, copy the following script: ``` powershell - \Deploy.Cortex.Configuration.Portal.ps1 ` + .\Deploy.Cortex.Configuration.Portal.ps1 ` -URL "https://cortexapp-machine.domain.com" ` -Port "8722" ` -Username "BasicAuthUser" ` diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md index 6659c6158..fe1d18e2a 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md @@ -9,6 +9,10 @@ weight: 10 The requirements for a server installation of the {{% ctx %}} Configuration Portal are laid out in this guide. These must be considered before undertaking installation. +{{< alert color="warning" title="Important" >}} +The Configuration Portal must be installed on the Web Application Server where {{% ctx %}} Gateway is installed.For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +{{< /alert >}} + ## Domain Requirements The server must be on a domain and cannot be a domain controller. From c4890bc1ef7e4dd1ee07eab6814b5c7c895b4a55 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 09:30:32 +0100 Subject: [PATCH 04/19] fixes to doc --- .../installation/_index.md | 7 ------ .../post-installation/try-it-out.md | 24 +++++++++---------- 2 files changed, 12 insertions(+), 19 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md index 709375580..7a9bc8727 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md @@ -224,13 +224,6 @@ On the Web Application Server: 1. Click `Convert to Application`. 1. Change the Application pool to be the same as `Cortex Gateway`, typically named `Cortex Gateway`. 1. Click `OK`. -1. Enable directory browsing: - 1. Select the newly created `ConfigurationPortal` application. - 1. Double-click on `Directory Browsing` under the `IIS` section. - 1. Ensure that it is Enabled in the `Actions` panel on the right-hand side. -{{< alert type="note" title="Note" >}} -If it is not, click on the `Enable` button. -{{< /alert >}} ### Configure the {{% ctx %}} Configuration Portal Website diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md index 56073ea5c..1b0131545 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -20,19 +20,19 @@ This guide describes how to try out a new {{% ctx %}} Configuration Portal insta 1. Click on the `+ Add Container` button. 1. Fill in the `Name` field with the value `TestContainer`. 1. Click `Confirm` to create the container. +1. Click the container you just created. 1. Using the values of the table below, add a some data to the created container as follows: -| Name | Value | Type | -|---------------|------------------------|---------| -| `TestText` | `This is a test value` | Text | -| `TestInteger` | `22` | Integer | -| `TestBool` | `true` | Bool | -| `TestObject` | `{"test":22}` | Object | - 1. Click the container you just created. - 1. For each of row, do the following: - 1. Click on the `+ Add Parameter/Value Pair` button. - 1. Fill in the `Name`. - 1. Select the `Type`. - 1. Click `CONFIRM` to add the parameter/value pair. + | Name | Value | Type | + |---------------|------------------------|---------| + | `TestText` | `This is a test value` | Text | + | `TestInteger` | `22` | Integer | + | `TestBool` | `true` | Bool | + | `TestObject` | `{"test":22}` | Object | + + 1. Click on the `+ Add Parameter/Value Pair` button. + 1. Fill in the `Name` and the `Value`. + 1. Select the `Type`. + 1. Click `CONFIRM` to add the parameter/value pair. ## Test reading data from Configuration Portal From 740794a0d3713722227d5dc16157c78d8edd9eee Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 10:48:17 +0100 Subject: [PATCH 05/19] first changes --- .../{installation/_index.md => installation.md} | 2 +- .../add-configuration-portal-to-cortex/pre-installation.md | 2 -- .../add-configuration-portal-to-cortex/requirements.md | 6 +++--- 3 files changed, 4 insertions(+), 6 deletions(-) rename content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/{installation/_index.md => installation.md} (99%) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md similarity index 99% rename from content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md rename to content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 7a9bc8727..db00ad4aa 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation/_index.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -1,7 +1,7 @@ --- title: "Install the Configuration Portal" linkTitle: "Install Configuration Portal" -description: "Information about installing the Configuration Portal." +description: "Information about installing the {{% ctx %}} Configuration Portal." weight: 40 --- diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md index 2269a2229..e387662cf 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md @@ -14,8 +14,6 @@ This guide describes how to perform the steps required before starting the insta 1. Copy the following artefacts to a folder on the Web Application Server: * Cortex Innovation {{< version >}} - Configuration Portal.zip - {{< alert title="Important" color="warning" >}}Only the files for the version to be installed should be in the containing folder. There should not be any other versions of the files in this folder or a subfolder.{{% /alert %}} - 1. Extract the `Cortex Innovation {{< version >}} - Configuration Portal.zip` file to a folder with the same name. ## Next Steps? diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md index fe1d18e2a..86b15c071 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md @@ -7,10 +7,10 @@ weight: 10 # {{% param title %}} -The requirements for a server installation of the {{% ctx %}} Configuration Portal are laid out in this guide. These must be considered before undertaking installation. +The requirements for an installation of the {{% ctx %}} Configuration Portal are laid out in this guide. These must be considered before undertaking installation. {{< alert color="warning" title="Important" >}} -The Configuration Portal must be installed on the Web Application Server where {{% ctx %}} Gateway is installed.For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +The Configuration Portal must be installed on the Web Application Server where {{% ctx %}} Gateway is installed. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. {{< /alert >}} ## Domain Requirements @@ -49,7 +49,7 @@ A domain user with the necessary administrative permissions to log on to the Con ### PowerShell User -A service user with the necessary permissions to execute PowerShell scripts on the Configuration Portal host server, and has right to query Active Directory. +A service user with the necessary permissions to execute PowerShell scripts on the {{% ctx %}} platform, and has right to query Active Directory. ### Domain Groups From 9436b156f46c98cc10d4a465a1b3eff2bf084a3d Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 10:56:45 +0100 Subject: [PATCH 06/19] added link and re-wording of some part of install --- .../add-configuration-portal-to-cortex/installation.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index db00ad4aa..87f0c31f5 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -17,13 +17,13 @@ The {{% ctx %}} Configuration Portal calls a set of flows to validate log-in cre To import the flows, perform the following steps: -1. Log into the {{% ctx %}} Gateway that was installed within the CORTEX Web Application Server. +1. Login to the {{% ctx %}} Gateway that is installed on the Web Application Server. 1. In {{% ctx %}} Gateway, click `Admin`, then `Studio Import`. -1. Import the following Studio packages which can be found in the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted: +1. Import the following Studio packages which can be found in the folder where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to: 1. `Configuration.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Configuration Portal`. 1. `Interaction.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Interaction Portal`. 1. `User Access Management.Flows.studiopkg`, which can be found in the folder named `User Access Management`. -1. Once imported, set up the access to these flows using Studio Authorisation. +1. Once imported, grant `Edit` permissions to these flows using [Studio Authorisation][]. {{< alert type="note" title="Note" >}} Once the flows are imported, they should be available from the ‘Dev’ charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing. @@ -354,3 +354,4 @@ On the Web Application Server: 1. [Try it out][] [Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} +[Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation" >}} From 1192453387ed21f719e1ac9fd201909bcb009da1 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 10:57:49 +0100 Subject: [PATCH 07/19] add maindoc to link --- .../add-configuration-portal-to-cortex/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 87f0c31f5..1714c96cf 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -354,4 +354,4 @@ On the Web Application Server: 1. [Try it out][] [Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} -[Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation" >}} +[Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation.MainDoc" >}} From 84355db452cf613c52ad450c111a01c81bbd3d6b Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 11:14:25 +0100 Subject: [PATCH 08/19] Added missing flow and fixed some typoes --- .../installation.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 1714c96cf..24f04baa0 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -26,14 +26,14 @@ To import the flows, perform the following steps: 1. Once imported, grant `Edit` permissions to these flows using [Studio Authorisation][]. {{< alert type="note" title="Note" >}} -Once the flows are imported, they should be available from the ‘Dev’ charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing. +Once the flows are imported, they should be available from the `Dev` charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing. {{< /alert >}} ### Configure the flows #### User Access Management flow -1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `UAM-Get-Config` +1. Within {{% ctx %}} Gateway, open the `Dev` charm then search for `UAM-Get-Config` 1. Open the flow. 1. Click on the first `Set Variable` block to show the properties. 1. Within the value field, update the following parameters only: @@ -83,7 +83,7 @@ This should look similar to the following: #### Configuration Management flow -1. Within {{% ctx %}} Gateway, open the `Dev` charms then search for `CM-Config-Settings` +1. Within {{% ctx %}} Gateway, open the `Dev` charm then search for `CM-Config-Settings` 1. Open the flow. 1. Click on the first `Set Variable` block to show the properties. 1. Within the value field, update the following parameters only: @@ -92,7 +92,7 @@ This should look similar to the following: | PowerShellDetails.Username | The username of an account that can run PowerShell commands on the host specified for `PowerShellDetails.Host`, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator on the targeted Host.{{< /alert >}} | `"ctx_serviceuser"` | | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | - | PowerShellDetails.Host | The host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This must target a specific {{% ctx %}} Server.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` | + | PowerShellDetails.Host | The host executing the PowerShell commands. | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` or `Environment.MachineName` | | PowerShellDetails.Port | The PowerShell port. | `5985` | | CortexInteractionPortalPath | The path to the Cortex Configuration Portal. | `@"C:\inetpub\wwwroot\Cortex\ConfigurationPortal"` | | ConfigurationExportsFolder | The folder containing the configuration being exported. | `@"ConfigurationModule\Exports"` | @@ -126,7 +126,7 @@ This should look similar to the following: ### Create the Configuration Management Package -1. Within {{% ctx %}} Gateway, open the `Admin` charms then click on `Packages` +1. Within {{% ctx %}} Gateway, open the `Admin` charm then click on `Packages` 1. Click on `Add Package Definition` then: 1. Set the `Package Name` to `CORTEXConfigurationManagement` 1. Select the flows and groups as follows: @@ -147,6 +147,9 @@ This should look similar to the following: ------ [X] `UAM-Check-Access-Level` ------ [X] `UAM-Get-Config` ------ [X] `UAM-Validate-Token` + [ ] `Generic Flow Library` + --- [ ] `PowerShell` + ------ [X] `Execute-PowerShell-Script` 1. Click `Save` 1. Once saved, click `Publish` 1. Once published: From 4d13a15c7ffa448a14ec7c75d5717fcd8d4274d6 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 11:47:05 +0100 Subject: [PATCH 09/19] added notes etc --- .../installation.md | 5 ++++- .../post-installation/try-it-out.md | 16 ++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 24f04baa0..d76d4b284 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -318,6 +318,10 @@ It may take a few minutes for the `Code` package to restart. ### Set up User Access Control +{{< alert color="warning" title="Important" >}} +The {{% ctx %}} Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when allocating access to the portal, it is advised that access is limited following the practice of least privilege. +{{< /alert >}} + On the Web Application Server: 1. Open a `Windows PowerShell ISE` (x64) window as administrator. @@ -349,7 +353,6 @@ On the Web Application Server: | adminAdGroups | An array of Active Directory groups that should have admin access to the Configuration Portal. | `@("Domain Admins Group")` | | userAdGroups | An array of Active Directory groups that should have user access to the Configuration Portal. | `@("Domain Users Group")` | | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | - 1. Once updated, run the script and verify that it completes without errors. ## Next Steps? diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md index 1b0131545..69f6ef9d6 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -34,6 +34,22 @@ This guide describes how to try out a new {{% ctx %}} Configuration Portal insta 1. Select the `Type`. 1. Click `CONFIRM` to add the parameter/value pair. +{{< alert type="note" title="Note" >}} +The CORTEX Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. We recommend that any sensitive data is {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} before it is added to the portal. +{{< /alert >}} + +## Test exporting an existing Container + +1. You should be able to export a container by doing as follows: + 1. Tick the `Export` checkbox next to the container you created in the previous section. + 1. Click on the `Export Containers` button. + +The file should be downloaded to your computer. + +{{< alert type="note" title="Note" >}} +Once you have confirmed the exported file contains the expected data, it is recommended to delete it. +{{< /alert >}} + ## Test reading data from Configuration Portal 1. Open a web browser and navigate to the URL of {{% ctx %}} Gateway. This is typically in the format `http:///gateway`. From 837a88ea4a9feb65e5e4a62ce5d5cb14b9c943e7 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 12:09:00 +0100 Subject: [PATCH 10/19] changed wording for applicationame --- .../add-configuration-portal-to-cortex/installation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index d76d4b284..77c7fdf5c 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -167,17 +167,17 @@ Keep a note of the selected groups, as they will be required when setting the ac On the Web Application Server: -1. Open the folder where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted. -1. From there, open the `Cortex Configuration Portal` folder. +1. Open the folder where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to. +1. Open the `Cortex Configuration Portal` folder. 1. Extract the contents of the `Cortex.Configuration.Portal.zip` file to where the website is to be installed. {{< alert type="note" title="Note" >}} Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` {{< /alert >}} -1. Copy the `web.config` and `config.json` files from the `Cortex Configuration Portal` folder to the root of the extracted website folder. -1. Once copied, open the `config.json` file then update the following parameters only: +1. Copy the `web.config` and `config.json` files from the `Cortex Configuration Portal` folder opened in step 2 to the root of the extracted content in step 3, e.g. `C:\inetpub\wwwroot\Cortex\ConfigurationPortal`. +1. Once copied, open the `config.json` file and update the following parameters only: | Name | Description | Example | |--------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------| - | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | + | ApplicationName | The name of the application, this will be used for referencing the relevant configuration data. | `"CortexConfigurationDev"` | | UseOAuth | Whether to use OAuth for authentication. | `true` | | CortexUrl | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | | CortexPort | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | From 0087dd35f3761cbc8f01fd0b723e3d29461e35f5 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 12:10:29 +0100 Subject: [PATCH 11/19] changed example --- .../add-configuration-portal-to-cortex/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 77c7fdf5c..342bb1f1f 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -186,7 +186,7 @@ Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` | ConfigManagementPackageName | The name of the package containing the flows used by the {{% ctx %}} Configuration Portal. | `CORTEXConfigurationManagement` | | ConfigManagementPackageVersion | The version of the package to be used. | `""` | | ConfigPortalPath | The folder name containing the {{% ctx %}} Configuration Portal. | `"ConfigurationPortal"` | - | ConfigPortalPort | The port to communicate with the {{% ctx %}} Configuration Portal. | `"4443"` | + | ConfigPortalPort | The port to communicate with the {{% ctx %}} Configuration Portal. | `"443"` | | ConfigPortalUrl | The {{% ctx %}} Configuration Portal base URL. | `"https://cortexwebapp-machine.domain.com"` | This should look similar to the following: @@ -204,7 +204,7 @@ This should look similar to the following: "ConfigManagementPackageName": "CORTEXConfigurationManagement", "ConfigManagementPackageVersion": "", "ConfigPortalPath": "ConfigurationPortal", - "ConfigPortalPort": "", + "ConfigPortalPort": "443", "ConfigPortalUrl": "https://cortexwebapp-machine.domain.com", "FlowAuthBase64": "", From 9b72c023ae928bee91b38b40d9d1bae6eb36f77e Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 12:17:24 +0100 Subject: [PATCH 12/19] change wording for Creating the application --- .../add-configuration-portal-to-cortex/installation.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 342bb1f1f..11932ea29 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -214,18 +214,20 @@ This should look similar to the following: } ``` +1. Save the file. + #### Create the application On the Web Application Server: 1. Open IIS. 1. Expand the current node, then `Sites`. -1. Locate the website that contains the `Cortex` application, typically named `Cortex`. +1. Expand the website that contains the `Cortex` application, typically named `Cortex`. 1. To convert the {{% ctx %}} Configuration Portal folder to an Application: 1. Locate the `ConfigurationPortal` folder - 1. Right-click on the `ConfigurationPortal`. + 1. Right-click on `ConfigurationPortal`. 1. Click `Convert to Application`. - 1. Change the Application pool to be the same as `Cortex Gateway`, typically named `Cortex Gateway`. + 1. Change the `Application pool` to be the same as [{{% ctx %}} Gateway][Gateway], typically named `Cortex Gateway`. 1. Click `OK`. ### Configure the {{% ctx %}} Configuration Portal Website @@ -361,3 +363,4 @@ On the Web Application Server: [Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} [Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation.MainDoc" >}} +[Gateway]: {{< url path="Cortex.Guides.Gateway.MainDoc" >}} From 42584e009f40d5e657330e75014556c7476e96d3 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 12:38:42 +0100 Subject: [PATCH 13/19] further changes for the CORS Configuration and restart of code package --- .../installation.md | 25 ++++++------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 11932ea29..e85a46589 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -222,7 +222,7 @@ On the Web Application Server: 1. Open IIS. 1. Expand the current node, then `Sites`. -1. Expand the website that contains the `Cortex` application, typically named `Cortex`. +1. Expand the website that contains the {{% ctx %}} application, typically named `Cortex`. 1. To convert the {{% ctx %}} Configuration Portal folder to an Application: 1. Locate the `ConfigurationPortal` folder 1. Right-click on `ConfigurationPortal`. @@ -255,12 +255,9 @@ These steps are only needed if the {{% ctx %}} Interaction Portal is not already These steps will need to be repeated on all Application Servers. {{< /alert >}} -On the Application Server: +On each Application Server: -1. Navigate to `C:\ProgramData\SF\.\Fabric\work\Applications\Cortex.Innovation.Core_App0\ApiGatewayPkg.Code.` -{{< alert type="note" title="Note" >}} -`` and `` will depend on how the node was configured during the installation of {{% ctx %}}. -{{< /alert >}} +1. Navigate to the Execution service directory, e.g. `%ProgramData%\SF\.\Fabric\work\Applications\Cortex.Innovation.Core_App\ApiGatewayPkg.Code.` replacing `` with the CustomerName configured during installation, `` with the NETBIOS name of the server, `` with the highest number in the directory and `` with the latest version in the directory. 1. Open the `appsettings.json` file. 1. Under the `Cors` section, update the following parameters: | Name | Description | Example | @@ -294,25 +291,19 @@ On the Application Server: ``` 1. Save the file. -1. Repeat these steps for the appsettings.json file located in `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.`. +1. Repeat these steps for the appsettings.json file located in `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.`. #### Restart the code package -{{< alert color="warning" title="Important" >}} -These steps will need to be repeated on all Application Servers. -{{< /alert >}} - -On the Application Server: - 1. Navigate to the Service Fabric Explorer, typically `http://localhost:9080/Explorer`. -1. Restart the `ApiGatewayPkg` by following these steps: - 1. Expand the `Nodes` - 1. Select the current node +1. Expand the `Nodes` +1. Restart the `ApiGatewayPkg` for each node by following these steps: + 1. Expand the node name 1. Expand `fabric:/Core/Services` 1. Expand the `ApiGatewayPkg` service package 1. Expand `Code Packages` 1. Hover over `Code` and click on the `▼` button - 1. Click `Restart` + 1. Confirm the restart as prompted, then click `Restart` {{< alert type="note" title="Note" >}} It may take a few minutes for the `Code` package to restart. From 994c78879cf61944394d10cf20437acea7cdc560 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 12:59:35 +0100 Subject: [PATCH 14/19] Before try it out --- .../installation.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index e85a46589..62497e73b 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -312,13 +312,13 @@ It may take a few minutes for the `Code` package to restart. ### Set up User Access Control {{< alert color="warning" title="Important" >}} -The {{% ctx %}} Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when allocating access to the portal, it is advised that access is limited following the practice of least privilege. +The {{% ctx %}} Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when granting access to the portal, it is advised that access is limited following the practice of least privilege. {{< /alert >}} On the Web Application Server: -1. Open a `Windows PowerShell ISE` (x64) window as administrator. -1. Change the location to where the `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted, inside the `Cortex Configuration Portal` folder, e.g. `cd "C:\Install\Cortex Innovation {{< version >}} - Configuration Portal\Cortex Configuration Portal"`. +1. Open a Windows PowerShell ISE (x64) window as administrator. +1. Change the location to where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to, inside the `Cortex Configuration Portal` folder, e.g. `cd "C:\Install\Cortex Innovation {{< version >}} - Configuration Portal\Cortex Configuration Portal"`. 1. In the script section, copy the following script: ``` powershell @@ -335,17 +335,17 @@ On the Web Application Server: ``` 1. Update the following parameters: - | Name | Description | Example | - |-----------------|------------------------------------------------------------------------------------------------|------------------------------------------| - | URL | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | - | Port | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | - | Username | The username used to authenticate against the Application Server APIGateway. | `"BasicAuthUser"` | - | Password | The password for the username specified for `Username`. | `""` | - | Tenant | The tenant defining the scope of the Configuration storage and user sessions. | `"default"` | - | Environment | The system defining the scope of the Configuration storage and user sessions. | `"default"` | - | adminAdGroups | An array of Active Directory groups that should have admin access to the Configuration Portal. | `@("Domain Admins Group")` | - | userAdGroups | An array of Active Directory groups that should have user access to the Configuration Portal. | `@("Domain Users Group")` | - | ApplicationName | The name of the application, this will be used for containerisation of user sessions. | `"CortexConfigurationDev"` | + | Name | Description | Example | + |-----------------|-------------------------------------------------------------------------------------------------------|------------------------------------------| + | URL | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | + | Port | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | + | Username | The username specified for `ApiGatewayBasicAuthUsername` when [installing the Application Servers][]. | `""` | + | Password | The password specified for `ApiGatewayBasicAuthPassword` when [installing the Application Servers][]. | `""` | + | Tenant | The tenant defining the scope of the Configuration storage and user sessions. | `"default"` | + | Environment | The system defining the scope of the Configuration storage and user sessions. | `"default"` | + | adminAdGroups | An array of Active Directory groups that should have admin access to the Configuration Portal. | `@("Domain Admins Group")` | + | userAdGroups | An array of Active Directory groups that should have user access to the Configuration Portal. | `@("Domain Users Group")` | + | ApplicationName | The `ApplicationName` set in step 5 of [Copy and configure relevant files][]. | `"CortexConfigurationDev"` | 1. Once updated, run the script and verify that it completes without errors. ## Next Steps? @@ -355,3 +355,5 @@ On the Web Application Server: [Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} [Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation.MainDoc" >}} [Gateway]: {{< url path="Cortex.Guides.Gateway.MainDoc" >}} +[installing the Application Servers]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}} +[Copy and configure relevant files]: {{< ref path="#copy-and-configure-relevant-files" >}} From 3d1d041b3bbba12daf259b8ec51d89b5b4d4de35 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 15:06:10 +0100 Subject: [PATCH 15/19] all doc reviewed --- .../installation.md | 2 +- .../post-installation/try-it-out.md | 55 +++++++++++++------ 2 files changed, 40 insertions(+), 17 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 62497e73b..d5a3263a0 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -312,7 +312,7 @@ It may take a few minutes for the `Code` package to restart. ### Set up User Access Control {{< alert color="warning" title="Important" >}} -The {{% ctx %}} Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when granting access to the portal, it is advised that access is limited following the practice of least privilege. +The {{% ctx %}} Configuration Portal should be treated as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when granting access to the portal, it is advised that access is limited following the practice of least privilege. {{< /alert >}} On the Web Application Server: diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md index 69f6ef9d6..a238ef3ff 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -1,18 +1,18 @@ --- title: "Try it out" linkTitle: "Try it out" -description: "Information about trying out {{% ctx %}} for the first time." +description: "Information about trying out {{% ctx %}} Configuration Portal for the first time." weight: 10 --- # {{% param title %}} -This guide describes how to try out a new {{% ctx %}} Configuration Portal installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. +This guide describes how to try out a new {{% ctx %}} Configuration Portal installation to make sure it is working. ## Test Access to Configuration Portal -1. Open a web browser and navigate to the URL of the Configuration Portal. This is typically in the format `http:///ConfigurationPortal`. -1. Log in using your Active Directory credentials. Ensure that the account you are using is part of one of the Active Directory groups specified during installation. +1. Open a web browser and navigate to `://:/`, e.g. `https://sever.domain.com/configurationportal`. +1. Log in using your Active Directory credentials. Ensure that the account you are using is a member of one of the Active Directory groups specified during installation. ## Test adding a new Configuration Container and Data @@ -21,7 +21,7 @@ This guide describes how to try out a new {{% ctx %}} Configuration Portal insta 1. Fill in the `Name` field with the value `TestContainer`. 1. Click `Confirm` to create the container. 1. Click the container you just created. -1. Using the values of the table below, add a some data to the created container as follows: +1. Using the values of the table below, add data to the created container as follows: | Name | Value | Type | |---------------|------------------------|---------| | `TestText` | `This is a test value` | Text | @@ -35,28 +35,51 @@ This guide describes how to try out a new {{% ctx %}} Configuration Portal insta 1. Click `CONFIRM` to add the parameter/value pair. {{< alert type="note" title="Note" >}} -The CORTEX Configuration Portal should be viewed as a repository of sensitive information which will most likely contain usernames and passwords. We recommend that any sensitive data is {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} before it is added to the portal. +The {{% ctx %}} Configuration Portal should be treated as a repository of sensitive information which will most likely contain usernames and passwords. We recommend that any sensitive data is {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} before it is added to the portal. {{< /alert >}} ## Test exporting an existing Container 1. You should be able to export a container by doing as follows: + 1. Click on `Home` to navigate back. 1. Tick the `Export` checkbox next to the container you created in the previous section. 1. Click on the `Export Containers` button. The file should be downloaded to your computer. +## Test importing an existing Container + +1. Modify some parameters from the `TestContainer` by doing as follows: + 1. Click on the `TestContainer` to open it. + 1. Click on the `Delete` button for `TestText`. + 1. Confirm the deletion by clicking `OK` on the pop-up. + 1. Click on the `Edit` button for `TestInteger`. + 1. Change the value to `33`. + 1. Click `CONFIRM` to save the changes. + +1. You should be able to import a container by doing as follows: + 1. Click on `Home` to navigate back. + 1. Click on the `Import Containers` button. + 1. Select the previously exported container `zip` file. + 1. Click `Open` to load the container. + 1. On the confirmation page, click `IMPORT`. + 1. Please confirm the import by clicking the`OK` button on the pop-up. + +1. Verify that the container has been imported by doing as follows: + 1. Click on the `TestContainer` to open it. + 1. Verify that the parameter `TestText` has been re-added and that the value of `TestInteger` retained the modified value of `33`. + {{< alert type="note" title="Note" >}} -Once you have confirmed the exported file contains the expected data, it is recommended to delete it. +Once you have successfully imported containers, it is recommended to always delete all the `zip` files. {{< /alert >}} ## Test reading data from Configuration Portal -1. Open a web browser and navigate to the URL of {{% ctx %}} Gateway. This is typically in the format `http:///gateway`. +1. Open a web browser and navigate to `://:/`, e.g. `https://server.domain.com/gateway` 1. Log in using your Active Directory credentials. -1. Click on the `Dev` charms, then search for `CM-Get-Config`. +1. Click on the `Dev` charm, then search for `CM-Get-Config`. 1. Click on the flow `CM-Get-Config`. -1. Once the flow opened, in the Settings tab, set the `ContainersNames` field to `["TestContainer"]`. +1. Once the flow has opened, in the Settings tab, set the `ContainersNames` property to `["TestContainer"]`. 1. Add a breakpoint to the `End Flow` block. 1. Click on the `Run` button to execute the flow. 1. When the flow hits the breakpoint, click on the `Variables` tab. @@ -69,12 +92,7 @@ Once you have confirmed the exported file contains the expected data, it is reco { "ParamID": "e440c1ee-29ee-4b70-9660-60f518a10339", "ParamName": "TestInteger", - "ParamValue": 22 - }, - { - "ParamID": "b0cedd5c-e832-4fd2-8292-462be9b0ab71", - "ParamName": "TestText", - "ParamValue": "This is a test value" + "ParamValue": 33 }, { "ParamID": "5f760269-41e4-4f99-8b82-96ac1ccfbb49", @@ -87,6 +105,11 @@ Once you have confirmed the exported file contains the expected data, it is reco "ParamValue": { "test": 22 } + }, + { + "ParamID": "b0cedd5c-e832-4fd2-8292-462be9b0ab71", + "ParamName": "TestText", + "ParamValue": "This is a test value" } ] } From ac6be4b28ceb824c6bf22fa6cd5a9794f5c8f16e Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 15:41:54 +0100 Subject: [PATCH 16/19] login --- .../add-configuration-portal-to-cortex/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index d5a3263a0..72b3c9c0c 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -13,7 +13,7 @@ This guide describes how to install the {{% ctx %}} Configuration Portal on the ### Import {{% ctx %}} Flows -The {{% ctx %}} Configuration Portal calls a set of flows to validate log-in credentials, and to manage interactions with the config reliable collections, where config data is stored. These flows are contained within the provided studio packages. +The {{% ctx %}} Configuration Portal calls a set of flows to validate login credentials, and to manage interactions with the config reliable collections, where config data is stored. These flows are contained within the provided studio packages. To import the flows, perform the following steps: From 36f5dd9e1220ce176c85e42aae8289aa693c75ab Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Mon, 13 Oct 2025 15:45:49 +0100 Subject: [PATCH 17/19] other log in typo --- .../add-configuration-portal-to-cortex/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index 72b3c9c0c..f66a9741e 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -17,7 +17,7 @@ The {{% ctx %}} Configuration Portal calls a set of flows to validate login cred To import the flows, perform the following steps: -1. Login to the {{% ctx %}} Gateway that is installed on the Web Application Server. +1. Log in to the {{% ctx %}} Gateway that is installed on the Web Application Server. 1. In {{% ctx %}} Gateway, click `Admin`, then `Studio Import`. 1. Import the following Studio packages which can be found in the folder where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to: 1. `Configuration.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Configuration Portal`. From 50576290783d5c90c1b2a6a3ead26e48af59002d Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Wed, 15 Oct 2025 11:03:26 +0100 Subject: [PATCH 18/19] PO sign-off --- .../installation.md | 98 +++++++++---------- .../post-installation/try-it-out.md | 4 +- 2 files changed, 49 insertions(+), 53 deletions(-) diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md index f66a9741e..edbc7c251 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -1,5 +1,5 @@ --- -title: "Install the Configuration Portal" +title: "Install Configuration Portal" linkTitle: "Install Configuration Portal" description: "Information about installing the {{% ctx %}} Configuration Portal." weight: 40 @@ -51,34 +51,32 @@ Once the flows are imported, they should be available from the `Dev` charms menu | OptionalAdConfig.Username | The username of an account used to query Active Directory. {{< alert type="note" title="Note" >}}If left empty, the `PowerShellDetails.Username` will be used.{{< /alert >}} | `ctx_aduser` | | OptionalAdConfig.Password | The password for the username specified for `OptionalAdConfig.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | -This should look similar to the following: - -``` json -{ - "PowerShellDetails": { - "Username": "ctx_serviceuser", - "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", - "Domain": "domain.com", - "Host": "cortexapp-machine.domain.com", - "Port": 5985, - "SSL": false - }, - "RecursiveAccessControl": false, - "OptionalAdConfig": { - "DomainController": "dc-machine.domain.com", - "BaseAdGroupSearch": "CN=Builtin,DC=CortexUsers,DC=com", - "Username": "ctx_aduser", - "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#" - }, - "DataStorage": { - "UamConfigCollection": "uamConfig", - "SessionsKeysCollection": "uamSessionsKeys", - "SessionsCollection": "uamSessions", - "ServiceRequestsCollection": "serviceRequests" + This should look similar to the following: + ``` json + { + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "RecursiveAccessControl": false, + "OptionalAdConfig": { + "DomainController": "dc-machine.domain.com", + "BaseAdGroupSearch": "CN=Builtin,DC=CortexUsers,DC=com", + "Username": "ctx_aduser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#" + }, + "DataStorage": { + "UamConfigCollection": "uamConfig", + "SessionsKeysCollection": "uamSessionsKeys", + "SessionsCollection": "uamSessions", + "ServiceRequestsCollection": "serviceRequests" + } } -} -``` - + ``` 1. Save and commit `UAM-Get-Config`. #### Configuration Management flow @@ -99,29 +97,27 @@ This should look similar to the following: | ConfigurationImportsFolder | The folder containing the configuration being imported. | `@"ConfigurationModule\Imports"` | | ConfigurationBackupsFolder | The folder containing the configuration backups if scheduled. | `@"ConfigurationModule\Backups"` | | `false` | -This should look similar to the following: - -``` json -{ - "PowerShellDetails": { - "Username": "ctx_serviceuser", - "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", - "Domain": "domain.com", - "Host": "cortexapp-machine.domain.com", - "Port": 5985, - "SSL": false - }, - "configCollectionName": "_cfgCollection", - "containerKeys": "_cfgContainerKeys", - "paramKeys": "_cfgParamKeys", - "CortexInteractionPortalPath": @"C:\inetpub\wwwroot\Cortex\ConfigurationPortal", - "ConfigurationExportsFolder": @"ConfigurationModule\Exports", - "ConfigurationImportsFolder": @"ConfigurationModule\Imports", - "ConfigurationBackupsFolder": @"ConfigurationModule\Backups", - "BackupBypassToken": "f2e97889-acd8-4324-9ac0-e6cc776478ed" -} -``` - + This should look similar to the following: + ``` json + { + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "configCollectionName": "_cfgCollection", + "containerKeys": "_cfgContainerKeys", + "paramKeys": "_cfgParamKeys", + "CortexInteractionPortalPath": @"C:\inetpub\wwwroot\Cortex\ConfigurationPortal", + "ConfigurationExportsFolder": @"ConfigurationModule\Exports", + "ConfigurationImportsFolder": @"ConfigurationModule\Imports", + "ConfigurationBackupsFolder": @"ConfigurationModule\Backups", + "BackupBypassToken": "f2e97889-acd8-4324-9ac0-e6cc776478ed" + } + ``` 1. Save and commit `CM-Config-Settings`. ### Create the Configuration Management Package diff --git a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md index a238ef3ff..38d6d7430 100644 --- a/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md +++ b/content/en/docs/2025.3/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -9,12 +9,12 @@ weight: 10 This guide describes how to try out a new {{% ctx %}} Configuration Portal installation to make sure it is working. -## Test Access to Configuration Portal +## Test access to Configuration Portal 1. Open a web browser and navigate to `://:/`, e.g. `https://sever.domain.com/configurationportal`. 1. Log in using your Active Directory credentials. Ensure that the account you are using is a member of one of the Active Directory groups specified during installation. -## Test adding a new Configuration Container and Data +## Test adding a new Configuration Container and data 1. Once logged in, you should be able to add a container by doing as follows: 1. Click on the `+ Add Container` button. From 9b3fedf4ca261d62e6ccbb4461a84fd767807e88 Mon Sep 17 00:00:00 2001 From: cortex-lp Date: Wed, 15 Oct 2025 11:14:06 +0100 Subject: [PATCH 19/19] Update documentation be also be on 2025.9 --- .../_index.md | 10 + .../installation.md | 355 ++++++++++++++++++ .../post-installation/_index.md | 10 + .../post-installation/try-it-out.md | 116 ++++++ .../pre-installation.md | 23 ++ .../requirements.md | 62 +++ 6 files changed, 576 insertions(+) create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md create mode 100644 content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md new file mode 100644 index 000000000..0b2764726 --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/_index.md @@ -0,0 +1,10 @@ +--- +title: "Add Configuration Portal to CORTEX" +linkTitle: "Add Configuration Portal to CORTEX" +description: "Information about pre-installation steps and installation instructions for the {{% ctx %}} Configuration Portal for {{% ctx %}}." +weight: 50 +--- + +{{< alert title="Important" color="warning" >}} +This guide currently only describe how to add the {{% ctx %}} Configuration Portal to an existing Web Application Server with {{% ctx %}} Gateway installed. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +{{% /alert %}} diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md new file mode 100644 index 000000000..edbc7c251 --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/installation.md @@ -0,0 +1,355 @@ +--- +title: "Install Configuration Portal" +linkTitle: "Install Configuration Portal" +description: "Information about installing the {{% ctx %}} Configuration Portal." +weight: 40 +--- + +# {{% param title %}} + +This guide describes how to install the {{% ctx %}} Configuration Portal on the Web Application Server. + +## Perform Installation + +### Import {{% ctx %}} Flows + +The {{% ctx %}} Configuration Portal calls a set of flows to validate login credentials, and to manage interactions with the config reliable collections, where config data is stored. These flows are contained within the provided studio packages. + +To import the flows, perform the following steps: + +1. Log in to the {{% ctx %}} Gateway that is installed on the Web Application Server. +1. In {{% ctx %}} Gateway, click `Admin`, then `Studio Import`. +1. Import the following Studio packages which can be found in the folder where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to: + 1. `Configuration.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Configuration Portal`. + 1. `Interaction.Portal.Core.Flows.studiopkg`, which can be found in the folder named `Cortex Interaction Portal`. + 1. `User Access Management.Flows.studiopkg`, which can be found in the folder named `User Access Management`. +1. Once imported, grant `Edit` permissions to these flows using [Studio Authorisation][]. + +{{< alert type="note" title="Note" >}} +Once the flows are imported, they should be available from the `Dev` charms menu. Note that you may need to refresh {{% ctx %}} Gateway after importing. +{{< /alert >}} + +### Configure the flows + +#### User Access Management flow + +1. Within {{% ctx %}} Gateway, open the `Dev` charm then search for `UAM-Get-Config` +1. Open the flow. +1. Click on the first `Set Variable` block to show the properties. +1. Within the value field, update the following parameters only: + | Name | Description | Example | + |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| + | PowerShellDetails.Username | The username of an account that can run PowerShell commands on all {{% ctx %}} servers, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator across the {{% ctx %}} servers.{{< /alert >}} | `"ctx_serviceuser"` | + | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | + | PowerShellDetails.Host | The host executing the PowerShell commands. {{< alert type="note" title="Note" >}}This can be `Environment.MachineName` to use the current node executing the flow.{{< /alert >}} | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` or `Environment.MachineName` | + | PowerShellDetails.Port | The PowerShell port. | `5985` | + | PowerShellDetails.SSL | Whether to use SSL for the PowerShell command. | `false` | + | RecursiveAccessControl | Whether child user groups should inherit access control granted to parents. | `false` | + | OptionalAdConfig.DomainController | The FQDN of the domain controller server. {{< alert type="note" title="Note" >}}If left empty, the domain that the node is attached to will be used.{{< /alert >}} | `"dc-machine.domain.com"` | + | OptionalAdConfig.BaseAdGroupSearch | The base path within the domain from which users can be selected. {{< alert type="note" title="Note" >}}If left empty, the entire domain will be used.{{< /alert >}} | `"CN=Builtin,DC=CortexUsers,DC=com"` | + | OptionalAdConfig.Username | The username of an account used to query Active Directory. {{< alert type="note" title="Note" >}}If left empty, the `PowerShellDetails.Username` will be used.{{< /alert >}} | `ctx_aduser` | + | OptionalAdConfig.Password | The password for the username specified for `OptionalAdConfig.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + + This should look similar to the following: + ``` json + { + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "RecursiveAccessControl": false, + "OptionalAdConfig": { + "DomainController": "dc-machine.domain.com", + "BaseAdGroupSearch": "CN=Builtin,DC=CortexUsers,DC=com", + "Username": "ctx_aduser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#" + }, + "DataStorage": { + "UamConfigCollection": "uamConfig", + "SessionsKeysCollection": "uamSessionsKeys", + "SessionsCollection": "uamSessions", + "ServiceRequestsCollection": "serviceRequests" + } + } + ``` +1. Save and commit `UAM-Get-Config`. + +#### Configuration Management flow + +1. Within {{% ctx %}} Gateway, open the `Dev` charm then search for `CM-Config-Settings` +1. Open the flow. +1. Click on the first `Set Variable` block to show the properties. +1. Within the value field, update the following parameters only: + | Name | Description | Example | + |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| + | PowerShellDetails.Username | The username of an account that can run PowerShell commands on the host specified for `PowerShellDetails.Host`, e.g., Service Account. {{< alert type="note" title="Note" >}}This user should be an administrator on the targeted Host.{{< /alert >}} | `"ctx_serviceuser"` | + | PowerShellDetails.Password | The password for the username specified for `PowerShellDetails.Username`. {{< alert type="note" title="Note" >}}This field must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | `"#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#"` | + | PowerShellDetails.Domain | The domain for the username specified for `PowerShellDetails.Username`. | `"domain.com"` | + | PowerShellDetails.Host | The host executing the PowerShell commands. | `"cortexapp-machine.domain.com"` or `"cortexapp-machine"` or `Environment.MachineName` | + | PowerShellDetails.Port | The PowerShell port. | `5985` | + | CortexInteractionPortalPath | The path to the Cortex Configuration Portal. | `@"C:\inetpub\wwwroot\Cortex\ConfigurationPortal"` | + | ConfigurationExportsFolder | The folder containing the configuration being exported. | `@"ConfigurationModule\Exports"` | + | ConfigurationImportsFolder | The folder containing the configuration being imported. | `@"ConfigurationModule\Imports"` | + | ConfigurationBackupsFolder | The folder containing the configuration backups if scheduled. | `@"ConfigurationModule\Backups"` | | `false` | + + This should look similar to the following: + ``` json + { + "PowerShellDetails": { + "Username": "ctx_serviceuser", + "Password": "#_124211015226168!130105247000243225146179242013178~146135159100034!214216128191025238010012072111212#", + "Domain": "domain.com", + "Host": "cortexapp-machine.domain.com", + "Port": 5985, + "SSL": false + }, + "configCollectionName": "_cfgCollection", + "containerKeys": "_cfgContainerKeys", + "paramKeys": "_cfgParamKeys", + "CortexInteractionPortalPath": @"C:\inetpub\wwwroot\Cortex\ConfigurationPortal", + "ConfigurationExportsFolder": @"ConfigurationModule\Exports", + "ConfigurationImportsFolder": @"ConfigurationModule\Imports", + "ConfigurationBackupsFolder": @"ConfigurationModule\Backups", + "BackupBypassToken": "f2e97889-acd8-4324-9ac0-e6cc776478ed" + } + ``` +1. Save and commit `CM-Config-Settings`. + +### Create the Configuration Management Package + +1. Within {{% ctx %}} Gateway, open the `Admin` charm then click on `Packages` +1. Click on `Add Package Definition` then: + 1. Set the `Package Name` to `CORTEXConfigurationManagement` + 1. Select the flows and groups as follows: + [ ] `Cortex-Library` + --- [X] `Config Management` + --- [ ] `Cortex Interaction Portal` + ------ [ ] `Core Portal Flows` + --------- [X] `UI-Get-AD-Groups` + --------- [X] `UI-Manage-Settings` + --- [ ] `User Access Management` + ------ [ ] `Config Data Storage` + --------- [X] `UAM-Get-Settings` + --------- [X] `UAM-Update-Settings` + ------ [ ] `Session Data Storage` + --------- [X] `UAM-Create-Session` + --------- [X] `UAM-Get-Session` + ------ [X] `UAM-Authenticate-User` + ------ [X] `UAM-Check-Access-Level` + ------ [X] `UAM-Get-Config` + ------ [X] `UAM-Validate-Token` + [ ] `Generic Flow Library` + --- [ ] `PowerShell` + ------ [X] `Execute-PowerShell-Script` + 1. Click `Save` + 1. Once saved, click `Publish` + 1. Once published: + 1. Select the `Authorisation` tab + 1. Select the groups that should be able to execute this package + 1. Click `Save` + +{{< alert type="note" title="Note" >}} +Keep a note of the selected groups, as they will be required when setting the access control for the {{% ctx %}} Configuration Portal. +{{< /alert >}} + +### Create the {{% ctx %}} Configuration Portal Website + +#### Copy and configure relevant files + +On the Web Application Server: + +1. Open the folder where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to. +1. Open the `Cortex Configuration Portal` folder. +1. Extract the contents of the `Cortex.Configuration.Portal.zip` file to where the website is to be installed. +{{< alert type="note" title="Note" >}} +Typically this is `C:\inetpub\wwwroot\Cortex\ConfigurationPortal` +{{< /alert >}} +1. Copy the `web.config` and `config.json` files from the `Cortex Configuration Portal` folder opened in step 2 to the root of the extracted content in step 3, e.g. `C:\inetpub\wwwroot\Cortex\ConfigurationPortal`. +1. Once copied, open the `config.json` file and update the following parameters only: + | Name | Description | Example | + |--------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------| + | ApplicationName | The name of the application, this will be used for referencing the relevant configuration data. | `"CortexConfigurationDev"` | + | UseOAuth | Whether to use OAuth for authentication. | `true` | + | CortexUrl | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | + | CortexPort | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | + | CortexTenant | The tenant defining the scope of the Configuration storage and user sessions at the tenant level. | `"default"` | + | CortexEnvironment | The system defining the scope of the Configuration storage and user sessions at the system level. | `"default"` | + | ConfigManagementPackageName | The name of the package containing the flows used by the {{% ctx %}} Configuration Portal. | `CORTEXConfigurationManagement` | + | ConfigManagementPackageVersion | The version of the package to be used. | `""` | + | ConfigPortalPath | The folder name containing the {{% ctx %}} Configuration Portal. | `"ConfigurationPortal"` | + | ConfigPortalPort | The port to communicate with the {{% ctx %}} Configuration Portal. | `"443"` | + | ConfigPortalUrl | The {{% ctx %}} Configuration Portal base URL. | `"https://cortexwebapp-machine.domain.com"` | + +This should look similar to the following: + +``` json +{ + "ApplicationName": "CortexConfigurationDev", + "UseOAuth": true, + + "CortexUrl": "https://cortexapp-machine.domain.com", + "CortexPort": "8722", + "CortexTenant": "default", + "CortexEnvironment": "default", + + "ConfigManagementPackageName": "CORTEXConfigurationManagement", + "ConfigManagementPackageVersion": "", + "ConfigPortalPath": "ConfigurationPortal", + "ConfigPortalPort": "443", + "ConfigPortalUrl": "https://cortexwebapp-machine.domain.com", + + "FlowAuthBase64": "", + "TableBreakpoint": "1224", + "MobileBreakpoint": 769, + "ConfigSet": true +} +``` + +1. Save the file. + +#### Create the application + +On the Web Application Server: + +1. Open IIS. +1. Expand the current node, then `Sites`. +1. Expand the website that contains the {{% ctx %}} application, typically named `Cortex`. +1. To convert the {{% ctx %}} Configuration Portal folder to an Application: + 1. Locate the `ConfigurationPortal` folder + 1. Right-click on `ConfigurationPortal`. + 1. Click `Convert to Application`. + 1. Change the `Application pool` to be the same as [{{% ctx %}} Gateway][Gateway], typically named `Cortex Gateway`. + 1. Click `OK`. + +### Configure the {{% ctx %}} Configuration Portal Website + +#### Configure the Redirect rule + +On the Web Application Server: + +1. Navigate to the `Cortex` website directory, typically `C:\inetpub\wwwroot\Cortex`. +1. If a `web.config` file is present, and a `Redirect Cortex to gateway` rule present, add a condition as follows: + + ``` xml + + ``` + +1. Save the file. + +#### CORS Configuration + +{{< alert type="note" title="Note" >}} +These steps are only needed if the {{% ctx %}} Interaction Portal is not already installed. +{{< /alert >}} + +{{< alert color="warning" title="Important" >}} +These steps will need to be repeated on all Application Servers. +{{< /alert >}} + +On each Application Server: + +1. Navigate to the Execution service directory, e.g. `%ProgramData%\SF\.\Fabric\work\Applications\Cortex.Innovation.Core_App\ApiGatewayPkg.Code.` replacing `` with the CustomerName configured during installation, `` with the NETBIOS name of the server, `` with the highest number in the directory and `` with the latest version in the directory. +1. Open the `appsettings.json` file. +1. Under the `Cors` section, update the following parameters: + | Name | Description | Example | + |-------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------| + | Enabled | Whether CORS is enabled, this MUST be set to `true`. | `true` | + | AllowedOrigins | List of Strings containing all the allowed origins. | `[ "https://*.domain.com", "https://cortexwebapp-machine.domain.com" ]` | + | AllowCredentials | Whether to allow credentials, this MUST be set to `true`. | `true` | + | AllowWildCardSubDomains | Whether to allow wildcard subdomains, this MUST be set to `true`. | `true` | + + The CORS section should look similar to the following: + + ``` json + "Cors": { + "Enabled": true, + "AllowedOrigins": [ + "https://*.domain.com", + "https://*.appgyver.com" + ], + "AllowedRequestHeaders": [ + "*" + ], + "AllowedResponseHeaders": [ + ], + "AllowedMethods": [ + "*" + ], + "AllowCredentials": true, + "AllowWildcardSubdomains": true, + "PreflightMaxAgeInMs": 5000 + }, + ``` + +1. Save the file. +1. Repeat these steps for the appsettings.json file located in `C:\ProgramData\SF\.\Fabric\work\ImageCache\Store\Cortex.Innovation.Core\ApiGatewayPkg.Code.`. + +#### Restart the code package + +1. Navigate to the Service Fabric Explorer, typically `http://localhost:9080/Explorer`. +1. Expand the `Nodes` +1. Restart the `ApiGatewayPkg` for each node by following these steps: + 1. Expand the node name + 1. Expand `fabric:/Core/Services` + 1. Expand the `ApiGatewayPkg` service package + 1. Expand `Code Packages` + 1. Hover over `Code` and click on the `▼` button + 1. Confirm the restart as prompted, then click `Restart` + +{{< alert type="note" title="Note" >}} +It may take a few minutes for the `Code` package to restart. +{{< /alert >}} + +### Set up User Access Control + +{{< alert color="warning" title="Important" >}} +The {{% ctx %}} Configuration Portal should be treated as a repository of sensitive information which will most likely contain usernames and passwords. Therefore consideration should be given to security when granting access to the portal, it is advised that access is limited following the practice of least privilege. +{{< /alert >}} + +On the Web Application Server: + +1. Open a Windows PowerShell ISE (x64) window as administrator. +1. Change the location to where `Cortex Innovation {{< version >}} - Configuration Portal.zip` was extracted to, inside the `Cortex Configuration Portal` folder, e.g. `cd "C:\Install\Cortex Innovation {{< version >}} - Configuration Portal\Cortex Configuration Portal"`. +1. In the script section, copy the following script: + + ``` powershell + .\Deploy.Cortex.Configuration.Portal.ps1 ` + -URL "https://cortexapp-machine.domain.com" ` + -Port "8722" ` + -Username "BasicAuthUser" ` + -Password "" ` + -Tenant "default" ` + -Environment "default" ` + -adminAdGroups @("Domain Admins Group") ` + -userAdGroups @("Domain Users Group") ` + -ApplicationName "CortexConfigurationDev" + ``` + +1. Update the following parameters: + | Name | Description | Example | + |-----------------|-------------------------------------------------------------------------------------------------------|------------------------------------------| + | URL | The URL of the Application Server APIGateway endpoint, or loadbalancer. | `"https://cortexapp-machine.domain.com"` | + | Port | The port of the Application Server APIGateway endpoint, or loadbalancer. | `"8722"` | + | Username | The username specified for `ApiGatewayBasicAuthUsername` when [installing the Application Servers][]. | `""` | + | Password | The password specified for `ApiGatewayBasicAuthPassword` when [installing the Application Servers][]. | `""` | + | Tenant | The tenant defining the scope of the Configuration storage and user sessions. | `"default"` | + | Environment | The system defining the scope of the Configuration storage and user sessions. | `"default"` | + | adminAdGroups | An array of Active Directory groups that should have admin access to the Configuration Portal. | `@("Domain Admins Group")` | + | userAdGroups | An array of Active Directory groups that should have user access to the Configuration Portal. | `@("Domain Users Group")` | + | ApplicationName | The `ApplicationName` set in step 5 of [Copy and configure relevant files][]. | `"CortexConfigurationDev"` | +1. Once updated, run the script and verify that it completes without errors. + +## Next Steps? + +1. [Try it out][] + +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PostInstallation.TryItOut" >}} +[Studio Authorisation]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.StudioAuthorisation.MainDoc" >}} +[Gateway]: {{< url path="Cortex.Guides.Gateway.MainDoc" >}} +[installing the Application Servers]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}} +[Copy and configure relevant files]: {{< ref path="#copy-and-configure-relevant-files" >}} diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md new file mode 100644 index 000000000..fa805caed --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/_index.md @@ -0,0 +1,10 @@ +--- +title: "Post-Installation" +linkTitle: "Post-Installation" +description: "Information about the steps required to be completed after the installation has finished." +weight: 50 +--- + +This guide describes how to perform the steps to verify the installation of the {{% ctx %}} Configuration Portal. Please ensure that the [Installation][] has been completed before starting this section. + +[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation.MainDoc" >}} diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md new file mode 100644 index 000000000..38d6d7430 --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/post-installation/try-it-out.md @@ -0,0 +1,116 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} Configuration Portal for the first time." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to try out a new {{% ctx %}} Configuration Portal installation to make sure it is working. + +## Test access to Configuration Portal + +1. Open a web browser and navigate to `://:/`, e.g. `https://sever.domain.com/configurationportal`. +1. Log in using your Active Directory credentials. Ensure that the account you are using is a member of one of the Active Directory groups specified during installation. + +## Test adding a new Configuration Container and data + +1. Once logged in, you should be able to add a container by doing as follows: + 1. Click on the `+ Add Container` button. + 1. Fill in the `Name` field with the value `TestContainer`. + 1. Click `Confirm` to create the container. +1. Click the container you just created. +1. Using the values of the table below, add data to the created container as follows: + | Name | Value | Type | + |---------------|------------------------|---------| + | `TestText` | `This is a test value` | Text | + | `TestInteger` | `22` | Integer | + | `TestBool` | `true` | Bool | + | `TestObject` | `{"test":22}` | Object | + + 1. Click on the `+ Add Parameter/Value Pair` button. + 1. Fill in the `Name` and the `Value`. + 1. Select the `Type`. + 1. Click `CONFIRM` to add the parameter/value pair. + +{{< alert type="note" title="Note" >}} +The {{% ctx %}} Configuration Portal should be treated as a repository of sensitive information which will most likely contain usernames and passwords. We recommend that any sensitive data is {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} before it is added to the portal. +{{< /alert >}} + +## Test exporting an existing Container + +1. You should be able to export a container by doing as follows: + 1. Click on `Home` to navigate back. + 1. Tick the `Export` checkbox next to the container you created in the previous section. + 1. Click on the `Export Containers` button. + +The file should be downloaded to your computer. + +## Test importing an existing Container + +1. Modify some parameters from the `TestContainer` by doing as follows: + 1. Click on the `TestContainer` to open it. + 1. Click on the `Delete` button for `TestText`. + 1. Confirm the deletion by clicking `OK` on the pop-up. + 1. Click on the `Edit` button for `TestInteger`. + 1. Change the value to `33`. + 1. Click `CONFIRM` to save the changes. + +1. You should be able to import a container by doing as follows: + 1. Click on `Home` to navigate back. + 1. Click on the `Import Containers` button. + 1. Select the previously exported container `zip` file. + 1. Click `Open` to load the container. + 1. On the confirmation page, click `IMPORT`. + 1. Please confirm the import by clicking the`OK` button on the pop-up. + +1. Verify that the container has been imported by doing as follows: + 1. Click on the `TestContainer` to open it. + 1. Verify that the parameter `TestText` has been re-added and that the value of `TestInteger` retained the modified value of `33`. + +{{< alert type="note" title="Note" >}} +Once you have successfully imported containers, it is recommended to always delete all the `zip` files. +{{< /alert >}} + +## Test reading data from Configuration Portal + +1. Open a web browser and navigate to `://:/`, e.g. `https://server.domain.com/gateway` +1. Log in using your Active Directory credentials. +1. Click on the `Dev` charm, then search for `CM-Get-Config`. +1. Click on the flow `CM-Get-Config`. +1. Once the flow has opened, in the Settings tab, set the `ContainersNames` property to `["TestContainer"]`. +1. Add a breakpoint to the `End Flow` block. +1. Click on the `Run` button to execute the flow. +1. When the flow hits the breakpoint, click on the `Variables` tab. +1. Select the variable `ConfigItems`. +1. Verify that the variable contains the data you added in the previous section, it should look like the following: + +``` json +{ + "Parameters": [ + { + "ParamID": "e440c1ee-29ee-4b70-9660-60f518a10339", + "ParamName": "TestInteger", + "ParamValue": 33 + }, + { + "ParamID": "5f760269-41e4-4f99-8b82-96ac1ccfbb49", + "ParamName": "TestBool", + "ParamValue": true + }, + { + "ParamID": "e967217d-4ca0-4a77-b357-2b3ccf1335d7", + "ParamName": "TestObject", + "ParamValue": { + "test": 22 + } + }, + { + "ParamID": "b0cedd5c-e832-4fd2-8292-462be9b0ab71", + "ParamName": "TestText", + "ParamValue": "This is a test value" + } + ] +} +``` diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md new file mode 100644 index 000000000..e387662cf --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/pre-installation.md @@ -0,0 +1,23 @@ +--- +title: "Pre-Installation" +linkTitle: "Pre-Installation" +description: "Information about the steps required to be completed prior to starting the installation." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to perform the steps required before starting the installation of the {{% ctx %}} Configuration Portal. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the Web Application Server: + * Cortex Innovation {{< version >}} - Configuration Portal.zip + +1. Extract the `Cortex Innovation {{< version >}} - Configuration Portal.zip` file to a folder with the same name. + +## Next Steps? + +1. [Installation][] + +[Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.Installation.MainDoc" >}} diff --git a/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md new file mode 100644 index 000000000..86b15c071 --- /dev/null +++ b/content/en/docs/2025.9/getting-started/on-premise/add-configuration-portal-to-cortex/requirements.md @@ -0,0 +1,62 @@ +--- +title: "Requirements" +linkTitle: "Requirements" +description: "Information about the requirements required." +weight: 10 +--- + +# {{% param title %}} + +The requirements for an installation of the {{% ctx %}} Configuration Portal are laid out in this guide. These must be considered before undertaking installation. + +{{< alert color="warning" title="Important" >}} +The Configuration Portal must be installed on the Web Application Server where {{% ctx %}} Gateway is installed. For any other installation scenario, please contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}}. +{{< /alert >}} + +## Domain Requirements + +The server must be on a domain and cannot be a domain controller. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|------------------------|-----------|---------------------|-----------------| +| Windows Server 2016 | | {{% ctx %}} v2025.3 | To be evaluated | +| Windows Server 2019 | ✓ | {{% ctx %}} v2025.3 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2025.3 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server. + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Security Requirements + +### Installation User + +A domain user with the necessary administrative permissions to log on to the Configuration Portal host server via Remote Desktop and execute PowerShell scripts. + +### PowerShell User + +A service user with the necessary permissions to execute PowerShell scripts on the {{% ctx %}} platform, and has right to query Active Directory. + +### Domain Groups + +The Active Directory groups to which access to the Configuration Portal should be granted must be known prior to installation. + +## Next Steps? + +1. [Pre-Installation][] + +[Pre-Installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddConfigurationPortalToCortex.PreInstallation" >}}