5.2 Backup, restore and upgrades

A complete backup includes PostgreSQL, DSH conversations and configuration, working files, and the database password, but no keys or connection authorizations. These commands apply to a Compose installation. Run them from the original installation directory and use a new backup directory.

npm installations

Install the 0.2.2 command package into a new command directory and use its teloa. Keep the original --home for a custom installation, finish active work, then stop and back up to a new directory before upgrading:

teloa stop
teloa backup --output "/absolute/path/new-backup"
teloa upgrade --to 0.2.2
teloa status

When --to matches the command package's version it becomes the candidate; other versions come from the npm registry. See the installation guide. The upgrade also creates a backup, checks the candidate before switching, and starts the service when it succeeds, so you do not need to run up. If the upgrade fails, the installation stays in maintenance and up and restart refuse to run; the automatic backup is under <home>.backups/before-<version>-…, and its path is recorded in instances/default/upgrade.json. npm backups include the database, sessions and configuration, but exclude model credentials and workspace files. Protect the unencrypted backup, separately preserve your workspace, and verify both before resuming. Restore into a new home with teloa restore --from "/absolute/path/new-backup" --home "/absolute/path/new-home"; then configure credentials again. Restore with a command package of exactly the same version as the backup (the automatic pre-upgrade backup belongs to the old version, so use the old command package), and put the original workspace back at its original path first. Updating the npm command package alone does not upgrade the running application. The following shell commands apply to Compose installations.

1. Stop writes and back up

Finish or stop running work first. The following commands use a macOS or Linux shell:

umask 077
mkdir backup
docker compose stop app
docker compose exec -T db pg_dump -U teloa -d teloa -Fc > backup/database.dump
docker compose run -T --rm --no-deps --entrypoint tar app -C /data --anchored --exclude=dsh/.env --exclude='dsh/.credentials.*' --exclude=teloa/mcp/credentials -czf - dsh teloa > backup/app.tar.gz
docker compose run -T --rm --no-deps --entrypoint cat app /run/teloa-secrets/postgres-password > backup/postgres-password
docker compose start app

Every export command must finish successfully. A file can exist even if an export failed and left it empty. Backups contain the database password and working data; keep them in encrypted storage with restricted access.

As with teloa backup, keys and authorizations are left out of the archive: the .env file in the DSH folder (it may hold plain-text keys), .credentials.* (encrypted keys and authorization tokens, their metadata and quarantined plain-text copies) and the old managed MCP key folder teloa/mcp/credentials. The key storage master key lives in the separate credentials-secret volume and is not backed up either. After a restore, enter model keys, connection grants and IM channel keys again in Settings; save any settings you need from .env yourself somewhere protected.

2. Restore into a separate copy

Use the same source version and image. Check that the new project name teloa-restore and port 3107 are unused. Do not use these steps to overwrite an existing working database.

A restored copy may contain enabled automations. Before starting the app, prevent it from repeating real business actions. Validate it in a controlled network or with its plans disabled.

Restore the password first, then start the empty database:

docker compose -p teloa-restore run -T --rm --no-deps --entrypoint sh init -c 'cat > /data/secrets/postgres-password && chmod 440 /data/secrets/postgres-password' < backup/postgres-password
docker compose -p teloa-restore up -d db
docker compose -p teloa-restore ps

Wait for the database to become healthy, then restore its data and the working files:

docker compose -p teloa-restore exec -T db pg_restore --exit-on-error --no-owner -U teloa -d teloa < backup/database.dump
docker compose -p teloa-restore run -T --rm --no-deps --entrypoint tar app -C /data -xzf - < backup/app.tar.gz
TELOA_PORT=3107 docker compose -p teloa-restore up -d --no-build

Open the restored copy with its new authentication link. Check the identities and contents of employees, groups, tasks, knowledge and at least one working file. A working home page alone does not prove that recovery succeeded. Stop the restored copy when verification is complete.

Upgrade and rollback

Record the application version, image digest and project name. Test the target version in a separate copy and complete a backup. For Hub installs, change both app and init images in Compose to the same exact version, then run docker compose pull and docker compose up -d --no-build. Source builds use docker compose up -d --build.

An older image may not be able to read newer database or conversation formats. A rollback requires the old version together with a complete backup from before the upgrade; changing an image tag alone is insufficient.

For source development paths, see Configuration and data locations. Copying a running PostgreSQL data directory does not replace a consistent backup.

What to keep and check before upgrading

0.2.2 uses DSH 0.2.1-rc.2. Keep the previous version and complete backup, then check the target version with a separate database, configuration directory, working directory and port before upgrading.

• Use the DSH versions locked by the release package. Do not update individual official packages independently or use floating tags. Preserve platform optional dependencies required by voice, browser or computer providers.
• Back up DSH configuration, sessions and attachments, extension activation choices, pending Market installation records and working files. Optional-package preparation preserves existing activation choices; Browser and Computer remain off by default.
• In the separate copy, check historical session reading and continuation, employee and business identity, original attachment contents, a file preview and a task stop. Older child sessions retain official recovery paths; they are not converted into invented Team records.
• Finish or stop active work before restarting. Local background processes and in-memory change reviews cannot be restored merely by copying session records. Check interrupted work afterwards and avoid automatically replaying external actions that may already have happened.
• Switch the working installation separately, after candidate acceptance and rollback preparation. If conversation or database formats changed, roll back with the pre-upgrade copy; do not let the old version rewrite new data directly.

See Native execution capabilities for candidate entry points and limits. An enabled extension does not establish that browser, desktop, voice or SSH execution has been verified.