So, you’re running applications on Dokku, enjoying the simplicity of a self-hosted PaaS. But eventually, the time comes: you need to move your setup to a new server. Maybe it’s a hardware upgrade, a change of hosting provider, or consolidating instances. You start thinking about the process: exporting apps, dumping databases, transferring potentially large files, meticulously recreating configurations, setting up domains, handling SSL certificates… Suddenly, that “simple” PaaS feels like it involves a lot of complex, manual, and error-prone steps.

If you’ve ever felt that migration dread, you’re not alone. Manually migrating Dokku environments can be time-consuming and stressful. A single missed step or typo can lead to downtime or data loss. That’s exactly why I built the Dokku Migration Tool, an open-source CLI designed to automate and simplify this entire process.

I recently used this very tool to migrate several of my own Dokku applications and databases between servers, turning what could have been a multi-day headache into a smooth, predictable operation.

Table of Contents

1. Why Another Dokku Tool? The Pain of Manual Migration

Before automation, migrating a Dokku setup typically involves a checklist like this:

• SSH into the source server.
• Run dokku apps:list and dokku postgres:list (or other database plugins) to identify everything.
• For each app: dokku backup:export (or equivalent), download the tarball.
• For each database: Dump the database (dokku postgres:export), download the dump file.
• Note down all app configurations (dokku config:show), domain settings (dokku domains:report), scaling settings (dokku ps:scale), and volume mounts (dokku storage:list).
• SSH into the destination server.
• Install Dokku (if not already done).
• Install necessary database plugins.
• For each app: Upload the tarball, dokku apps:create, dokku backup:import.
• For each database: Create the service (dokku postgres:create), upload the dump, import the data (dokku postgres:import), link it to the app.
• Re-apply all configurations, domains, scaling, and volume mounts.
• Set up Let’s Encrypt certificates.
• Transfer persistent volume data (often involving rsync or scp).
• Test, test, test.

This process is tedious, requires careful tracking, and is highly susceptible to human error. Transferring large backups or volumes over slow connections adds another layer of complexity. The Dokku Migration Tool aims to eliminate most of this manual effort.

2. Introducing the Dokku Migration Tool: Features

This CLI tool wraps the entire migration process into simple commands, leveraging SSH for secure communication between servers. Key features include:

• 🚀 Single-Command Installation: Get up and running quickly with curl.
• 🔄 Complete Migration: Handles the entire environment or just selected apps/databases.
• 🧩 Modular Design: Run the full migration (run-all) or individual steps (export, import-db, import-apps, cleanup) as needed.
• ⚙️ Flexible Configuration: Use a config file (~/.dokku-migration-config by default) or override settings with command-line arguments.
• 🔒 Secure: Uses your existing SSH keys for secure authentication between servers. No passwords needed.
• 📊 Comprehensive: Transfers apps (Docker images), databases, environment variables, domain configurations, Let’s Encrypt email associations, persistent volumes, and process scaling.
• 🧠 Smart Defaults: Sensible defaults for ports and SSH keys, but easily overrideable.
• 💬 Informative Output: Provides progress updates and attempts to report errors clearly during the migration process.

3. How It Works Under the Hood

At its core, the tool orchestrates a series of commands over SSH on both your source and destination Dokku servers.

1. Export: Connects to the source server via SSH and runs the necessary dokku commands to export application backups and database dumps to temporary locations on the source server. It also gathers configuration data.
2. Transfer: Uses scp (leveraging your SSH keys) to securely transfer the exported files and configuration data from the source server to a temporary location on the destination server.
3. Import: Connects to the destination server via SSH. It creates the apps and database services, imports the backups/dumps, sets configurations, domains, scaling, Let’s Encrypt email, and crucially, uses rsync over SSH to transfer the contents of any persistent volumes.
4. Cleanup: Removes the temporary files created on both servers during the process.

The modular design means you can pause between steps, perform manual checks, or re-run specific parts if needed.

4. Getting Started: Installation & Basic Usage

Getting started is designed to be straightforward.

Installation:

Run this command on the machine from which you want to control the migration (this could be your local machine, or even one of the servers):

curl -fsSL https://raw.githubusercontent.com/pedropaf/dokku-migration/main/install.sh | bash

This installs the tool to ~/.dokku-migration and creates a handy symlink at /usr/local/bin/dokku-migration for easy access. It also creates a default configuration file at ~/.dokku-migration-config.

Basic Usage:

1. Edit the configuration file:

   nano ~/.dokku-migration-config

   You’ll need to fill in at least SOURCE_SERVER_IP, DEST_SERVER_IP, and the APPS and DBS arrays you want to migrate. Make sure your SSH keys allow access from the machine running the tool to both the source and destination servers as the dokku user (or root, if needed). (Ensure the SSH key you specify via SOURCE_SERVER_KEY/DEST_SERVER_KEY or the default ~/.ssh/id_rsa on the machine running the script has been added to the authorized keys on the respective servers for the appropriate user.)

   # Example ~/.dokku-migration-config
   SOURCE_SERVER_IP="1.2.3.4"
   DEST_SERVER_IP="5.6.7.8"
   # Optional: Specify if ports/keys differ from default
   # SOURCE_SERVER_PORT="22"
   # DEST_SERVER_PORT="2222"
   # SOURCE_SERVER_KEY="~/.ssh/id_rsa_source"
   # DEST_SERVER_KEY="~/.ssh/id_rsa_dest"
   
   APPS=("my-cool-app" "another-app")
   DBS=("my-postgres-db" "my-redis-cache") # Assumes you have plugins for these!
   LETSENCRYPT_EMAIL="[email protected]" # Important for SSL

2. Run the migration:

   dokku-migration run-all

The tool will then connect to your servers and perform the export, transfer, import, and cleanup steps, showing progress along the way.

5. What Exactly Gets Migrated?

The goal is comprehensive migration. Here’s a checklist of what the tool handles:

• ✅ Application Docker images (via dokku backup)
• ✅ Environment variables (dokku config)
• ✅ Domain configurations (dokku domains)
• ✅ Let’s Encrypt email association (used for certificate renewal)
• ✅ Database content (via plugin export/import commands, e.g., dokku postgres:export)
• ✅ Persistent storage volumes (using rsync for efficient transfer)
• ✅ Process scaling configuration (dokku ps:scale)

Requirements:

• SSH access (key-based recommended) to both servers from the machine running the tool.
• Dokku installed on both servers.
• Matching Dokku database plugins (e.g., dokku-postgres, dokku-redis) must be installed on both servers for the databases being migrated. The tool relies on these plugins’ export and import commands.

6. Advanced Usage & Flexibility

While the configuration file is convenient, you can also control everything via command-line arguments, which override the config file settings.

Migrate Specific Apps/DBs without Editing Config:

dokku-migration \
  --source 192.168.1.10 \
  --dest 192.168.1.20 \
  --apps "app1 app2" \
  --dbs "db1" \
  run-all

Migrate Between Servers with Non-Standard Ports/Keys:

dokku-migration \
  --source old-server.example.com \
  --dest new-server.example.com \
  --source-port 2222 \
  --dest-port 22 \
  --source-key ~/.ssh/old_server_key \
  --dest-key ~/.ssh/new_server_key \
  --apps "my-legacy-app" \
  --dbs "legacy-db" \
  --email "[email protected]" \
  run-all

Run Only Specific Steps:

Need to just get the data off the old server for now?

dokku-migration --source 1.2.3.4 --apps "app1" --dbs "db1" export

Later, you can manually transfer the files (if needed) and run the import steps on the destination:

# Ensure exported files are manually placed in the expected temp dir on destination
# (~/dokku_migration_temp/export by default) before running import commands.
dokku-migration --dest 5.6.7.8 --apps "app1" --dbs "db1" import-db
dokku-migration --dest 5.6.7.8 --apps "app1" import-apps
dokku-migration --dest 5.6.7.8 cleanup # Optional cleanup

7. A Note on Persistent Logs and Volumes

In my previous post on Deploying Nextjs on Your Own VPS using Dokku, I touched upon various operational aspects, including managing Dokku. One common challenge is ensuring logs persist across container restarts or deployments. A good practice is to mount a persistent volume for your application’s logs, alongside any other persistent data like user uploads.

The Dokku Migration Tool directly supports this best practice. When it migrates persistent storage (identified via dokku storage:list), it uses rsync to copy the contents of those volumes from the source to the destination server. So, if you’ve configured your applications to write logs or store uploads in Dokku-managed volumes, this data will be migrated along with everything else, ensuring continuity. This is crucial for maintaining historical log data or user files during a server transition.

8. Contributing & Future

This tool is open-source under the MIT license, and contributions are highly welcome! Whether it’s bug reports, feature requests, documentation improvements, or code contributions, please feel free to get involved.

• GitHub Repository: https://github.com/pedropaf/dokku-migration
• How to Contribute: Fork the repo, create a feature branch, make your changes, and open a Pull Request.

I have ideas for potential future enhancements, such as more granular controls, pre-migration checks (like verifying plugin existence), or support for more complex scenarios, but community input will be invaluable in shaping its direction.

9. Conclusion

Migrating Dokku servers doesn’t have to be a complex, high-stakes manual process anymore. The Dokku Migration Tool provides a reliable, automated, and secure way to move your Dokku applications and databases. By handling the tedious details of exporting, transferring, and importing data, configurations, and volumes, it frees you up to focus on the bigger picture.

Give it a try for your next Dokku migration! I hope it saves you as much time and stress as it has saved me. Find the project on GitHub: https://github.com/pedropaf/dokku-migration