Installing Cirata Symphony

Symphony can be installed using one of four methods, depending on your infrastructure and operational preferences:

• Docker Compose—the recommended approach for most deployments. Provides a self-contained bundle with an nginx reverse proxy and optional bundled Keycloak for OIDC authentication. With bundled Keycloak, a working installation requires only setting a hostname and password—no external identity provider is needed. Requires Docker and Docker Compose.

• Linux—a bare-metal installation using a standalone binary, systemd, and nginx. Suitable for environments where containers are not available or desired. Works on any Linux distribution.

• RPM—install via the native package manager on RPM-based distributions (RHEL 9+, Fedora, SLES). The RPM handles user creation, systemd service installation, and directory setup automatically. Upgrades and rollbacks are managed through dnf or zypper.

• Kubernetes—deploy into an existing Kubernetes cluster using a Helm chart. Includes an optional bundled Keycloak for turnkey OIDC authentication. Suited for organisations that already operate Kubernetes infrastructure.

Obtaining the Software

Cirata Symphony is distributed as an installation archive. Contact your Cirata representative or visit the Cirata customer portal to obtain the archive for your platform:

• Docker Compose—cirata-symphony-<version>-docker.tar.gz
• Linux—cirata-symphony-<version>-linux-amd64.tar.gz
• RPM—cirata-symphony-<version>.x86_64.rpm
• Kubernetes—symphony-<version>.tgz (Helm chart)

The Docker Compose and Linux archives include:

• The Symphony server (container image or binary)
• The cirata CLI tool for Linux (AMD64), macOS (Apple Silicon), and Windows (AMD64)
• Configuration templates and setup scripts

The RPM package contains the Symphony server binary, systemd service unit, and configuration templates, including an nginx reverse-proxy configuration template at /etc/symphony/nginx.conf.template. CLI binaries for client platforms are available separately from the Linux archive or the Cirata customer portal.

The Kubernetes Helm chart contains the chart templates and default values; the container image must be loaded separately (see Kubernetes Installation for details).

Client libraries for Python, Java, Go, and Rust are available as separate downloads from the Cirata customer portal.

Distribute the appropriate CLI binary to users who need terminal access to Symphony. See the Command-Line Tool page for setup instructions.

System Requirements

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
Memory	4 GB	8+ GB
Disk	10 GB	50+ GB (depends on stored metadata and logs)

Extensions have their own resource requirements depending on the systems they manage. Deploy extensions on hosts with sufficient resources and network access to the data or services they operate on. See Deployment Topology for planning guidance.

Prerequisites

All installation methods require:

• A DNS name that resolves to the machine or load balancer where Symphony will run (e.g. symphony.example.com).
• An OIDC provider for user authentication (Auth0, Keycloak, Okta, or similar). You do not need to configure OIDC in advance—the setup wizard will guide you through it. Alternatively, the Docker Compose and Kubernetes methods can include a bundled Keycloak instance that requires no OIDC configuration at all.
• TLS certificates for your domain, either provided by you or generated as self-signed certificates during setup.

Outbound Network Access

Symphony's outbound network requirements depend on the dependency resolution mode an administrator selects on the Platform Settings page. Three modes are available; each has different network implications.

Proxy mode (default)

The Symphony server requires outbound HTTPS access to the jsDelivr content delivery network (cdn.jsdelivr.net, port 443).

Symphony uses jsDelivr to dynamically obtain JavaScript libraries that an extension's user interface imports. When an extension registers a UI page or widget, Symphony compiles the extension's TypeScript/JSX code in the browser. Imports of npm packages (globe.gl, chart.js, etc.) are fetched at runtime from jsDelivr via a server-side proxy (/npm/ endpoint) and cached locally in memory. The platform's own UI assets (React, Babel, MUI, htmx, Mermaid, oidc-client-ts) are vendored into the Symphony binary and served from /vendor/* — they do not require outbound HTTPS in any mode.

Cache settings (size, TTL) are tuned on the Platform Settings page. Defaults are 256 MB and 24 hours.

Mixed mode

Extensions that ship a pre-built dependency bundle resolve their imports locally; bare specifiers not in any extension's bundle fall through to the jsDelivr proxy. Outbound HTTPS to cdn.jsdelivr.net is still required, but the volume drops to whatever is not yet bundled.

This mode is the practical migration path: a fleet adopts bundles extension-by-extension while continuing to honour any extension that hasn't migrated yet.

Bundle-only mode

The jsDelivr proxy is disabled. Every extension that imports a non-platform-external library must ship a pre-built dependency bundle, or its UI will fail to load with an explicit error message naming the unbundled dependency.

In this mode Symphony requires no outbound HTTPS to fetch JavaScript libraries. The platform itself never reaches outbound for JS — only the extensions can, and only via bundles they ship to Symphony once at registration.

Bundle-only mode is the supported path for air-gapped, compliance-restricted, or supply-chain-hardened deployments. Switching modes takes effect immediately; no Symphony restart is required.

See Bundling UI Dependencies for how an extension author produces a bundle.

Why a CDN proxy at all?

Extensions are dynamic — they can be written in any language, register arbitrary UI components, and connect or disconnect at any time. Bundling every possible JavaScript dependency into the Symphony server binary would be impractical and would limit the libraries available to extension authors. By resolving npm packages from jsDelivr on demand in proxy and mixed modes, Symphony supports a wide and evolving ecosystem of frontend libraries without requiring server rebuilds or restarts. Bundle-only mode trades that flexibility for stricter network containment.

Choosing a mode

Deployment	Recommended mode
Standard production with outbound internet	Proxy (default)
Production with outbound through a corporate proxy	Proxy with proxy server's IP allowlisted for cdn.jsdelivr.net
Phased migration toward air-gap	Mixed during migration
Air-gapped, compliance-restricted, or supply-chain-hardened	Bundle-only
Demonstrating extensions in a development laptop	Proxy (default)

Ports

Symphony uses the following network ports:

Port	Protocol	Service
443	TCP	HTTPS (UI and API)
80	TCP	HTTP (redirects to HTTPS)
4222	TCP	NATS (messaging)

In proxy and mixed dependency resolution modes, Symphony also makes outbound connections to cdn.jsdelivr.net (port 443) to fetch JavaScript libraries for extension UIs. Bundle-only mode requires no outbound HTTPS for extension dependencies. See Outbound Network Access above for details.

The HTTPS and HTTP ports are served by nginx, which reverse-proxies to Symphony's internal HTTP server (port 8080) and WebSocket server (port 9222).

First-Run Setup

Regardless of installation method, when Symphony starts for the first time it presents an administration setup wizard in the browser. This wizard guides you through:

1. Configuring the OIDC identity provider
2. Setting the product name and branding
3. Defining network settings

Validating Your Configuration

The setup wizard includes a Validate Configuration button that checks your DNS hostname and OIDC settings before you submit. Each check reports pass, warning, or fail, along with a description of any issue and instructions for resolving it. Warnings do not prevent setup from completing, but should be investigated. Failures indicate configuration errors that should be corrected before proceeding.

For a detailed description of every check, what causes it to fail, and how to resolve it, see Setup Wizard Validation.

Once setup is complete, Symphony writes its configuration and restarts into normal operation. Subsequent starts skip the wizard and run directly.