In short
A complete backup is two things: the data directory and the secret key. Without the second, the first brings back an instance whose database passwords and git tokens are unreadable. If you use PostgreSQL, its database joins the list.
What to back up
The data directory
Everything your users create: the application database, the files, the project folders, the git working copies. The Docker images hold no data.
The secret key
It does not live in the data directory: it is passed as an environment variable. It must therefore be backed up separately, in your secret store.
The PostgreSQL database, if you use one
When the application database is external it is no longer in the data directory: back it up with your usual tools, consistently with the folder.
A backup without the secret key is an incomplete backup
The instance will come back and your users will sign in — their account passwords do not depend on that key. But every database password, every git token and every API key will be unreadable, with no visible error, and will have to be re-entered by hand. See Configuration.
What you may exclude
The cache sub-folder — the shared R and Python packages — is rebuildable. Excluding it shrinks the backup considerably; at worst the first environment build after a restore takes longer. Uploads in flight can be skipped too.
Backing up cleanly
The difficulty is not copying, it is copying a consistent state: a copy taken while a write is in progress can contain a half-written database.
Stop the instance, or take a snapshot
The safest route is stopping the containers for the duration of the copy. Failing that, a filesystem or volume snapshot gives a consistent point with no downtime.
Copy the folder
With your usual tools, preserving permissions. This is where choosing a mounted folder over a named Docker volume pays off: the folder backs up like any other.
Record the version
Keep the version number of the images alongside the backup. A backup does not restore onto an older version — see below.
docker compose -f docker-compose.hub.yml down
tar czf linkr-$(date +%F).tar.gz -C /srv linkr
docker compose -f docker-compose.hub.yml up -dRestoring
Put the folder back, supply the same secret key, and start with a version at least equal to the one the backup came from. Any needed migrations apply by themselves on start.
You do not restore onto an older version
The database schema moves forward with upgrades, and those migrations do not replay backwards. A backup taken on a recent version will not come back on an earlier one: that is why the version must be recorded at backup time.
Test a restore at least once
A backup that has never been restored is a hypothesis, not a guarantee. Bring one back on a test machine: sign in, open a project, display a dashboard, and above all connect to a database — that last step is what reveals a missing secret key.
Backing up differently: git
The data directory protects the instance. Git versioning protects the work, and the two complement each other.
An entity linked to a remote repository has, by construction, a copy outside your server: cohort definitions, scripts, dashboards. If the instance disappears, that work is recovered by cloning the repositories, even with no backup at hand.
But git does not back up data
Data files are excluded from versioning unless explicitly marked. A git repository is therefore not a backup of your datasets — see Git versioning.
Accounts, separately
The Settings › Backup & sync tab exports and re-imports organizations, users and roles, as an archive or to a git repository. It is useful for carrying a configuration from one instance to another, or for keeping track of how roles evolve.
Passwords are never exported
An imported user with no password lands disabled and must be given one before they can sign in. This export is therefore not a substitute for a backup: it carries a configuration, not accounts usable as they stand.
What the backup does not cover
- External databases. A PostgreSQL or Oracle database queried by Linkr stays the responsibility of whoever operates it: Linkr only holds its address.
- Files pointed at by path. A warehouse placed on the server and pointed at without copying is not in the data directory — it belongs to the server’s own backup. See Files on the server.
- A browser-mode installation. The data lives in each person’s browser, out of an administrator’s reach. Only manually exporting a project puts it somewhere safe.
Going further
- Configuration — the data directory, folder by folder.
- Production install — the volume to mount, and upgrading.
- Git versioning — the other safety net.
- Import and export — taking an entity out of an instance.