Helpin
Dark mode
Back up and restore

Back up and restore

A Helpin backup is only useful if it includes both your data and the encryption keys that unlock it. The CLI captures both in one consistent snapshot and restores them into a fresh installation, without touching the original.

Before you rely on it: test a restore on a separate directory or host. A backup you've never restored is a hope, not a plan.

What a backup contains

Included

Details

Databases

PostgreSQL volume with all four databases (Helpin, Runtime, Temporal, visibility)

Files

Garage metadata and objects: attachments, images, and uploads

Queues and caches

NATS and Redis volumes

Agent workspaces

The execution_workspaces volume

Configuration

The installed bundle, .env (including encryption keys), apps.json, and your Caddy file

Image references

The exact image digests, so a restore runs the same software

Container images themselves aren't copied. The restore host must be able to pull the same images.

Create a backup

helpin backup --dir /srv/helpin --backup /srv/backups/helpin-2026-09-23

  1. The CLI asks before stopping services. Add --yes for scheduled or unattended runs.

  2. It stops services gracefully (180-second grace period) and refuses to continue if anything is still writing.

  3. It snapshots every named volume and your configuration into the backup directory.

  4. It restarts the services that were running before, and waits for them to become healthy.

If you omit --backup, a timestamped directory is created next to your installation.

The result is a directory containing backup.json (a manifest with checksums), installation.tar.gz, and one archive per volume. A directory without backup.json is incomplete. Don't use it.

Warning: Backups contain unencrypted customer data and your encryption keys. The directory is private to your user (mode 700, files 600). Copy it to encrypted, off-host storage. The CLI doesn't schedule, encrypt, or prune backups for you.

Schedule nightly backups

Backups briefly stop Helpin, so run them in a quiet window. A cron example:

# /etc/cron.d/helpin-backup, 03:15 every night
15 3 * * * helpin /home/helpin/.local/bin/helpin backup --dir /srv/helpin --backup /srv/backups/helpin-$(date +\%F) --yes

Then sync /srv/backups to your encrypted off-site storage and apply your own retention policy.

Restore into a new installation

Restore always creates a new installation with new volumes. It never overwrites the original.

helpin restore --backup /srv/backups/helpin-2026-09-23 --dir /srv/helpin-restored --no-start
helpin configure --dir /srv/helpin-restored   # adjust ports or domains if needed
helpin start --dir /srv/helpin-restored
helpin doctor --dir /srv/helpin-restored

Restore verifies every archive before it creates anything. It brings back the original release, settings, and encryption keys, and gives the new installation its own Compose project name.

  • Same host: stop the original first, or choose different ports with configure.

  • New host: copy the whole backup directory across, then point DNS and your HTTPS proxy at the new server.

Verify before switching traffic

  • Open a support conversation and check its messages and attachments.

  • Open a help center article with images.

  • Start an agent run using an existing AI connection. This confirms your encryption keys were restored.

Keep the backup until you've verified the restore.

Move Helpin to a new server

  1. helpin backup on the old server.

  2. Copy the backup directory to the new server over an encrypted channel.

  3. Install the helpin CLI on the new server, then run helpin restore and helpin start.

  4. Update DNS and install your reverse-proxy configuration.

  5. Run helpin doctor, then verify as above before you decommission the old server.

Supported layouts

Backup and restore support the bundled local Docker volumes. Restoring requires the same CPU architecture (amd64 or arm64). External volumes, custom volume drivers, bind mounts outside the installation, and external databases need your own storage-specific procedures.

Manual database dumps

If you run your own backup system, stop application writers first and dump each database:

cd /srv/helpin/community
umask 077 && mkdir -p /srv/manual-backup
docker compose stop helpin-frontend helpin-helpcenter helpin-worker agent-runtime-worker agent-runtime helpin-api
for db in helpin agent_runtime temporal temporal_visibility; do
  docker compose exec -T postgres pg_dump -U postgres -Fc "$db" > "/srv/manual-backup/$db.dump"
done
cp .env apps.json /srv/manual-backup/

Also snapshot object storage (garage_data) while stopped, then start again with helpin start. Manual dumps can't be used with helpin restore.

Was this article helpful?