Linux Installation

info

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

Install Symphony as a native Linux service using systemd and nginx. This method is suitable for bare-metal servers and virtual machines where containers are not available or desired.

tip

On RPM-based distributions (RHEL, Fedora, SLES), you can also install via the native package manager. See RPM Installation for details.

Prerequisites

Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+, or similar)
nginx (for HTTPS termination and reverse proxying)
A DNS name that resolves to this machine
TLS certificates for your domain
An OIDC provider (Auth0, Keycloak, Okta, or similar)

Quick Start

1. Extract the archive

tar xzf cirata-symphony-*-linux-amd64.tar.gz
cd symphony-*-linux-amd64

2. Run the setup script

sudo ./setup.sh --hostname symphony.example.com

To run the service as a different system user, pass --user (and optionally --group):

sudo ./setup.sh --hostname symphony.example.com --user myuser
sudo ./setup.sh --hostname symphony.example.com --user myuser --group mygroup

The setup script will:

Create a system user (default: symphony, or the name given to --user)
Install the binary to /usr/local/bin/cirata
Create the configuration directory at /etc/symphony/
Install and enable a systemd service unit
Configure nginx as a reverse proxy (if installed)
Generate a self-signed TLS certificate (replace for production)

3. Start Symphony

The EXTERNAL_HOSTNAME is set automatically by the setup script. The remaining network variables (LISTEN_ADDRESS, UI_PORT, WEBSOCKET_PORT, NATS_PORT) can be left at their defaults.

sudo systemctl enable --now symphony

4. Complete setup

Open https://<hostname> in your browser. Symphony presents an administration setup wizard on first start. The wizard includes fields for your OIDC issuer, API client ID, and UI client ID. Enter these values in the wizard and use the Validate Configuration button to check your DNS and OIDC settings before submitting. 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.

Manual Installation

If you prefer not to use setup.sh, perform the steps manually:

# Install binary
sudo install -m 755 bin/cirata /usr/local/bin/cirata

# Create user and directories
sudo useradd --system --shell /usr/sbin/nologin symphony
sudo mkdir -p /etc/symphony /var/lib/symphony
sudo chown symphony:symphony /var/lib/symphony
sudo chmod 700 /var/lib/symphony

# Install environment configuration
sudo cp etc/symphony/symphony.env.example /etc/symphony/symphony.env
sudo chmod 600 /etc/symphony/symphony.env

# Edit the environment file — set EXTERNAL_HOSTNAME at minimum
# OIDC values can be entered here or in the setup wizard
sudo vi /etc/symphony/symphony.env

# Install systemd service
sudo cp lib/systemd/system/symphony.service /etc/systemd/system/
sudo systemctl daemon-reload

Then configure nginx using etc/nginx/symphony-nginx.conf as a template.

nginx Configuration

The included nginx configuration handles:

HTTPS termination—port 443 proxied to Symphony on port 8080
WebSocket upgrade—/ws path proxied to port 9222
HTTP redirect—port 80 redirected to HTTPS

Install the configuration. nginx uses different site-config layouts on different distributions:

Debian / Ubuntu (sites-available / sites-enabled):

sudo cp etc/nginx/symphony-nginx.conf /etc/nginx/sites-available/symphony
sudo ln -sf /etc/nginx/sites-available/symphony /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

RHEL / Fedora / Rocky / SLES (conf.d):

sudo cp etc/nginx/symphony-nginx.conf /etc/nginx/conf.d/symphony.conf
sudo nginx -t && sudo systemctl reload nginx

tip

The template contains SYMPHONY_HOSTNAME as a placeholder. If you are installing manually rather than via setup.sh, substitute your hostname first:

sudo sed -i "s/SYMPHONY_HOSTNAME/$(hostname -f)/g" \
    /etc/nginx/conf.d/symphony.conf        # or sites-available/symphony

Optional: NATS passthrough

By default, extensions connect to the NATS port (4222) directly on the host and nginx is not involved.

tip

Symphony supports native NATS TLS—if your goal is to encrypt NATS connections, configure the NATS_TLS_CERT and NATS_TLS_KEY environment variables instead of proxying through nginx. See the NATS TLS configuration guide and the Environment Variables table below for details.

If you still need nginx to proxy NATS traffic for other reasons (for example, to consolidate all traffic through a single port or to apply nginx access controls), install the nginx stream module for your distribution:

# Debian / Ubuntu
sudo apt install libnginx-mod-stream

# RHEL / Fedora / Rocky
sudo dnf install nginx-mod-stream

# SLES / openSUSE
sudo zypper install nginx-module-stream

Then add the following stream block. It must live at the top-level context of nginx's configuration (outside the http block), which on most distributions means editing /etc/nginx/nginx.conf directly— stream{} blocks cannot go inside files included from conf.d/ or sites-enabled/, because those are included inside http{}.

stream {
    upstream nats_backend {
        server 127.0.0.1:4222;
    }
    server {
        listen 4222;
        proxy_pass nats_backend;
    }
}

Environment Variables

The environment file at /etc/symphony/symphony.env seeds the admin setup wizard on first start. Values set here pre-populate the wizard fields, but the administrator can review and change them before submitting. After initial configuration, Symphony writes persistent config to /var/lib/symphony/ and the environment file is no longer required for normal operation.

tip

OIDC values do not need to be set in the environment file. The setup wizard provides fields for the issuer URL and client IDs, along with a Validate Configuration button that checks them against the identity provider. Entering OIDC details in the wizard is the recommended approach because it provides immediate feedback on configuration errors. Environment variables are primarily useful for automated or scripted deployments. See Setup Wizard Validation for details on each check.

Variable	Default	Description	Used at
`EXTERNAL_HOSTNAME`	(required)	Public DNS hostname	Setup only
`LISTEN_ADDRESS`	`0.0.0.0`	Listen address	Setup only
`UI_PORT`	`8080`	Internal HTTP port	Setup only
`WEBSOCKET_PORT`	`9222`	Internal WebSocket port	Setup only
`NATS_PORT`	`4222`	Internal NATS port	Setup only
`NATS_TLS_CERT`	(unset)	Path to NATS server TLS certificate (PEM). Enables native NATS TLS when set with `NATS_TLS_KEY`.	Runtime
`NATS_TLS_KEY`	(unset)	Path to NATS server TLS private key (PEM)	Runtime
`NATS_TLS_CA`	(unset)	Path to CA certificate for NATS client verification (optional)	Runtime
`OIDC_ISSUER`	(optional)	OIDC issuer domain and path (no `https://` prefix)—can also be entered in the setup wizard	Setup only
`OIDC_CLIENTID`	(optional)	OIDC client ID for the API—can also be entered in the setup wizard	Setup only
`OIDC_UICLIENTID`	(optional)	OIDC client ID for the UI—can also be entered in the setup wizard	Setup only
`OIDC_CLIENTSECRET`	(optional)	Client secret for the API client (for confidential clients such as Auth0 M2M)—can also be entered in the setup wizard	Setup only
`OIDC_UICLIENTSECRET`	(optional)	Client secret for the UI client (for confidential UI clients)—can also be entered in the setup wizard	Setup only
`OIDC_CA_CERT`	(unset)	Path to a PEM CA certificate file for verifying the OIDC provider's TLS certificate (recommended for self-signed certs). Validated during setup when set.	Runtime
`OIDC_TLS_SKIP_VERIFY`	(unset)	Set to `true` to skip TLS verification — can also be set via the Disable TLS Verification switch in the setup wizard. Use `OIDC_CA_CERT` for production.	Runtime
`OIDC_INTERNAL_BASE_URL`	(unset)	Internal URL for the OIDC provider if different from the public issuer URL	Runtime

TLS Certificates

The setup script generates a self-signed TLS certificate at /etc/nginx/certs/symphony/. This is suitable for evaluation and development.

For production, replace the certificate files and reload nginx:

sudo cp fullchain.pem /etc/nginx/certs/symphony/fullchain.pem
sudo cp privkey.pem /etc/nginx/certs/symphony/privkey.pem
sudo systemctl reload nginx

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

Using the CLI

The installation archive includes CLI binaries for all supported platforms in the cli/ directory. Distribute the appropriate binary to users who need terminal access to Symphony:

File	Platform
`cli/cirata-linux-amd64`	Linux (AMD64)
`cli/cirata-darwin-arm64`	macOS (Apple Silicon)
`cli/cirata-windows-amd64.exe`	Windows (AMD64)

The server binary installed at /usr/local/bin/cirata also functions as a CLI tool on the server itself.

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

File Locations

Path	Purpose
`/usr/local/bin/cirata`	Symphony binary
`/etc/symphony/symphony.env`	Initial setup configuration (optional after first run)
`/var/lib/symphony/`	Runtime data (configuration, accounts, storage)
`/etc/systemd/system/symphony.service`	systemd unit
`/etc/systemd/journald.conf.d/symphony.conf`	journald log retention settings
`/etc/nginx/sites-available/symphony` (Debian/Ubuntu) or `/etc/nginx/conf.d/symphony.conf` (RHEL/Fedora/SLES)	nginx site configuration
`/etc/nginx/certs/symphony/`	TLS certificate and private key

Log Retention

Symphony logs to stdout in structured JSON format. When running under systemd, journald captures all output automatically. To ensure logs survive reboots and are bounded in size, install the bundled journald drop-in configuration:

sudo mkdir -p /etc/systemd/journald.conf.d
sudo cp lib/systemd/journald-symphony.conf /etc/systemd/journald.conf.d/symphony.conf
sudo systemctl restart systemd-journald

This configures persistent storage, 2 GB maximum disk usage, and 3-month retention. Without the drop-in, some distributions default to volatile journal storage (logs lost on reboot).

Managing the Installation

# View logs (structured JSON)
sudo journalctl -u symphony -f

# View logs for a specific time range
sudo journalctl -u symphony --since "1 hour ago"

# Restart
sudo systemctl restart symphony

# Check status
sudo systemctl status symphony

# Upgrade: replace binary and restart
sudo install -m 755 bin/cirata /usr/local/bin/cirata
sudo systemctl restart symphony

Uninstalling

To completely remove Symphony and all its data from the system, run the bundled uninstall script from the installation archive:

sudo ./uninstall.sh

The script stops the service, removes all installed files, and deletes the symphony system user. By default it also removes the data directory at /var/lib/symphony/. To keep the data directory (for example, to preserve cryptographic keys for a future reinstall), pass --keep-data:

sudo ./uninstall.sh --keep-data

warning

The data directory at /var/lib/symphony/ contains the platform's cryptographic identity keys and all persistent state. Once deleted, this data cannot be recovered. Back up this directory before uninstalling if you may need it later.

Manual Uninstall

If you no longer have the installation archive, perform the steps manually:

# Stop and disable the service
sudo systemctl stop symphony
sudo systemctl disable symphony

# Remove systemd unit and reload
sudo rm -f /etc/systemd/system/symphony.service
sudo systemctl daemon-reload

# Remove nginx configuration (whichever layout your distribution uses)
sudo rm -f /etc/nginx/sites-enabled/symphony /etc/nginx/sites-available/symphony   # Debian/Ubuntu
sudo rm -f /etc/nginx/conf.d/symphony.conf                                          # RHEL/Fedora/SLES
sudo rm -rf /etc/nginx/certs/symphony/
nginx -t 2>/dev/null && sudo systemctl reload nginx

# Remove journald drop-in
sudo rm -f /etc/systemd/journald.conf.d/symphony.conf

# Remove binary
sudo rm -f /usr/local/bin/cirata

# Remove configuration
sudo rm -rf /etc/symphony/

# Remove data (WARNING: irreversible — back up first if needed)
sudo rm -rf /var/lib/symphony/

# Remove system user and group
sudo userdel symphony 2>/dev/null

Troubleshooting

Service won't start—check journalctl -u symphony for error messages. On first run, verify that /etc/symphony/symphony.env exists with at least the EXTERNAL_HOSTNAME value set. OIDC values are optional in the environment file and can be entered in the setup wizard instead. After initial setup, the environment file is optional—Symphony reads its config from /var/lib/symphony/.
nginx errors—run nginx -t to validate configuration. If you have configured optional NATS passthrough, ensure the stream module is installed (libnginx-mod-stream on Debian/Ubuntu, nginx-mod-stream on RHEL/Fedora/Rocky, nginx-module-stream on SLES/openSUSE).
Certificate warnings in browser—the auto-generated self-signed certificate will show browser warnings. Replace with production certificates as described in TLS Certificates.
WebSocket errors in browser console—verify that the /ws location block in your nginx configuration is proxying to port 9222 with proxy_http_version 1.1 and the Upgrade headers set.
OIDC errors—verify the OIDC_ISSUER value does not include the https:// prefix—Symphony adds it automatically. If your OIDC provider uses an internal URL that differs from the public issuer, set OIDC_INTERNAL_BASE_URL in the environment file. See Setup Wizard Validation for a detailed guide to diagnosing OIDC configuration issues.
Permission denied—verify the service user (default symphony) owns /var/lib/symphony/. If this is a first-time setup, also check that /etc/symphony/symphony.env is readable by the service user.

Prerequisites​

Quick Start​

1. Extract the archive​

2. Run the setup script​

3. Start Symphony​

4. Complete setup​

Manual Installation​

nginx Configuration​

Optional: NATS passthrough​

Environment Variables​

TLS Certificates​

Using the CLI​

File Locations​

Log Retention​

Managing the Installation​

Uninstalling​

Manual Uninstall​

Troubleshooting​