Skip to main content

Install in Docker

warning

Cortex version 2.0 (and beyond) require a read-write connection to a Cortex-specific data store. This can be the same database, a completely separate database, or a completely separate database server/service.

You can find more information about how to configure this on the Connection Strings page.

Pre-requisites​

  • A container runtime, like Docker, Kubernetes, Amazon ECS, or Azure Container Apps
  • Your Cherwell database, restored to a Microsoft SQL Server instance (with Full Text Indexing installed) accessible to your container runtime

Install​

1. Pull the docker image​

Decide which version of Cortex you would like to install. Each has a specific "tag"; at present we don't tag a latest image (see here for why):

  • Current stable: use the tag v1.7.6

Execute the following command:

docker pull synapsesoftware.azurecr.io/cortex:v1.7.6

2. Run the docker image​

For testing, the only options you need to specify are:

  • -p to map your desired port to port 8080 within the container, like -p 80:8080
  • -e ConnectionStrings__Default=<your_connection_string> to configure the connection to SQL server
  • -e Authentication__Type=none to disable auth during testing (you must have a CSDAdmin user defined)

See below for the full list of configuration options.

Run the container like so:

docker run -p 8080:8080 -e ConnectionStrings__Default=<your_connection_string> -e Authentication__Type=none synapsesoftware.azurecr.io/cortex/v1.5.0

3. Running in production​

Configuration​

Three items need to be configured:

  • Database connection to a previously installed Cherwell database (See here for details on creating a connection string)
  • Your Cortex License "company name" and License code (NOTE: These are different from your Cherwell license)
  • Your desired authentication type (even if it's "none")

If you don't have a Cortex License, the software will run with result sets limited to 10 records.

Configuration with Environment Variables​

Set at least the following environment variables:

ConnectionStrings__Cherwell="READ (WRITE OPTIONAL) CONNECTION STRING FOR CHERWELL DATA"
ConnectionStrings__Cortex="READ/WRITE CONNECTION STRING FOR CORTEX DATA"
Licensing__CompanyName="YOUR COMPANY'S NAME HERE"
Licensing__LicenseCode="YOUR LICENSE CODE"
Authentication__Type="ONE OF: none, saml, keycloak"
# Also the additional values required for your authentication type

Any option that can be configured in the appsettings.json file can also be specified as environment variables by appending each path segment, separated by two underscores. Thus, the "Type" field in the "Authentication" block becomes Authentication__Type. Microsoft calls this "environment variable hierarchical keys".

Next Steps​

HTTPS/SSL​

warning

If you are using SAML for authentication, HTTPS/SSL may be required (it is certainly recommended). If you add HTTPS later, you may have to change your SAML configuration.

It is highly recommended that you configure HTTPS/SSL for the server running the Cortex application. How to do this is outside the scope of this documentation, because it is highly environment and infrastructure dependent. For instance, you might choose to use a self-signed certificate installed in IIS. Or a fully-signed cert from a local certificate authority. Or a full cert from a third-party CA. Or you might run a reverse proxy in front of either IIS or a container, that handles HTTPS in yet another way.

We might be able to provide guidance if we have familiarity with your specific technology, but the most knowledgeable people will undoubtedly be your own infrastructure team.

Authentication​

In most cases, we start with using the authentication type none so we can verify connectivity to your database without adding extra variables to the mix.

However, Authentication:Type none is not recommended for production. You should instead configure your desired authentication type (SAML or OpenID Connect).

Leaving Authentication:Type set to none means that all of your data is accessible to anyone who can visit the HTTP site on the system running Cortex and is extremely insecure. This mode is meant solely for initial setup and verification.