Skip to main content
Version: Next

Install using Docker

warning

Cortex 2.0 and later require a read-write connection to a Cortex-specific data store. Synapse Software does not support having Cortex and any archive in the same database. They should always be two separate databases.

See the Connection Strings page for configuration details.

Prerequisites​

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

Step 1 - Pull the Docker Image​

All Cortex releases are available as container images. Check the releases site for the current stable tag:

  • Current stable: use the tag vNEXT

https://releases.synapsesoftware.com/

docker pull synapsesoftware.azurecr.io/cortex:vNEXT

Pull the image using the desired version tag:

docker pull synapsesoftware.azurecr.io/cortex:vX.X.X

Replace vX.X.X with the version you are deploying.

Step 2 - Run the Container (Testing)​

For initial testing, the minimum required options are:

  • -p to map a host port to port 8080 inside the container
  • -e ConnectionStrings__Default to set the database connection string
  • -e Authentication__Type=none to disable authentication during testing (a CSDAdmin user must exist in your database)
docker run -p 8080:8080 \
  -e ConnectionStrings__Default="<your_connection_string>" \
  -e Authentication__Type=none \
  synapsesoftware.azurecr.io/cortex:vX.X.X

Browse to http://localhost:8080 to confirm the application loads.

Step 3 - Running in Production​

For production deployments, pass all required configuration via environment variables. Do not use Authentication:Type=none in production.

Set at minimum 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 NAME HERE"
Licensing__LicenseCode="YOUR LICENSE CODE"
Authentication__Type="none | saml | keycloak | internal"

Any setting from appsettings.json can be passed as an environment variable by replacing each level of nesting with __ (two underscores). For example, the Type field inside the Authentication block becomes Authentication__Type. Microsoft refers to this as environment variable hierarchical keys.

For a docker compose deployment, a typical service definition looks like:

services:
  cortex:
    image: synapsesoftware.azurecr.io/cortex:vX.X.X
    ports:
      - "8080:8080"
    environment:
      ConnectionStrings__Cherwell: "<your cherwell connection string>"
      ConnectionStrings__Cortex: "<your cortex connection string>"
      Licensing__CompanyName: "<your company name>"
      Licensing__LicenseCode: "<your license code>"
      Authentication__Type: "saml"

If you do not have a Cortex license, the application will run with search results limited to 10 records.

For connection string details, see: Connection Strings

For authentication configuration, see: Authentication

Next Steps​

HTTPS / SSL​

warning

If you are using SAML for authentication, HTTPS is required (or at minimum strongly recommended). If you add HTTPS after configuring SAML, you will need to update your SAML configuration to match.

Configuring HTTPS is highly recommended for any production deployment. How you do this depends on your environment - common options include a certificate installed directly in IIS, a certificate from an internal or external CA, or HTTPS termination at a reverse proxy in front of Cortex.

Your infrastructure team will be the best resource for this. We can offer guidance if we are familiar with your specific setup.

Authentication​

In most cases, we recommend starting with Authentication:Type set to none to confirm your database connection is working before introducing additional variables.

Authentication:Type none is not suitable for production. Once you have confirmed connectivity, configure your preferred authentication method:

Authentication

Leaving authentication set to none means all data is accessible to anyone who can reach the server. This mode is intended solely for initial setup and verification.

Troubleshooting​

If Cortex does not load after installation, see:

Installation Troubleshooting