Scaling From a Single Server to a Multi-Machine Cluster

One of the best things about Hatchbox is that you can start simple — everything on a single server — and split your app across multiple machines whenever you're ready, without rebuilding anything. This guide walks through the most common scaling moves: adding a worker server for background jobs, and adding a load balancer in front of your web servers.

The one concept that makes it all click

In Hatchbox, your processes (your web server, Sidekiq, etc.) follow roles, not specific machines. A process assigned to the "worker" role runs on every server in the cluster that has the worker role. A process assigned to "web" runs on every web server.

Once that clicks, scaling is mostly just a matter of adding a server, giving it the right role, and deploying. Hatchbox figures out the rest.

Adding a worker server for background jobs

Say you want to move your Sidekiq (or other background) jobs onto their own machine so they're not competing with web traffic.

Will the new worker automatically connect to Redis (and your database)?
Yes. Your Redis and database connection settings already point at your main server's private IP, and the new worker uses those same environment variables — so it connects with nothing to wire up. Hatchbox also automatically opens the firewall on your main server so the new worker can reach Redis and your database over the private network. You don't need to configure any of that by hand.

Steps:

1. Add the new server to your cluster with the Worker role.
2. Deploy.
3. Your background jobs will start running on the new worker.

Moving background jobs off your main server

If your main "everything" server was previously running your background jobs and you now want them only on the new worker, you simply remove the Worker role from the main server. Because processes follow roles, dropping the role tells Hatchbox to stop and clean up those job processes there — and they keep running on the new worker, which still has the role.

Before you do this, quickly check your app's Processes section and confirm your background processes are assigned to the "worker" role (and not pinned to a specific server). If they're on the worker role, you're all set.

Recommended order, so you never have a moment with no workers running:

1. Add the new worker server (Worker role) and deploy.
2. Confirm jobs are processing on the new machine.
3. Remove the Worker role from your main server.

Adding a load balancer

When you're ready to put a load balancer in front of your web server(s), most of the work is automatic.

When you add a server with the Load Balancer role, Hatchbox:

• Installs and configures Caddy on it,
• Automatically discovers all the web servers in your cluster and routes traffic to them,
• Reconfigures your web servers to sit behind the load balancer,
• Handles SSL for you right at the load balancer.

You don't need to set up any firewall rules yourself. When servers join the cluster, Hatchbox automatically opens the necessary ports between your machines over the private network, so your web servers will accept traffic from the load balancer with no manual firewall configuration.

The one manual step: point your domain's DNS (the A record) at the load balancer's IP instead of your web server's. (If you've connected a DNS provider to Hatchbox, it can handle this part for you.)

Steps:

1. Add a server with the Load Balancer role.
2. Deploy — this gets your web servers ready to receive traffic from the load balancer.
3. Update your domain's DNS to point at the load balancer's IP.

Is my site down during the load balancer switch?

No — your site stays up the whole way through. Here's why:

• When you add the load balancer, your DNS is still pointed at your web server, which keeps serving traffic directly, exactly as before. The load balancer is set up off to the side but isn't in the traffic path yet.
• After you deploy, your web servers are ready to take traffic from the load balancer — but your site is still being served directly the whole time (DNS hasn't moved), so there's no downtime.
• When you move your DNS to the load balancer, even that isn't a hard cutover. As DNS propagates, some visitors still reach your old web server's IP directly (works fine) and some reach the load balancer (also works fine) — both serve your app at the same time, so there's no broken window. Once everyone has resolved to the new IP, you're fully balanced.