Upgrading and Backups
This page explains how to upgrade SelfDocHub and how to back up its state.
Upgrading#
The image is published on Docker Hub as selfdochub/selfdochub, and the compose file pins a release tag, so the running version changes only when you change it.
- Pick the new tag on the Docker Hub tags page.
- Set it in the
.envfile next todocker-compose.yml:SELFDOCHUB_VERSION=<new tag>. Alternatively edit the tag indocker-compose.yml, or download the latest compose file from the self-doc-hub-image repository, which pins the newest release. - Pull the image and restart the container:
docker compose pull && docker compose up -d.
The docs-hub-data volume is kept, so the data stays in place. To go back, set the previous tag and run the same commands. Before downgrading, restore a backup made before the upgrade: a newer version may have changed the database schema.
The data directory is never touched by an upgrade and needs no manual migration. The SQLite database applies its schema migrations by itself on every start, before the server begins serving requests. Each migration runs in its own transaction, so a failure part way is retried in full next time.
Some upgrades also run one-time data upgrades in the background on first start, for example rebuilding the navigation index or recalculating Change Logs. They are logged and remembered once they succeed.
After an upgrade, the Rebuild action in the top menu (admin only) rebuilds merged documents and indexes of the current versions. A single version can be reparsed from the versions table (see Versions and Branches).
Note: Run exactly one instance per data directory, also during an upgrade. Two processes on one directory can corrupt it.
New translation keys are appended to your translation files automatically. See Interface Translations.
Backups#
Back up the whole data directory (the docs-hub-data Docker volume, mounted at /data in the container). It is the entire state of the application:
| Content | Location |
|---|---|
| Database: services, users, teams, environments, version metadata, tokens and more | docs-hub.db (with -wal and -shm sidecar files while running) |
| Stored specifications | specs/ |
| Merged documents and snapshots | merged/ |
| Overlays | overlays/ |
| Exports, interaction files, text page pictures | exports/, interactions/, service-pages/ |
| Configuration and translations | config.yaml, translations/ |
| License and device ID | in the data directory |
Keep your .env file (it holds session_secret) in your backup too. Without the same secret, two-factor secrets, SSO client secrets and notification secrets cannot be decrypted after a restore.
For a consistent copy of the SQLite database, stop the container (docker compose stop) for the copy or use a filesystem snapshot. For example, to archive the volume:
docker compose stop docs-hub
docker run --rm -v selfdochub_docs-hub-data:/data -v "$PWD":/backup alpine \
tar czf /backup/docs-hub-data.tgz -C /data .
docker compose start docs-hub
The volume name is prefixed with the project directory name (selfdochub if you followed the installation steps); check it with docker volume ls. The database runs in WAL mode, so copy the -wal and -shm files together with the main file.
Warning: The device ID in the data directory identifies the installation for the license. Restoring onto another machine without it changes the device ID and the license is rejected.