dokku-backup-restore

Dokku backup & restore

Version: Dokku 0.37.x. Safety: the export/list steps are read-only; config:import, storage:mount, and datastore :import overwrite live state — confirm before restoring. Exported config and DB dumps contain secrets — store them encrypted.

There is no single dokku backup command. A complete backup is composed from three parts: (1) config/env, (2) persistent storage, (3) datastore services. Capture all three.

1. Configuration / environment

# Back up
dokku config:export <app> > <app>.env          # or:
dokku config:bundle <app> > <app>-env.tar       # tarball form

# Restore
dokku config:import <app> < <app>.env           # merge
dokku config:import --replace <app> < <app>.env # replace

2. Persistent storage (bind mounts)

dokku storage:list <app>     # read-only: shows host-dir:container-dir mounts
dokku storage:report <app>

The data lives in the host directories shown by storage:list (typically under /var/lib/dokku/data/storage/<app>). Backing them up is a host-filesystem operation (outside the dokku CLI, usually needs root):

sudo tar czf <app>-storage.tgz /var/lib/dokku/data/storage/<app>   # confirm path from storage:list

Restore = place files back on the host and (re)create the mount:

dokku storage:mount <app> /var/lib/dokku/data/storage/<app>:/data   # confirm

Host-filesystem access requires root/sudo and is outside Dokku itself — coordinate with whoever owns the host (verify exact paths via storage:list first).

3. Datastore services (plugin-dependent)

Database/service data is not in the app — it lives in a Dokku service plugin (postgres, mysql, redis, …). Each official datastore plugin provides :export/:import:

# Example (MySQL service plugin):
dokku mysql:export <service> > <service>.sql      # back up
dokku mysql:import <service> < <service>.sql      # restore (overwrites — confirm)

Check which service plugins exist (dokku plugin:list) and use that plugin's own :export/:import. Command names vary per plugin — confirm with dokku <service>:help.

4. App definition (for rebuilds / migration)

The app's shape (builder, ports, domains, checks, resources) is captured by the reports in dokku-app-audit, or ideally lives in version control as a Dockerfile + app.json. Re-create the app on a new host by deploying the same source (see dokku-deploy-dockerfile) and re-importing config + storage + datastore.

Restore / migrate checklist

1. Create the app on the target host and deploy the same image/source.
2. config:import the environment.
3. Restore storage directories on the host, then storage:mount.
4. Restore each datastore via its plugin's :import.
5. Re-apply ports/domains/certs/checks/resources as needed.
6. Verify with dokku ps:report + dokku logs + a real request.