/
Containerized Deployment Guide 3.7.1

Containerized Deployment Guide 3.7.1

Syndeia Cloud 3.7.1 — Docker Deployment Guide

1. Overview

This guide provides step-by-step instructions for deploying Syndeia Cloud 3.7.1 using Docker Compose. For upgrading from a previous containerized version, see the separate Docker Upgrade Guide.

The deployment package includes everything needed to run Syndeia Cloud as a set of Docker containers:

  • 34 Services: 7 core services, up to 26 integration services, and 1 operations service — all managed by Docker Compose.

  • Infrastructure: Cassandra 4.1, Kafka 3.7 (KRaft mode), and JanusGraph 1.0 run as containers alongside the application services.

  • Automated Setup: The setup.py script handles user creation, secret generation, configuration, and orchestrated startup with health checks.

  • Air-Gapped Support: Images can be distributed via registry pull, registry mirroring, or offline tarball loading.

2. Prerequisites

2.1 General Requirements

Software: Syndeia Cloud Package

Download the following from the Intercax secure file share (see your license email):

  • syndeia-cloud-docker-3.7.1.zip (The containerized deployment package)

Software: License Server

2.2 Target Server Requirements

  • OS: RHEL/Alma/Rocky/CentOS 8+, Ubuntu 20.04/22.04, or any Linux distribution with Docker support. macOS and Windows with Docker Desktop are supported for development/evaluation.

  • CPU: 16 cores minimum

  • Memory: 32 GB minimum

  • Disk: 50 GB free for container images, 100+ GB for persistent data (Cassandra + Kafka)

  • Docker: Docker Engine 24+ with the Compose plugin (docker compose). Standalone docker-compose is also supported.

  • Python: Python 3.6+ (included by default on RHEL 8+, Ubuntu 20.04+)

  • User: A user account with sudo privileges (Linux only, for system user creation).

2.3 Network Requirements

The server needs access to pull container images from the Intercax registry (c7reg.intercax.com). For air-gapped environments, see Section 3b.

3. Deployment & Installation

Stage 1: Preparation

Step 1: Extract the docker deployment package

  1. Transfer the package to the target server at the location of your choice using your desired method (scp, ftp, etc.).

    # Transfer the package scp syndeia-cloud-3.7.1-docker.zip user@mydockerserver:/home/user

  2. Log into the target server and navigate to the directory to which you transferred the package.

    ssh user@mydockerserver # Navigate to the directory containing the package cd /home/user

  3. Unzip the docker deployment package and cd into the extracted folder

    # Unzip the package and cd unzip syndeia-cloud-3.7.1-docker.zip -d syndeia-cloud-3.7.1-docker cd syndeia-cloud-3.7.1-docker

The package contains:

syndeia-cloud-3.7.1-docker/ ├── .syndeia-version # version identifiers from the build process ├── README.md # secondary guidance ├── docker-compose.yml # Service definitions ├── env.template # Environment variable template ├── prepare-images.py # Image distribution utility ├── hocon-merge.py # Configuration files merge utility ├── setup.py # Install/upgrade/rollback orchestration ├── config/ # Per-service configuration files │ ├── .defaults/ # default values for configurations │ ├── sc_service_configs/ # HOCON configs for each service │ ├── trust/ # credentials management │ └── infra/ # supporting IT services' configuration ├── data/ # Runtime data directory structure ├── libs/ # Vendor libraries (Teamcenter, DSCR, DSE3) ├── license/ # License file location ├── logs/ # Log output directory └── .syndeia-version # Version metadata

Stage 2: Pull Images

For security and reliability, you must copy the provided Syndeia Cloud Docker images from Intercax's distribution registry into your local docker repository or your organization's private container registry (e.g., Artifactory, Harbor, AWS ECR, Docker Hub, etc.).

For production deployment, we recommend using an internal or cloud hosted private registry. See Security and Hardening Containerized Post-Deployment Actions .

We provide a helper script template, prepare-images.py, to automate this process - but you must first authenticate with the Intercax registry

Step 2: Authenticate with Registry

Log in to the Intercax Registry using the docker login command.

  1. # Login to Intercax registry # Replace <registry-host> with the Registry Host provided in the intercax-docker-registry-credentials.txt file docker login <registry-host>

    Enter the username and password provided in the intercax-docker-registry-credentials.txt file.

If you do not have these credentials, review your Syndeia Download Guide, provided in your IHD license ticket, for instruction on how to obtain these.

Step 3: Pull Container Images

You can pull everything needed all at once, in stages, sequentially, or in parallel. If you are pulling from the Intercax Docker Registry over highspeed links, try this all-at-once, parallel pull. Use the other options here if you need to slow it down or to pull from different registries.

python3 prepare-images.py --source-host c7reg.intercax.com --pull-third-party --parallel 17

Assuming that worked well, skip to the verification step after these other options.

Use the included prepare-images.py script to pull the Syndeia images:

# Download images to local docker repository python3 prepare-images.py --source-host <registry-host>

This pulls all Syndeia service images plus the 3 infrastructure images (Cassandra, Kafka, JanusGraph). The --parallel flag allows you to control the number of concurrent pulls (default: 4):

python3 prepare-images.py --source-host <registry-host> --parallel 8

To also pull third-party infrastructure images:

python3 prepare-images.py --source-host <registry-host> --pull-third-party

Verify all images are available:

docker images | grep syndeia

Stage 3: Configuration

Quick-start Tip: If you are deploying Syndeia for the first time, skip configuration and jump right to Step 5 (Licensing)

The configuration here is for administrators who need to tailor Syndeia defaults to a known environment.

These instructions are for the initial installation of Syndeia onto a clean server which has not been a Syndeia server before. See the Upgrades and Migration section for installation into existing Syndeia servers.

For HTTP Systems

When you intend to deploy a Syndeia service that does not use HTTPS, you do not need to set any of the variables in the environment file - the setup process will generate every setting and generate the necessary .env which the docker containers use at runtime. In fact, for this case, you should move aside any preexisting .env file. Furthermore, the syndeia-cloud user should not yet exist. Remove any preexisting syndeia-cloud user from /etc/passwd and /etc/group. When either .env or syndeia-cloud is present before you start this installation of Syndeia Cloud, it indicates that the VM was used for a prior deployment of Syndeia or, at least, for a prior attempt at deploying Syndeia.

For HTTPS Systems

When you intend to deploy a Syndeia service that does use HTTPS, you need to create a .env file from the env.template and then set the following variables. You can bring your own SSL Certificate or have the setup.py script create suitable “self-signed” certificate keystore and truststore content. Read https://intercax.atlassian.net/wiki/spaces/IN/pages/5441748993 for the details.

# other vars come before these WEB_GATEWAY_PROTOCOL=https WEB_GATEWAY_HOST=syndeia.example.com WEB_GATEWAY_PORT=9443 TRUSTSTORE_PASSWORD=changeit TRUSTSTORE_TYPE=PKCS12 # more variables come after these but you can skip editing those for this purpose

With the .env edited, you can then either use setup to generate a self-signed certificate (for non-production, evaluation work) or set up the configuration using your production full-chain certificate in PEM format.

Production Systems
# Use an existing cert chain instead of generating self-signed python3 setup.py --prepare-https /path/to/fullchain.pem --keystore-password <ks_pass> --cacerts-password <ts_pass>
Evaluation/Non-Production Use
# Generate a self-signed HTTPS cert, a keystore, and update the default cacerts with that new cert python3 setup.py --prepare-https --keystore-password <ks_pass> --san syndeia.example.com --cacerts-password <ts_pass>

For illustrative purposes, here is the output from running the prepare-https with a dry-run check:

python3 setup.py --prepare-https --keystore-password ReallyChangeMe! --dry-run
[2026-05-13 18:08:29] [INFO] === HTTPS Certificate Preparation === [2026-05-13 18:08:29] [INFO] Generating self-signed cert (dname='CN=sc-web-gateway,OU=Syndeia,O=Intercax,C=US', SANs=['sc-web-gateway', 'localhost', 'IP:127.0.0.1'], validity=825 days) [2026-05-13 18:08:29] [INFO] Generated: DNS:sc-web-gateway, DNS:localhost, IP:127.0.0.1, CN=sc-web-gateway [2026-05-13 18:08:29] [INFO] Writing keystore: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/keystore/sc-web-gateway.pfx [2026-05-13 18:08:29] [INFO] (dry-run) Would write /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/keystore/sc-web-gateway.pfx [2026-05-13 18:08:29] [WARNING] Existing cacerts unreadable — seeding from system CA bundle [2026-05-13 18:08:29] [INFO] Seeding from system CA bundle: /etc/pki/tls/cert.pem (143 certs) [2026-05-13 18:08:29] [INFO] Writing truststore: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/trust/cacerts (144 certs) [2026-05-13 18:08:29] [INFO] (dry-run) Would write 144-cert PKCS12 truststore to /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/trust/cacerts [2026-05-13 18:08:29] [INFO] Writing HTTPS.conf: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/sc_service_configs/sc-web-gateway/HTTPS.conf [2026-05-13 18:08:29] [INFO] (dry-run) Would write HTTPS.conf: play.server.https.keyStore.path = "/opt/docker/config/keystore/sc-web-gateway.pfx" play.server.https.keyStore.type = "PKCS12" play.server.https.keyStore.password = "ReallyChangeMe!" [2026-05-13 18:08:29] [INFO] Adding HTTPS.conf include to web-gateway/application.conf [2026-05-13 18:08:29] [WARNING] WEB_GATEWAY_PROTOCOL=https but no HTTPS.conf found at /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/sc_service_configs/web-gateway/HTTPS.conf. Provide this file before starting containers. [2026-05-13 18:08:29] [INFO] === HTTPS preparation complete === Keystore: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/keystore/sc-web-gateway.pfx Truststore: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/trust/cacerts HTTPS.conf: /home/vl/syndeia-cloud-3.7.1-rc.5-docker/config/sc_service_configs/sc-web-gateway/HTTPS.conf Cert SANs: DNS:sc-web-gateway, DNS:localhost, IP:127.0.0.1, CN=sc-web-gateway

Step 4: The .env Environment File

This file will be created and generated during your installation which follows. The file will be owned by the new syndeia-cloud user and be readable only by that user to protect the secrets it contains. To perform later docker stack operations, you will need to run, then, the following command to allow your Linux host user to perform docker compose operations.

sudo chmod a+rw .env

Step 5: Add the License File

Syndeia Cloud requires a license file - and an existing RLM License server, if using a floating license. Please see the licensing pre-requisite for additional details.

  1. Place your license file in the license directory inside of the extracted docker-syndeia-cloud-3.7 package.

# Replace 'user' with your username. cp /home/user/mylicense.lic /home/user/syndeia-cloud-3.7.1-docker/license

Example License File Contents:

HOST <license server hostname/FQDN or ip address> [5053 (default) or designated RLM port] ISV intercax [port=5055 (default) or designated vendor service port]

Stage 4: Execution

Step 6: Run the Setup Script

Run the setup script to perform the initial installation:

sudo python3 setup.py

If the docker stack appears to hang after waiting for Cassandra and Kafka, you might have forgotten Step 5 of the Configuration for licensing sc-web-gateway. You can provide the license and restart the setup.

The script performs the following automatically:

  1. System user creation (Linux only): Creates a syndeia-cloud system user for running application containers.

  2. Secret generation: Generates cryptographic secrets (Play HTTP secret, JWT signing secret, Cassandra password) and writes them to .env.

  3. Docker Compose override: Generates docker-compose.override.yml with platform-appropriate user: directives for each service.

  4. Image validation: Verifies all required images are available in the local Docker daemon.

  5. Container startup: Starts infrastructure containers first, waits for health checks, then starts application services in dependency order.

  6. Init containers: Runs one-time initialization (Cassandra schema creation, JanusGraph graph initialization, superuser account creation).

  7. Health checks: Polls all services until they report healthy or a timeout is reached.

The setup typically takes 3–5 minutes after images are pulled.

Optional Flags

Flag

Description

Flag

Description

--dry-run

Shows what would be done without making changes.

--skip-user-setup

Skips system user creation (use when the user already exists).

--skip-healthcheck

Skips the post-startup health check polling.

--data-dir <path>

Override the default data directory (/var/lib/syndeia-cloud/).

--verbose

Enables detailed logging output.

Step 7. Move to /opt

At this point, your new Syndeia service is deployed. This next step is to relocate it to clean up your home directory and to make the distribution available for maintenance and upgrades.

# bring the docker compose stack down for routine maintenance cd ~/syndeia-cloud-3.7.1-docker # move to the usual /opt/icx folder sudo mkdir -p /opt/icx sudo mv ~/syndeia-cloud-3.7.1-docker /opt/icx/ # bring the stack back up (and detach from it) cd /opt/icx/syndeia-cloud-3.7.1-docker docker compose up -d

Note that, by default, for Syndeia Cloud 3.7.1, this docker deployment will mount the cassandra and kafka data files on your host server at the /var/lib/syndeia-cloud location. This is done to ease your regular backup and restore locations. The updated .env file will reference this location.

This concludes the installation process. We recommend that you perform the Verification steps at this time. Intercax Support will ask you for the status of the Verification steps when you call to request live assistance.

Additional information on various options follows.

3b. Air-Gapped Installation

If the target server does not have access to the Intercax container registry, you can distribute images via an archive (aka tarball) or a private registry mirror.

Option A: Tarball (Offline)

Step 1: Pull and Save Images (on a machine with registry access)

cd /opt/syndeia-cloud-3.7.1 python3 prepare-images.py --source-host c7reg.intercax.com --pull-third-party

Save all images to a tarball:

docker save $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -E 'syndeia|cassandra|kafka|janusgraph') -o syndeia-cloud-images.tar

Step 2: Transfer to Target Server

scp syndeia-cloud-images.tar <user>@<server-ip>:~/

Step 3: Load Images (on target server)

docker load -i ~/syndeia-cloud-images.tar

Then continue with Stage 3 (Configuration) above.

Option B: Private Registry Mirror

Step 1: Pull and Push (on a machine with access to both registries)

python3 prepare-images.py --source-host c7reg.intercax.com --target-host registry.mycompany.com --pull-third-party

Step 2: Configure on Target Server

Edit .env to point to your private registry:

REGISTRY_HOST=registry.mycompany.com REGISTRY_NAMESPACE=syndeia

Then continue with Stage 4 (Execution) above.

4. Service Architecture

4.1 Service Categories

Category

Count

Examples

Category

Count

Examples

Core Services

7

auth, store, graph, web-gateway, pipeline, devops, admin

Integration Services

26

jira, doors-next, teamcenter, cameo, codebeamer, etc.

Operations

1

service-discovery

Infrastructure

3

Cassandra, Kafka, JanusGraph

Init Containers

4

cassandra-init, janusgraph-init, devops-setup, sc-nginx

4.2 Startup Order

Services start in dependency order, enforced by Docker Compose health checks:

  1. Infrastructure: Cassandra and Kafka start in parallel.

  2. Schema Init: Init containers run once infrastructure is healthy (Cassandra schema, JanusGraph graph).

  3. Core Services: auth, store, graph — depend on schema init completion.

  4. Gateway & Pipeline: web-gateway and pipeline — depend on core services.

  5. Integration Services: All 26 integration services — depend on web-gateway.

4.3 Key Ports

Port

Service

Protocol

Port

Service

Protocol

9000

web-gateway

HTTP/HTTPS

56110

auth

HTTP

56120

store

HTTP

56180

graph

HTTP

56135

pipeline

HTTP

56132

devops

HTTP

Only the web-gateway port (9000) is published to the host by default. All other services communicate over the internal Docker network.

5. Configuration

5.1 Environment Variables (.env)

The .env file contains deployment-wide settings. Key variables:

Variable

Description

Variable

Description

REGISTRY_HOST

Container registry hostname

REGISTRY_NAMESPACE

Registry namespace/organization

SYNDEIA_VERSION

Image tag for all Syndeia services

PLAY_HTTP_SECRET_KEY

Play Framework HTTP secret (auto-generated)

JWT_SHARED_SECRET

JWT signing secret (auto-generated)

CASSANDRA_PASSWORD

Cassandra syndeia_admin password (auto-generated)

SC_UID

UID for application containers (default: system user UID)

LICENSE_SERVER_HOST

Floating license server hostname

5.2 Service Configuration

Each service has its own HOCON configuration file at:

config/sc_service_configs/<service-name>/application.conf

These are Docker volume bind-mounted into the containers. Edit them directly for service-specific customization.

(Docker volume bind mounts live outside the Docker containers. They are editable on the host and they persist even if the docker named-mount volumes are removed.)

5.3 Shared Overrides (sc-docker-overrides.conf)

The file config/sc-docker-overrides.conf contains settings shared across all services, including service discovery URLs. This file is generated by setup.py and should not be edited manually — it is regenerated on every install and upgrade.

5.4 Docker Compose Override (docker-compose.override.yml)

Platform-specific settings (primarily user: directives) are managed in the override file. On Linux, setup.py generates this automatically with the correct UID/GID mappings. Do not edit this file manually.

6. HTTPS Configuration

To enable HTTPS on the web-gateway:

  1. Place your keystore in config/keystore/.

  2. Create or edit config/sc_service_configs/web-gateway/HTTPS.conf:

https.port=9443 play.server.https.keyStore.path="/opt/syndeia-cloud/config/keystore/your-keystore.jks" play.server.https.keyStore.password="your-keystore-password"

  1. Update docker-compose.override.yml to publish port 9443:

services: web-gateway: ports: - "9443:9443"

  1. Restart the web-gateway:

docker compose restart web-gateway

7. Verification

After installation, run the following checks.

7.1 Check All Services

docker compose ps

All services should show healthy status. Infrastructure services (Cassandra, Kafka, JanusGraph) should show running (healthy).

7.2 Check Core Ports

for port in 9000 56110 56120 56180 56135 56132; do ss -tlnp | grep -q ":${port} " && echo "Port ${port} OK" || echo "Port ${port} MISSING" done

7.3 Login Test

Command line:

curl -s -X POST 'http://127.0.0.1:9000/signIn' \ -H 'Content-Type: application/json' \ -d '{"username":"super.user","password":"syn45ia","rememberMe":true}' \ | grep -q '"statusCode":201' && echo "Login OK" || echo "Login FAILED"

The default superuser password is syn45ia. We recommend that you change it after your first login.

Browser:

Open http://<server-ip>:9000 in a browser.

# in your Chrome, Edge, Safari, Firefox browser address bar http://<server-ip>:9000

If the web-gateway listens on 127.0.0.1, you might use an SSH tunnel to expose the Syndeia service to other nodes of your network. This is not typical:

ssh -L 9000:127.0.0.1:9000 <user>@<server-ip>

Then you can browse to http://localhost:9000 on the machine running the tunnel and connect to your Syndeia service running within your Syndeia server.

7.4 Check Logs

To view logs for a specific service:

docker compose logs -f <service-name>

To view logs for all services:

docker compose logs -f --tail=50

8. Troubleshooting

8.1 Image Pull Fails

Verify registry connectivity:

docker login c7reg.intercax.com docker pull c7reg.intercax.com/syndeia/web-gateway:3.7.1

If the registry requires authentication, log in first. For air-gapped environments, see Section 3b.

8.2 Service Fails Health Check

Check the service log:

docker compose logs <service-name> --tail=100

Common causes:

  • Cassandra not ready: Core services depend on Cassandra. Check docker compose logs cassandra.

  • Configuration error: Verify the service's application.conf for syntax errors.

  • Port conflict: Another process may be using a required port. Check with ss -tlnp | grep <port>.

8.3 Permission Denied on Config or Data Files

On Linux, the setup.py script sets up a syndeia-cloud system user and generates a docker-compose.override.yml with the correct UID/GID mappings. If you see permission errors:

# Check the override file exists cat docker-compose.override.yml # Verify the syndeia-cloud user exists id syndeia-cloud # Re-run setup to regenerate the override sudo python3 setup.py --skip-healthcheck

8.4 Container Stuck in "Restarting"

A container in a restart loop usually indicates a configuration or dependency issue:

docker compose logs <service-name> --tail=50

If a dependency service is down, fix it first — dependent services will recover automatically.

8.5 Secrets Lost After Re-running Setup

The setup script preserves existing secrets in .env on subsequent runs. If secrets were lost, check that .env was not deleted or overwritten. The previous .env may be recoverable from the backup created during upgrade (.env.backup).

8.6 License Issues

Verify the license configuration:

  • Floating license: Ensure LICENSE_SERVER_HOST in .env is set and the license server is reachable from the Docker host.

  • Node-locked license: Ensure the license file is in the license/ directory and the hostname matches.

Check the web-gateway log for license errors:

docker compose logs web-gateway | grep -i license

8.7 Re-running After Failure

The setup script is idempotent. Fix the reported issue and re-run:

sudo python3 setup.py

No cleanup is needed between attempts.

8.8 Your kernel does not support memory limit capabilities or the cgroup is not mounted. Limitation discarded.

A cgroup ("control group") is a Linux kernel feature that lets you bundle a set of processes together and apply resource limits, accounting, and isolation to that bundle as a unit. Where namespaces answer "what can this process see?", cgroups answer "how much can this process use?"

During docker compose up, if the message “Your kernel does not support memory limit capabilities or the cgroup is not mounted. Limitation discarded.” occurs then your chosen Linux kernel either intentionally lacks or has disabled the “memory” cgroup capability.

To remove this warning, you may:

  • Enable the memory cgroup capability in your OS (see OS documentation for that)

  • Switch to a kernel which offers the memory cgroup support (see your OS and Cloud Provider documentation)

  • Remove the memory limit settings in the docker-compose.yml file

The memory limits are meant to be useful under peak utilization and likely the images will operate well without the limits.