Skip to main content

Tutorial: Deploy and Configure Cirata Symphony

In this tutorial you will install Cirata Symphony using Docker Compose, complete the setup wizard, sign in, create an API key, and explore the user interface. By the end, you will have a running Symphony instance ready for extension development.

Prerequisites​

Step 1: Extract and Load​

Download the Symphony Docker archive and extract it:

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

Step 2: Configure Your Environment​

For this tutorial we use the bundled Keycloak option, which provides a fully-configured OIDC provider with no external services required.

cp env.keycloak.example .env

Edit .env and set the following values:

VariableDescriptionExample
EXTERNAL_HOSTNAMEDNS name or IP for this machinesymphony.example.com
KEYCLOAK_ADMIN_PASSWORDPassword 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.

Step 3: Start Symphony​

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

This starts four containers:

ContainerPurpose
symphony-certgenGenerates a self-signed TLS certificate (runs once, then exits)
symphonySymphony application server
symphony-nginxnginx reverse proxy (TLS, WebSocket, NATS passthrough)
symphony-keycloakKeycloak OIDC provider

Wait for the services to be healthy (this may take 30–60 seconds on first startup).

Step 4: Complete the Setup Wizard​

Open your browser and navigate to https://<EXTERNAL_HOSTNAME>. Your browser will show a certificate warning because the auto-generated certificate is self-signed—accept the warning to continue.

On first startup, Symphony presents a 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.

tip

If the container for the Nginx proxy that is created with the Docker Compose environment is accessed via a different hostname, be sure to use that hostname as the external address for Symphony in the setup wizard.

Step 5: Create a User in Keycloak​

The bundled Keycloak realm does not include any pre-configured user accounts—self-registration is also disabled—so you must create at least one user before you can sign in to Symphony.

  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 a username and email address, then click Create
  6. Go to the Credentials tab, click Set password, enter a password, and toggle Temporary off so you are not forced to change it on first login
  7. Click Save

Step 6: Sign In​

Navigate to https://<EXTERNAL_HOSTNAME>. You will see a login page in which you can enter the credentials you just created in Keycloak to sign in.

Once authenticated, you will see the Symphony dashboard.

Step 7: Explore the User Interface​

The Symphony UI has several areas:

  • Dashboard—Customizable widget view (the default landing page)
  • Extensions—Shows installed extensions and their pages
  • Account—Manage your API keys and view your roles
  • Administration—Role and assignment management (if you have admin access)
  • Help—Documentation (you're reading it now)

Take a moment to navigate through each section to familiarize yourself with the interface.

Step 8: Create an API Key​

API keys are required for running extensions, using client libraries, and calling the REST API programmatically.

  1. Navigate to Account → API Keys
  2. Click Create API Key
  3. Name it "Tutorial Key"
  4. For this tutorial, grant full access by allowing cirata.> for both publish and subscribe
  5. Click Create
  6. Copy the token immediately—it will not be shown again

Test your API key using the cirata CLI:

# Login to your instance
cirata login --address <EXTERNAL_HOSTNAME>

# Verify your account
cirata account

# Get instance information
cirata info

# List extensions
cirata extension list

You can also test with curl if you prefer:

export SYMPHONY_TOKEN="<your-token>"
curl -H "Authorization: Bearer $SYMPHONY_TOKEN" https://<EXTERNAL_HOSTNAME>/api/v1/apikey

Step 9: Install a Sample Extension​

Install a sample extension to see how extensions integrate with Symphony. Using the Python library:

pip install cirata_symphony-*.whl

# Set the token
export SYMPHONY_TOKEN="<your-token>"

Create a file called hello.py:

import asyncio
from cirata import symphony

async def main():
    async with symphony.Extension("Hello World", "hello") as ext:
        if ext.token:
            ext.add_resource("ui://hello", "text/symphony-jsx", """
                export default function Hello() {
                    return <h1>Hello from my first extension!</h1>
                }
            """)
            ext.add_route("/hello", "ui://hello")
            ext.add_menu("Extensions", "Hello World", "/hello", "fa-hand-wave")
        await ext.operate()

asyncio.run(main())

Run it:

python hello.py

Switch back to your browser and refresh Symphony. You should see "Hello World" in the navigation menu. Click it to see your extension's page.

Next Steps​