Skip to main content

Upgrades

This guide covers how to upgrade Cirata Symphony to a new version, including pre-upgrade checks, deployment-specific procedures, and post-upgrade verification.

info

The commands below vary by deployment method. Ensure the required tools are installed for your environment.

Pre-Upgrade Checklist​

Before upgrading:

  1. Back up the configuration directory—See Operations—Backup
  2. Review the release notes for breaking changes or migration steps
  3. Notify users of planned downtime (upgrades require a restart)
  4. Verify current health—Confirm the instance is running and all extensions are connected
# Verify current version
cirata info

# Check extensions are connected
cirata extension list

# Back up configuration (see Backup and Recovery for all supported approaches)
cirata symphony backup --output ./symphony-backup-$(date +%Y%m%d).tar

Upgrade Procedures​

Docker Compose​

Cirata Symphony is distributed as a tarball containing container images and configuration files.

# Extract the new release alongside the current installation
tar xvf cirata-symphony-<new-version>.tar.gz

# Load the bundled Symphony image
docker load -i cirata-symphony-<new-version>/images/cirata.tar

# Stop the current instance
cd /path/to/current/symphony
docker compose down

# Pull updated public images (NGINX, Keycloak, etc.)
docker compose pull

# Compare configuration for any changes introduced in the new release
diff docker-compose.yml /path/to/cirata-symphony-<new-version>/docker-compose.yml

# Apply any required configuration changes, then start
docker compose up -d

# Verify
curl http://localhost:8080/api/v1/ping
tip

Review the output of the diff command carefully. New releases may add services, change environment variables, or update image tags. Merge any relevant changes into your existing docker-compose.yml before starting.

Linux (systemd)​

# Download the new release package
# (Replace with actual download URL from release notes)

# Stop the service
sudo systemctl stop symphony

# Install the new binary
sudo cp cirata /usr/local/bin/cirata
sudo chmod +x /usr/local/bin/cirata

# Start the service
sudo systemctl start symphony

# Verify
sudo systemctl status symphony
curl http://localhost:8080/api/v1/ping

RPM​

# Upgrade the package (automatically restarts the service)
sudo dnf upgrade cirata-symphony-<new-version>.x86_64.rpm

# Verify
sudo systemctl status symphony
curl http://localhost:8080/api/v1/ping

Kubernetes​

# Update the image tag in your deployment manifest or Helm values
# Then apply the update:
kubectl set image deployment/symphony symphony=cirata/symphony:<new-version>

# Or with Helm:
helm upgrade symphony symphony-<new-version>.tgz

# Monitor the rollout
kubectl rollout status deployment/symphony

# Verify
kubectl exec -it deployment/symphony -- curl http://localhost:8080/api/v1/ping

Post-Upgrade Verification​

After upgrading, verify the instance using the cirata CLI or curl:

  1. Check health and version:

    cirata info

  2. Check that extensions reconnect:

    cirata extension list

    Extensions reconnect automatically when Symphony restarts. Allow 30–60 seconds for all extensions to re-register.

  3. Test API key authentication:

    cirata account

  4. Review logs for errors:

    # Linux
    sudo journalctl -u symphony --since "10 min ago"

    # Docker
    docker compose logs symphony --tail 50

    # Kubernetes
    kubectl logs deployment/symphony --tail 50

Rollback​

If the upgrade causes issues:

Docker Compose​

# Stop the current instance
docker compose down

# Reload the previous Symphony image from the earlier release tarball
docker load -i cirata-symphony-<previous-version>/images/cirata.tar

# Revert any configuration changes made during the upgrade
docker compose up -d

Linux​

sudo systemctl stop symphony
sudo cp /path/to/backup/cirata /usr/local/bin/cirata
sudo systemctl start symphony

RPM​

sudo dnf downgrade cirata-symphony-<previous-version>.x86_64.rpm

Kubernetes​

# Undo the last rollout
kubectl rollout undo deployment/symphony

Data Migration​

Symphony automatically handles data migration on startup when upgrading to a version that introduces new storage structures:

  • New JetStream buckets (e.g., symphony_roles, symphony_role_assignments) are created automatically
  • Existing user accounts are migrated to import new buckets
  • Existing data is preserved—no manual migration is needed
  • The process is backward compatible

See Also​

  • Operations—Backup, health checks, and troubleshooting
  • Configuration—Configuration files and directory structure