5.2 Backup, restore and upgrades

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

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 -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 credentials and working data; keep them in encrypted storage with restricted access.

2. Restore into a separate instance

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 instance may contain enabled automations and model credentials. 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 instance with its new authentication link. Check the identities and contents of colleagues, groups, tasks, knowledge and at least one working file. A working home page alone does not prove that recovery succeeded. Stop the restored instance when verification is complete.

Upgrade and rollback

Record the source version, image digest and project name. Test the target version in a separate instance. Before upgrading your working installation, complete a backup, then run docker compose up -d --build from its original directory.

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.