---
title: Backup, restore and upgrades
description: Protect the database, conversations, working files and container credentials together.
lastVerified: 2026-09-23
---

# 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:

```sh
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:

```sh
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:

```sh
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](https://docs.teloa.ai/markdown/en/deploy/configuration.md). Copying a running PostgreSQL data directory does not replace a consistent backup.