Skip to the content
Get started

Documentation

Back up and restore

What to back up on a self-hosted Docustay, a script that does it, and how to restore it on a new machine.

A self-hosted Docustay keeps its state in three places. Back up all three, together, or the backup may not restore.

What Where Why it matters
The database the db container (volume dbdata) People, templates, documents, settings, the audit trail.
The file store the storage container (volume filedata) Uploaded files and signed PDFs.
The app data volume and .env volume appdata and the file docustay/.env The certificate that seals signed PDFs, the key that protects stored passwords, and the secrets behind sign-in. Without them a restored copy cannot open what it stored.

Back up

Run this from the docustay folder. It writes one dated folder.

set -eu
d="backup-$(date +%Y%m%d-%H%M)"; mkdir -p "$d"
# 1. the database, as one consistent file
docker compose exec -T db pg_dump -U docustay -Fc docustay > "$d/db.dump"
# 2. the file store and the app data volume, as archives
for v in filedata appdata; do
  docker run --rm -v "docustay_$v:/v:ro" -v "$PWD/$d:/out" alpine tar czf "/out/$v.tgz" -C /v .
done
# 3. the settings file
cp .env "$d/env"; chmod 600 "$d/env"
echo "backed up to $d"

Copy the folder somewhere that is not this machine. The folder holds secrets, so keep it as private as the install itself.

Restore on a new machine

  1. Install Docker and get the Docustay folder (git clone, then cd docustay).
  2. Put the saved settings file back: cp backup-…/env .env
  3. Start only the database and the file store, so nothing writes yet:
docker compose up -d db storage
  1. Load the database:
docker compose exec -T db pg_restore -U docustay -d docustay --clean --if-exists < backup-…/db.dump
  1. Load the two volumes:
for v in filedata appdata; do
  docker run --rm -v "docustay_$v:/v" -v "$PWD/backup-…:/in:ro" alpine sh -c "cd /v && tar xzf /in/$v.tgz"
done
  1. Start everything and check it: docker compose up -d, then run docker compose ps and open the app. Every service should be Up, and app should say (healthy).

Test the restore

A backup you have not restored is a guess. Once, on a spare machine, do the restore above and open a signed document. Do it again after a major upgrade.

How often

Daily is a good start for the database. The file store changes only when documents are made or signed, so the same schedule is enough. Keep at least the last seven.

CtrlI