Moving Your App to a Different-Sized Server (When In-Place Resizing Isn't Available)

Sometimes you need to move your app to a different server — for example, you want to upsize (or downsizesize) but your hosting provider doesn't support resizing an existing machine in place, so you have to spin up a brand-new server.

The good news: you don't have to recreate your apps to do this. This guide walks you through migrating to a new server while keeping everything intact.

The key concept: apps live on the cluster, not the server

In Hatchbox, your apps belong to a cluster, not to any individual server. A server is just the machine the cluster deploys onto. This means you can swap the underlying server out and your apps — along with their environment variables, domains, and cron jobs — all stay exactly as they are.

So migrating to a new server isn't about recreating anything. It's about adding a new server to your existing cluster, moving your data over, and removing the old one.

What moves automatically vs. what you'll do by hand

• Automatic: Your apps, environment variables, domains, and cron jobs all live at the cluster level, so they carry over with no recreation needed.
• Manual: Your databases. If your databases run directly on your server (rather than on a managed/external database), they're tied to that specific machine, so you'll dump the data from the old server and restore it onto the new one. A full database dump includes both the structure and the data — and Rails' record of which migrations have already run — so there's no need to rebuild your schema or re-run migrations. Future deploys will continue running new migrations as normal.

Before you start

• Make sure you have current backups of all your databases. Don't delete the old server until you've confirmed everything is working on the new one.
• Plan for a short maintenance window during the database move, so no new data is written to the old database while you're copying it.

Step-by-step

1. Spin up your new server and add it to the same cluster. Give it the same roles your current setup needs — typically Web and Worker, plus your database engine (e.g. PostgreSQL, MySQL, Redis).
2. Put your apps into maintenance mode. This prevents new data from being written to the old database while you're migrating it.
3. Migrate your database data. Dump each database from the old server and restore it onto the new one. (You can use Hatchbox's Backups feature to generate the dump.)
4. Point your apps at the new database, then deploy and confirm everything is working as expected.
5. Take your apps out of maintenance mode once you've verified the new server is serving correctly.
6. Move the Cron role to the new server. Only one server per cluster can hold the Cron role, so this is done as the final handoff step — it's what runs your scheduled jobs and migrations on deploy.
7. Delete the old server. Once you're confident everything is running on the new server and your backups are safe, you can remove the old one.

A few things to keep in mind

• Double-check your backups before deleting anything. This is the one step you can't undo, so confirm the new server is fully working first.
• Your database connection settings (e.g. DATABASE_URL) point at the database server, so they'll be updated when you set the database up on the new server.
• If you run Redis only for caching or background jobs, you may not need to migrate its data at all — just point your app at the new Redis.