# Back up and restore

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.

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

```bash
docker compose up -d db storage
```

4. Load the database:

```bash
docker compose exec -T db pg_restore -U docustay -d docustay --clean --if-exists < backup-…/db.dump
```

5. Load the two volumes:

```bash
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
```

6. 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.