Skip to main content

RPM Installation

info

See Obtaining the Software for how to get the cirata-symphony-<version>.x86_64.rpm package.

Install Symphony on RPM-based Linux distributions (RHEL 9+, Fedora, SLES, or similar) using the native package manager. The RPM handles user creation, systemd service installation, and directory setup automatically.

For Debian/Ubuntu systems or environments where you prefer a manual installation from a tarball, see Linux Installation instead.

Prerequisites​

  • An RPM-based Linux distribution (RHEL 9+, Fedora 39+, SLES 15+, or similar)
  • A reverse proxy to terminate TLS and front Symphony—either on-box nginx (a template is shipped with the RPM) or an external proxy/load balancer (HAProxy, AWS ALB, Azure Application Gateway, F5, etc.)
  • A DNS name that resolves to this machine or to the external proxy
  • TLS certificates for your domain
  • An OIDC provider (Auth0, Keycloak, Okta, or similar)

Quick Start​

1. Install the package​

sudo dnf install cirata-symphony-<version>.x86_64.rpm

On SLES or older distributions, use zypper or rpm instead:

# SLES
sudo zypper install cirata-symphony-<version>.x86_64.rpm

# Direct RPM install (any distribution)
sudo rpm -ivh cirata-symphony-<version>.x86_64.rpm

The package will:

  • Create a symphony system user and group
  • Install the binary to /usr/bin/cirata
  • Install a systemd service unit, sysusers, and tmpfiles configurations
  • Create the configuration directory at /etc/symphony/
  • Install an nginx configuration template at /etc/symphony/nginx.conf.template
  • Create the state directory at /var/lib/symphony/
  • Create the log directory at /var/log/symphony/

2. Configure the environment​

sudo cp /etc/symphony/symphony.env.example /etc/symphony/symphony.env
sudo vi /etc/symphony/symphony.env

Set EXTERNAL_HOSTNAME to your public DNS hostname. OIDC values can optionally be set here or entered in the setup wizard.

3. Configure a reverse proxy​

Symphony serves its UI and API on internal HTTP port 8080 and its WebSocket server on port 9222. These must be fronted by a reverse proxy that terminates TLS and forwards traffic correctly. The RPM does not install or start a proxy—choose one of the two approaches below.

Option A — On-box nginx (using the shipped template)​

The RPM installs a site-configuration template at /etc/symphony/nginx.conf.template. Install nginx via your package manager, then deploy the template:

sudo dnf install nginx   # or: sudo zypper install nginx

sudo sed "s/SYMPHONY_HOSTNAME/$(hostname -f)/g" \
    /etc/symphony/nginx.conf.template \
    | sudo tee /etc/nginx/conf.d/symphony.conf >/dev/null

sudo nginx -t && sudo systemctl enable --now nginx && sudo systemctl reload nginx

The template handles HTTPS termination on port 443 (proxied to port 8080), WebSocket upgrades on /ws (proxied to port 9222), and an HTTP-to-HTTPS redirect on port 80. It expects TLS certificates at /etc/nginx/certs/symphony/fullchain.pem and privkey.pem—see TLS Certificates below.

For optional NATS passthrough and other configuration details, see the Linux installation nginx guide.

Option B — External reverse proxy or load balancer​

For deployments that terminate TLS on an upstream proxy (HAProxy, AWS ALB/NLB, Azure Application Gateway, F5, nginx on a separate host, etc.), configure the proxy to forward traffic to the Symphony host:

IncomingBackendNotes
HTTPS :443http://<host>:8080UI and API
WSS :443 path /wsws://<host>:9222WebSocket; requires upgrade headers
TCP :4222<host>:4222NATS, plain TCP passthrough (no TLS termination)

Requirements for the upstream proxy:

  • Forward the Host, X-Real-IP, X-Forwarded-For, and X-Forwarded-Proto headers to Symphony.
  • Forward Upgrade and Connection: upgrade headers on the /ws path and set the WebSocket idle timeout to at least 86400 seconds.
  • Use a health-check endpoint of GET http://<host>:8080/api/v1/ping (returns 200 when Symphony is running).
  • The NATS port (4222) is a separate TCP stream—if your proxy fronts it, use raw TCP passthrough, not HTTP. Most deployments expose NATS directly on the host instead.

TLS is handled entirely on the external proxy; certificates do not need to be installed on the Symphony host.

The nginx configuration template at /etc/symphony/nginx.conf.template is not used in this mode and can be ignored or removed.

4. Start Symphony​

sudo systemctl enable --now symphony

5. 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.

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.

VariableDefaultDescriptionUsed at
EXTERNAL_HOSTNAME(required)Public DNS hostnameSetup only
LISTEN_ADDRESS0.0.0.0Listen addressSetup only
UI_PORT8080Internal HTTP portSetup only
WEBSOCKET_PORT9222Internal WebSocket portSetup only
NATS_PORT4222Internal NATS portSetup 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 wizardSetup only
OIDC_CLIENTID(optional)OIDC client ID for the API—can also be entered in the setup wizardSetup only
OIDC_UICLIENTID(optional)OIDC client ID for the UI—can also be entered in the setup wizardSetup only
OIDC_CLIENTSECRET(optional)Client secret for the API client (for confidential clients such as Auth0 M2M)—can also be entered in the setup wizardSetup only
OIDC_UICLIENTSECRET(optional)Client secret for the UI client (for confidential UI clients)—can also be entered in the setup wizardSetup 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 URLRuntime

TLS Certificates​

The RPM does not ship TLS certificates. Where you install them depends on which proxy approach you chose in Configure a reverse proxy:

  • On-box nginx (Option A): install your certificates at the paths referenced by the shipped template (/etc/nginx/certs/symphony/fullchain.pem and privkey.pem), or edit the deployed nginx configuration to match your existing layout. See the Linux installation TLS guide for further detail.
  • External proxy (Option B): install certificates on the upstream proxy or load balancer. No certificates are needed on the Symphony host.

Using the CLI​

The RPM package installs the server binary at /usr/bin/cirata, which also functions as a CLI tool on the server itself. For client machines, distribute the appropriate CLI binary from the Linux installation archive or download it separately from the Cirata customer portal.

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

File Locations​

PathPurpose
/usr/bin/cirataSymphony binary
/etc/symphony/symphony.envInitial setup configuration (optional after first run)
/etc/symphony/symphony.env.exampleExample environment file
/etc/symphony/nginx.conf.templatenginx reverse-proxy configuration template
/var/lib/symphony/Runtime data (configuration, accounts, storage)
/var/log/symphony/Log directory
/run/symphony/Runtime directory
/usr/lib/systemd/system/symphony.servicesystemd unit
/usr/lib/sysusers.d/symphony.confsysusers configuration
/usr/lib/tmpfiles.d/symphony.conftmpfiles configuration

systemd Service​

The RPM installs a hardened systemd service unit with security restrictions enabled by default. The service runs as the symphony user and includes protections such as ProtectSystem=strict, NoNewPrivileges=true, and restricted address families.

# View the installed unit file
systemctl cat symphony

# Check security restrictions
systemd-analyze security symphony

Log Retention​

Symphony logs to stdout in structured JSON format. When running under systemd, journald captures all output automatically. To configure persistent storage and bounded retention, create a journald drop-in:

sudo mkdir -p /etc/systemd/journald.conf.d
cat <<'EOF' | sudo tee /etc/systemd/journald.conf.d/symphony.conf
[Journal]
Storage=persistent
SystemMaxUse=2G
MaxRetentionSec=3month
EOF
sudo systemctl restart systemd-journald

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

Upgrading​

sudo dnf upgrade cirata-symphony-<new-version>.x86_64.rpm

The package upgrade restarts the service automatically via the systemd post-uninstall scriptlet.

Uninstalling​

sudo dnf remove cirata-symphony

This stops the service and removes all installed files. The data directory at /var/lib/symphony/ and configuration at /etc/symphony/ are preserved by default (RPM does not remove modified config files or user data directories).

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 removing it.

To fully clean up after removal:

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

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

# Remove log directory
sudo rm -rf /var/log/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.
  • Reverse-proxy errors (on-box nginx)—run nginx -t to validate configuration. Ensure the nginx configuration proxies HTTPS to port 8080 and WebSocket to port 9222.
  • Reverse-proxy errors (external proxy)—confirm the upstream proxy can reach the Symphony host on ports 8080 and 9222. Check the proxy's access and error logs for upstream connection failures and verify the health-check endpoint (GET /api/v1/ping on port 8080) returns 200.
  • Certificate warnings in browser—install production TLS certificates as described in TLS Certificates.
  • WebSocket errors in browser console—verify that traffic on the /ws path is forwarded to port 9222 with the Upgrade and Connection: upgrade headers preserved. For on-box nginx, the /ws location block must also set proxy_http_version 1.1.
  • 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 symphony user owns /var/lib/symphony/. Run rpm -V cirata-symphony to check installed file permissions.
  • SELinux denials—if SELinux is enforcing, check audit2allow for any denials related to the symphony service.