Backup and restore
There are two different backups, and it matters not to confuse them:
- Content backup — the documentation itself: every page, attachment, and the full history. This is the Git repository, and Git protects it.
- Full server backup — content plus the server state that is not in Git: user accounts, reader comments, notification subscriptions, and the licence token. This is the server’s working directory (the Docker volume).
Content backup: the repository
git clone --mirror ssh://git@github.com/your-org/docs.git
A mirror clone carries every branch, tag, and commit — the complete history, not just the
current state. Attachments are included, because they live in _attachments/ inside the
same repository.
If your remote is already hosted somewhere with its own redundancy, you may consider that sufficient. A local mirror on a schedule protects against the case that redundancy does not cover: someone deleting the remote.
To restore content: push the mirror to a new remote, point DOCUCOMMIT_SYNC_REPOS_0_URL at
it, and start the server. It clones and serves. There is no import step, because there was
no export step.
Full server backup: the working directory
The server’s working directory (the docucommit-repos volume in the standard compose file) holds
state that is not in your repository and is not recreated by a fresh clone:
| What | Where | Lost if the volume is lost? |
|---|---|---|
| Repository clone | the volume root | No — re-cloned from the remote |
| Search index | derived | No — rebuilt automatically |
| Licence token | .docucommit-license/ | No — re-issued when the server validates your key |
| User accounts | .auth/users.json | Yes |
| Comments | .comments/ | Yes |
| Notification subscriptions and outbox | sidecar JSON files | Yes |
If comments and accounts matter to you, back up the volume itself — a scheduled
docker run --rm -v tar of the volume, or whatever volume-backup mechanism your host
already uses. If you run the server purely as a rendered mirror of the repo with no
sign-ins and no comments, the repository backup alone is enough.
To restore the volume: stop the container, restore the volume contents, start it again. The server reconciles comments against the current content on startup.
Testing a restore
Worth doing once, and cheap: clone the repository into an empty directory and read a few pages in any text editor. If they are readable there, the backup is good — there is no format that could fail to load.