Skip to content

Backup and Restore

Apps, services, and their data are backed up through Dokku's existing mechanisms - the app git repositories, each datastore plugin's export/import commands, and filesystem backups of Dokku's data root. See the Dokku documentation for those. This guide covers only the additional state that Dokku Pro layers on top.

That extra state lives in three places. The Dokku Pro database (/var/lib/dokku/data/pro/db) and the plugin property namespaces (/var/lib/dokku/config/webhook, .../teams, .../users) both sit inside Dokku's data root at /var/lib/dokku, so a full filesystem backup of that tree already captures them. The server configuration at /etc/default/dokku-pro lives outside that tree and is the piece most easily missed. The sections below describe each so that operators taking selective or plugin-level backups do not lose Dokku Pro state, and so that a restore brings the server up cleanly.

What to back up

Dokku Pro database

Dokku Pro stores its own state in a database directory at the path configured by DATABASE_LOCATION (default /var/lib/dokku/data/pro/db, described in Configuration). This directory holds the background job queue, the command and activity logs, and the issued authentication tokens.

The database is a live on-disk store that Dokku Pro compacts in the background while the service runs, so back up the whole directory with the service stopped to get a consistent snapshot.

Note

Stop the service with systemctl stop dokku-pro.service before copying the database directory. See General Operating Instructions for the service commands.

Server configuration

Configuration lives in /etc/default/dokku-pro (described in Configuration). Preserve this file as-is; it holds the values the server needs to start and authenticate:

  • ROOT_TOKEN and ROOT_USERNAME - the credentials used to log in.
  • API_JWT_ACCESSSECRET and API_JWT_REFRESHSECRET - the secrets used to sign authentication tokens.
  • LICENSE_KEY or LICENSE_KEY_FILE - the license the server validates on start. When LICENSE_KEY_FILE is used, back up the file it points at (for example /etc/dokku-pro/license.key) as well.
  • The SERVER_* settings and PORT - the server's network and behaviour configuration.

Warning

Keep API_JWT_ACCESSSECRET and API_JWT_REFRESHSECRET identical across a restore. Changing either secret invalidates every previously issued token, forcing all users to sign in again. ROOT_TOKEN and the license value must also match for the server to start and authenticate.

Per-app and account settings

Some Dokku Pro settings are stored through Dokku's plugin property store rather than in the Dokku Pro database, under /var/lib/dokku/config/<namespace>/. These are not part of an app's own git or build state, so back them up alongside the rest:

  • webhook (per app) - the GitHub webhook configuration for each app, at /var/lib/dokku/config/webhook/<app>/. The keys are enabled, secret, repository, git-ref, and build-mode. The secret file holds the GitHub signing secret, which cannot be recovered from GitHub if lost.
  • teams (global) - team definitions, at /var/lib/dokku/config/teams/--global/<team>-team.json.
  • users (global) - user accounts, at /var/lib/dokku/config/users/--global/<username>-user.json.

Creating a backup

The following example stops the service, copies the three pieces of state into a backup directory, and starts the service again. Adjust the database path if you have changed DATABASE_LOCATION.

# stop the service so the database is snapshotted consistently
systemctl stop dokku-pro.service

# create a directory to hold the backup
mkdir -p /var/backups/dokku-pro

# the database: background jobs, command logs, and auth tokens
tar -czf /var/backups/dokku-pro/db.tar.gz -C /var/lib/dokku/data/pro db

# the server configuration, plus the license file if LICENSE_KEY_FILE is used
cp /etc/default/dokku-pro /var/backups/dokku-pro/dokku-pro.env
cp /etc/dokku-pro/license.key /var/backups/dokku-pro/license.key

# the plugin property namespaces: webhooks, teams, and users
tar -czf /var/backups/dokku-pro/config.tar.gz -C /var/lib/dokku/config webhook teams users

# start the service again
systemctl start dokku-pro.service

Restoring onto a fresh install

Restore in the following order so the server comes up cleanly:

  1. Install Dokku and restore the base Dokku backup - apps, services, their data, and /var/lib/dokku/config.
  2. Install Dokku Pro at the same version, following the Installation guide. This recreates the plugin triggers the property store relies on.
  3. Restore /etc/default/dokku-pro, keeping the JWT secrets, ROOT_TOKEN, and license identical to the backup. Restore the LICENSE_KEY_FILE target too if you use file-based licensing.
  4. With the service stopped, ensure the DATABASE_LOCATION parent directory exists, then restore the database directory into place.
  5. Restore the webhook, teams, and users property namespaces if they were not already covered by the base Dokku restore.
  6. Start the service and confirm you can sign in with ROOT_TOKEN.
# with Dokku and Dokku Pro installed, stop the service before restoring
systemctl stop dokku-pro.service

# restore the server configuration and license file
cp /var/backups/dokku-pro/dokku-pro.env /etc/default/dokku-pro
cp /var/backups/dokku-pro/license.key /etc/dokku-pro/license.key

# ensure the database parent directory exists, then restore the database
mkdir -p /var/lib/dokku/data/pro
tar -xzf /var/backups/dokku-pro/db.tar.gz -C /var/lib/dokku/data/pro

# restore the plugin property namespaces
tar -xzf /var/backups/dokku-pro/config.tar.gz -C /var/lib/dokku/config

# start the service
systemctl start dokku-pro.service

Note

Existing sessions survive a restore only when the JWT secrets are unchanged. Otherwise the tokens in the restored database are rejected and users simply sign in again.