Skip to navigation
Self-hosting

Upgrades and operations

Upgrade Agent Studio without dropping calls, use the studio command, and know what to back up.

Upgrades

sudo apt-get update
sudo apt-get install --only-upgrade jambonz-studio

The upgrade:

  1. runs the database migrations (they only go forward);
  2. publishes the new web app; browser tabs opened before the upgrade keep working;
  3. reloads the Studio services one process at a time, so Studio stays up;
  4. checks that every service is healthy.

Calls in progress are not dropped. The process that serves calls finishes the calls it has before it stops, which can take up to 15 minutes, and the upgrade command waits for that. Run upgrades when few calls are up.

There is no rollback. If an upgrade fails, the previous version keeps running and apt reports the package as not fully configured; fix the cause (the output says what failed) and run sudo dpkg --configure -a. Installing an older version is only safe if the newer one ran no database migration; the release notes say which releases migrate.

Studio’s ClickHouse and Qdrant versions are pinned to the ones each Studio release is tested with, and apt upgrades them together with Studio.

The studio command

Run on the server, as root or as a user with passwordless sudo (configure must run with sudo).

CommandWhat it does
studio statusversion, processes, health, data stores, disk, certificate and key settings
studio healththe health of every service and data store; exits 1 if any fail
studio versionversion, commit and database migration levels
studio envthe effective settings, without secret values
studio logs [api|gw|rag|worker]follow the logs as readable lines; --since 10m, --call <call_sid>, --session <id>, --no-follow
studio callsrecent calls, newest first (--since 1h, --limit 20)
studio call <call_sid or test session id>one call in detail: its record, timeline and log lines
studio restart [api|gw|rag|worker]reload the services (asks first; calls drain as in an upgrade)
sudo studio configure ...change a setting (see Configuration)

When something goes wrong, studio health names what is failing and studio logs or studio call <sid> usually says why. When you contact support@jambonz.org, include their output.

Where things are

PathWhat
/opt/jambonz-studiothe application
/etc/jambonz-studio/studio.envsettings and generated secrets
/etc/jambonz-studio/configure.envwhat studio configure was last given (no secrets)
/var/lib/jambonz-studioknowledge-base documents
/var/log/jambonz-studioservice logs, rotated daily or at 50 MB, 14 kept
/var/www/jambonz-studiothe web app nginx serves

The services run as the jambonz-studio user, under the jambonz-studio systemd service. Qdrant runs as qdrant.service; MariaDB, Redis, ClickHouse and nginx as their usual services.

Backups

Back up the data stores’ directories and /etc/jambonz-studio, or snapshot the data volume if you use --data-dir.

/etc/jambonz-studio/studio.env holds SECRETS_KEKS, the key that encrypts the jambonz API keys and other credentials Studio stores. A database restored without the matching studio.env cannot decrypt them. Keep it with your backups, and keep it secret.

Removing Studio

sudo apt-get remove jambonz-studio

This stops Studio (calls drain first) and removes the application. Your data, settings and keys are kept, even with apt-get purge, so a later install with studio configure picks them up again. Delete them yourself if you mean to.