Docker Compose Installation

info

See Obtaining the Software for how to get the cirata-symphony-<version>-docker.tar.gz installation archive.

This is the recommended installation method for most deployments. It provides a self-contained bundle with Symphony, an nginx reverse proxy for TLS termination and WebSocket support, and an optional bundled Keycloak OIDC provider.

Choosing an Authentication Approach

Symphony requires an OpenID Connect (OIDC) provider for user authentication. There are two options:

• Bundled Keycloak (recommended for standalone deployments)—the Docker Compose bundle includes an optional Keycloak overlay that runs a fully-configured OIDC provider alongside Symphony. This is the simplest way to get a working installation because all OIDC settings, client registrations, and realm configuration are pre-configured. No external services are required—everything runs on a single machine. Use this approach unless your organisation already operates a centralised identity provider.

• External OIDC provider—if you already have an identity provider such as Auth0, Okta, Microsoft Entra ID, or an existing Keycloak deployment, you can point Symphony at it instead. This requires you to create client registrations in your provider. The issuer URL and client IDs can be entered in the setup wizard on first start, or supplied in advance via environment variables for automated deployments.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• A hostname or IP address that resolves to this machine (or localhost for local evaluation). A /etc/hosts entry on the host is sufficient — the bundle wires the same hostname into the compose network, so the Symphony container's first-run validation does not require real DNS.

Quick Start with Bundled Keycloak

This is the fastest path to a working Symphony installation. It starts Symphony, nginx, and Keycloak together with all OIDC settings pre-configured. Self-signed TLS certificates are generated automatically.

1. Extract the archive

tar xzf cirata-symphony-*-docker.tar.gz
cd symphony-*-docker

2. Load the container image

docker load -i images/cirata-*.tar

3. Configure your environment

cp env.keycloak.example .env

Edit .env and set the following values:

Variable	Description	Example
EXTERNAL_HOSTNAME	DNS name or IP for this machine	symphony.example.com
KEYCLOAK_ADMIN_PASSWORD	Password for the Keycloak admin account	(choose a strong password)

These are the only two values you need to set. The OIDC issuer, client IDs, and internal networking are all configured automatically by the Keycloak overlay.

4. Start Symphony

docker compose -f docker-compose.yml -f docker-compose.keycloak.yml up -d

This starts four containers:

Container	Purpose
symphony-certgen	Generates a self-signed TLS certificate (runs once, then exits)
symphony	Symphony application server
symphony-nginx	nginx reverse proxy (TLS, WebSocket, NATS passthrough)
symphony-keycloak	Keycloak OIDC provider

5. Complete the setup wizard

Open https://<EXTERNAL_HOSTNAME> in your browser. Because this is a first-time start, Symphony presents an administration setup wizard.

The OIDC fields are pre-populated with the correct values for the bundled Keycloak. Review the settings, set a product name if desired, and complete the wizard.

note

Your browser will show a certificate warning because the auto-generated certificate is self-signed. This is expected — accept the warning to continue. See TLS Certificates to install production certificates.

6. Create users in Keycloak

After Symphony is running, you need to create user accounts in Keycloak so that people can sign in.

1. Open the Keycloak admin console at https://<EXTERNAL_HOSTNAME>/auth
2. Sign in with username admin and the password you set in .env
3. Select the symphony realm from the dropdown in the top-left corner
4. Navigate to Users and click Create new user
5. Fill in the username and email, then click Create
6. Go to the Credentials tab, click Set password, enter a password, and toggle Temporary off if you do not want the user to be forced to change it on first login
7. Click Save

Users can now sign in to Symphony at https://<EXTERNAL_HOSTNAME> using these credentials.

Installation with an External OIDC Provider

If you already have an OIDC provider, use this approach instead.

1. Extract and load

tar xzf cirata-symphony-*-docker.tar.gz
cd symphony-*-docker
docker load -i images/cirata-*.tar

2. Configure your environment

cp env.example .env

Edit .env and set the hostname:

Variable	Description	Example
EXTERNAL_HOSTNAME	Public DNS name for Symphony	symphony.example.com

OIDC values can optionally be set here to pre-populate the setup wizard, which is useful for automated deployments:

Variable	Description	Example
OIDC_ISSUER	OIDC provider domain and path (no https:// prefix)	auth.example.com/realms/symphony
OIDC_CLIENTID	OIDC client ID for the API (confidential client, no login flow)	symphony-api
OIDC_UICLIENTID	OIDC client ID for the UI (public client, authorization code flow)	symphony-ui
OIDC_CLIENTSECRET	Client secret for the API client (optional, for confidential clients)
OIDC_UICLIENTSECRET	Client secret for the UI client (optional, for confidential UI clients)

If you leave the OIDC variables unset, you will enter them in the setup wizard instead.

3. Start Symphony

docker compose up -d

4. Complete setup

Open https://<EXTERNAL_HOSTNAME> in your browser and follow the administration setup wizard. The wizard provides OIDC issuer and client ID fields along with a Validate Configuration button that checks your DNS and OIDC settings before you submit. Each check includes a description of any issue and instructions for resolving it.

tip

For help registering clients with your identity provider, see OIDC Configuration. For a detailed explanation of each validation check, see Setup Wizard Validation.

Using the CLI

The cirata CLI tool lets you manage Symphony from the terminal. CLI binaries for Linux, macOS, and Windows are included in the installation archive under the cli/ directory. Copy the binary for your platform to a directory in your PATH:

# Example: install the Linux binary
chmod +x cli/cirata-linux-amd64
sudo mv cli/cirata-linux-amd64 /usr/local/bin/cirata

You can also copy the server's own binary from the running container:

docker compose cp symphony:/cirata ./cirata
chmod +x ./cirata

See the Command-Line Tool page for full setup and usage instructions.

Managing the Installation

# View logs
docker compose logs -f

# View logs for a specific service
docker compose logs -f symphony

# Stop
docker compose down

# Upgrade: load new image, then recreate containers
docker load -i images/cirata-NEW_VERSION.tar
docker compose up -d

# Back up configuration — the built-in command produces a consistent
# archive of the running instance. See /help/operation for alternatives.
cirata symphony backup --output ./backup.tar

When using the Keycloak overlay, remember to include both compose files in every command:

docker compose -f docker-compose.yml -f docker-compose.keycloak.yml logs -f
docker compose -f docker-compose.yml -f docker-compose.keycloak.yml down
docker compose -f docker-compose.yml -f docker-compose.keycloak.yml up -d

tip

To avoid typing the file flags every time, set the COMPOSE_FILE environment variable:

export COMPOSE_FILE=docker-compose.yml:docker-compose.keycloak.yml
docker compose up -d    # now uses both files automatically

Customising Ports

Override the default ports by setting these variables in .env:

Variable	Default	Description
HTTPS_PORT	443	HTTPS port
HTTP_PORT	80	HTTP redirect port
NATS_PORT	4222	NATS messaging port

TLS Certificates

A self-signed certificate is generated automatically on first start using EXTERNAL_HOSTNAME as the common name. This is suitable for evaluation and development.

For production, replace the certificates in the tls-certs Docker volume:

# Copy your production certificates into the running nginx container
docker compose cp ./fullchain.pem nginx:/etc/nginx/certs/fullchain.pem
docker compose cp ./privkey.pem nginx:/etc/nginx/certs/privkey.pem
docker compose restart nginx

The certificate files must be named fullchain.pem (certificate chain) and privkey.pem (private key) in PEM format.

To regenerate the self-signed certificate (e.g. after changing the hostname), remove the volume and restart:

docker compose down
docker volume rm $(docker volume ls -q | grep tls-certs)
docker compose up -d

NATS TLS

To encrypt native NATS connections (port 4222) used by extensions and CLI tools, provide a TLS certificate and key via environment variables. Add these to your .env file or docker-compose.yml:

services:
  symphony:
    environment:
      - NATS_TLS_CERT=/certs/nats/tls.crt
      - NATS_TLS_KEY=/certs/nats/tls.key
    volumes:
      - ./nats-certs:/certs/nats:ro

When both variables are set, the NATS server requires TLS on all connections. Client SDKs automatically attempt TLS using system CAs. For certificates signed by a private CA, extensions can set SYMPHONY_TLS_CA to the path of the CA certificate — this trust anchor applies to both the HTTPS registration exchange and NATS. NATS_TLS_CA remains supported as a NATS-only override.

Hostname resolution without real DNS

Containers do not inherit the host's /etc/hosts. The bundle handles the common case automatically: nginx is published inside the compose network under ${EXTERNAL_HOSTNAME} so the Symphony container can reach itself during first-run validation regardless of host DNS.

If your external OIDC provider hostname is also only resolvable via /etc/hosts, add a mapping for it in a docker-compose.override.yml file. A template is shipped with the bundle:

cp docker-compose.override.yml.example docker-compose.override.yml
# edit docker-compose.override.yml to set host:ip pairs
docker compose up -d

Compose loads docker-compose.override.yml automatically — no -f flag needed.

Troubleshooting

• Certificate warnings in browser—the auto-generated self-signed certificate will show browser warnings. This is expected for evaluation deployments. Replace with production certificates for public-facing installations.
• Connection refused—check that ports 80, 443, and 4222 are not blocked by a firewall. Run docker compose ps to verify all containers are running.
• OIDC errors after setup—verify that your OIDC issuer URL is reachable from the Symphony container and that client IDs are correct. For the bundled Keycloak, check that the symphony-keycloak container is running with docker compose logs keycloak. If the OIDC hostname is /etc/hosts-only on the host, see Hostname resolution without real DNS. See Setup Wizard Validation for a detailed guide to diagnosing OIDC configuration issues.
• Users cannot sign in (bundled Keycloak)—ensure you have created user accounts in Keycloak under the symphony realm. See Create users in Keycloak above.
• WebSocket errors in browser console—check that the nginx container is running and that port 443 is accessible. WebSocket connections use the same HTTPS port as the UI.