Repository / docs/wiki/Backup-and-Recovery.md
Backup, updates and recovery
04 · RUN AND PROTECT · All guides · Get help
On this page
An evidence export is for handing over. A backup you can restore from also needs the logins, keys and config.
What to preserve#
| Installation | Data to preserve |
|---|---|
| Source / portable | The whole data/live directory |
| Custom data directory | That whole directory |
| Docker | The whole /data volume, same Compose project |
| External vault key | The original key file, kept separately |
| Witness | Its own data directory, keys, config and secret files |
That means everything: all profiles/, media, databases, checkpoints, hidden files, vault
key and metadata, plus .env, custom config and certificate volumes. Treat the backup like
the account password, because it is one.
Make a consistent backup#
- Pause observation and stop the process properly.
- Copy the whole data directory somewhere private, outside the repo.
- Copy the external vault key separately if you use one.
- Note the version and time.
- Start it again and check observation and coverage.
Default Docker setup:
docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update
Use a fresh destination every time. With overlays or deploy/compose/compose.image.yaml, pass the same files.
Restore deliberately#
- Leave the original backup alone.
- Restore into a separate directory with the app stopped.
- Bring the original external key if you had one, a new key won't open old secrets.
- Start one instance on the restored directory.
- Check workspace and account, verify the journal, look at media and gaps, then resume.
Never run the original and the restored copy at the same time with the same Telegram session.
Update the application#
Native install: stop, back up, replace the source, run python start.py --setup-only, start.
Don't carry a venv across OSes or Python versions.
Docker from source, after backing up and pulling the new code:
docker compose up -d --build --wait
Same project name and volume. Afterwards check the panel, the account and that new events come in. Whatever happened during downtime isn't fully recoverable.
Retention and deletion#
Nothing gets deleted automatically. Editing signed records breaks verification. Removing a workspace doesn't remove exports, off-site copies or witness records you keep elsewhere.
Deletion incomplete? Close whatever holds the files and retry from Accounts. The workspace stays stopped until then.
Next: Operations reference · Deployment and updates · Troubleshooting