Moving a Docker Compose-based application to a new VPS — whether for an upgrade, provider switch, or scaling need — follows a fairly systematic process when approached carefully.
Step 1 — Document Your Current Stack
docker compose configReview the fully-resolved configuration, including any environment variable substitutions, so you understand exactly what's actually running before migrating.
Step 2 — Back Up All Volume Data
docker run --rm -v myapp_postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz /dataRepeat for each named volume in your stack — this is your actual application data and must be transferred correctly.
Step 3 — Transfer Backup Archives to the New Server
scp *.tar.gz newuser@NEW_SERVER_IP:/home/newuser/Step 4 — Set Up Docker on the New Server
See How to Install Docker Engine on Ubuntu & Debian (Complete Guide) and How to Install Docker Compose on Ubuntu & Debian.
Step 5 — Transfer Your Compose Files and Configuration
scp docker-compose.yml .env newuser@NEW_SERVER_IP:/home/newuser/myapp/Step 6 — Recreate Volumes and Restore Data on the New Server
docker volume create myapp_postgres-data
docker run --rm -v myapp_postgres-data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-data.tar.gz -C /Step 7 — Start the Stack on the New Server
docker compose up -dStep 8 — Verify Everything Started Correctly
docker compose ps
docker compose logsConfirm all services are running and healthy (see How to Set Up Health Checks for Docker Compose Services) before proceeding.
Step 9 — Verify Data Integrity
Check that migrated data is actually present and correct — spot-check database records, verify file uploads are accessible, confirm application functionality end-to-end before considering migration complete.
Step 10 — Update DNS to Point to the New Server
See How to Point a Domain to Your VPS (A/AAAA Records) and Understanding DNS Propagation and TTL — lower TTL in advance of the migration if minimizing cutover disruption matters.
Step 11 — Keep the Old Server Running Briefly as a Fallback
Don't immediately decommission the old server — keep it available (stopped or running) for a reasonable period in case you discover an issue with the migration and need to quickly revert DNS back.
Minimizing Downtime: A More Advanced Approach
For genuinely minimal-downtime migration, consider setting up the new server fully in advance, syncing data close to cutover time (rather than a single full backup/restore), and switching over with only a brief final sync gap — more complex, but reduces the actual downtime window significantly for production-critical applications.
Common Errors
Application starts but shows no data — verify volume names match exactly between the backup/restore process and what the compose file actually expects; a volume naming mismatch is a common migration mistake.
Continue Reading
- Docker Volumes: How to Persist Data Beyond a Container's Lifecycle
- How to Migrate an E-commerce Store to a New VPS Without Downtime
- How to Point a Domain to Your VPS (A/AAAA Records)
Browse more articles in Docker & Containers.
