# 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](https://hub.docker.com/r/selfdochub/selfdochub), and the compose file pins a release tag, so the running version changes only when you change it.

1. Pick the new tag on the [Docker Hub tags page](https://hub.docker.com/r/selfdochub/selfdochub/tags).
2. Set it in the `.env` file next to `docker-compose.yml`: `SELFDOCHUB_VERSION=<new tag>`. Alternatively edit the tag in `docker-compose.yml`, or download the latest compose file from the [self-doc-hub-image](https://github.com/SelfDocHub/self-doc-hub-image) repository, which pins the newest release.
3. 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](/documentation/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](/documentation/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:

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

## Next steps

- [Installation](/documentation/installation)
- [Troubleshooting](/documentation/troubleshooting)

---
Source: https://selfdochub.com/documentation/upgrading-and-backups
