Written by James BrittTechnically reviewed by Jim Freeze · Reviewed

Start with a default Rails 8 app and much of the deployment setup is supplied for you: a Dockerfile, a Kamal configuration and a way to run background jobs alongside Puma. Stick with the generated SQLite setup and the databases live on the deployment server as well. The files are there. You still have to decide how much work one machine can handle.
For a smaller Rails team, that is a useful place to start. SSH into the host, inspect the Docker containers and follow a request through a relatively short stack. Kamal 2 takes care of switching releases behind its proxy without requiring a cluster.
The first successful deployment tells you little about a busy afternoon. How much memory will each worker use? Will a queue failure restart the web service? Which versions will still be available for rollback? Find those answers before an outage makes them urgent.
Size the box before you size Puma
When teams leave a platform, they often pick a server by price tier and copy the old host’s Puma settings. Most of the planning in Ruby-Doc’s Rails cloud migration guide still applies on a single machine, connection budget included. There are fewer moving parts on one host, but web and job processes still compete for its resources.
Measure memory under load before choosing the worker count. Use ps -o rss -p PID to read a worker’s resident memory; the output is in KiB. YJIT is enabled by default in production for Rails 7.2 and later on Ruby 3.3 or newer, unless you change that setting. Measure the configuration you plan to run. Account separately for job processes, database memory and Docker. Leaving roughly a third of RAM available is a starting estimate. Check actual pressure during a deployment, when old and new containers briefly coexist.
CPU allocation is another part of choosing hardware. With dedicated server hosting, the six-core Xeon and 64GB of RAM belong to you alone, so the nproc command reports twelve threads that no other tenant can borrow and a worker count picked on Monday still means the same thing on Friday. That example assumes simultaneous multithreading is enabled and all twelve logical CPUs are available to the process. Check the host itself. A shared VM may lose cycles to a neighbour; a nonzero “st” value in top can be a clue to stolen CPU time.
The Rails guide on tuning performance for deployment suggests three threads per worker and one worker per CPU core, and it warns that WEB_CONCURRENCY=auto can get the count wrong on cloud hosts with shared CPUs. Physical cores and logical CPU threads are different counts. Start the example host at six workers, load-test the busiest page, then try eight and compare p95 response times. Keep the settings that hold up under your application’s mix of Ruby work and database waits.
Make the health check tell the truth
Kamal considers a release ready when its proxy gets a successful response from the new container. The kamal-proxy defaults poll /up once a second with a five-second timeout per request, and Kamal stops waiting when its 30-second deploy timeout runs out. Rails answers /up when the application has booted without an exception.
A slow cold boot can look like a broken release. An app that loads a large bundle or warms caches in an initializer may need longer than thirty seconds even though nothing is wrong with the new code. Measure the cold boot, then add some margin in deploy.yml:
deploy_timeout: 60
proxy:
healthcheck:
path: /up
interval: 3
timeout: 3
Try another check in staging: make the database unreachable, then request /up. With the default Rails health controller, you can still get a 200 while pages that query models fail. Boot health and dependency health answer different questions.
A deeper proxy endpoint brings its own trade-off: a ten-second database stall during a release can now fail the deploy. The split that holds up keeps the proxy on the cheap check and hands dependency checks to an outside monitor, the same /up and /health arrangement that Ruby-Doc’s guide to Rails health checks and job heartbeats walks through. Put the monitor on another machine. Anything watching from the same host disappears with it during a server outage.
Decide where the jobs live
Rails 8’s generated deploy.yml sets SOLID_QUEUE_IN_PUMA, and the default Puma configuration uses it to start the Solid Queue supervisor alongside Puma. The Solid Queue README is candid about how tightly that couples the two, since a supervisor that exits takes Puma down with it, and if the queue database is unreachable at boot, neither process stays up. For an app sending a few hundred emails a day, one fewer service to manage may be worth that coupling.
A nightly CSV import changes the calculation. A job holding 1.5GB competes with web requests for the same container budget. In its default fork mode, the plugin starts separate worker and dispatcher processes. They are not request threads, but they share the host and container limits. App preloading is required, which also rules out Puma phased restarts.
For heavier work, enable the job role in deploy.yml. Point it at the same host and give it bin/jobs as its command. Remove SOLID_QUEUE_IN_PUMA from the environment seen by the web role so you do not launch jobs there as well. Now the job container has separate logs and can restart independently. Set and test resource limits, too. Both containers still live on one machine; moving an import does not automatically protect checkout from memory pressure across the host.
Test persistence before the next deployment. The default SQLite queue database is storage/production_queue.sqlite3. Web and job containers need the same persistent storage volume. Lose the mount and a new release may create an empty database while the earlier jobs remain stranded elsewhere. Keep a separate backup and rehearse a restore. A Docker volume survives container replacement; it does not protect against losing the server or deleting the data.
Keep the way back open
Use kamal app containers -q to inspect the releases retained on each host. Rolling back starts a container from one of those local images and switches the proxy to it. There is no new build or registry download. Choose the version deliberately, then run kamal rollback VERSION.
Look at the retention setting instead of assuming you have so many days of history. Current Kamal 2 documentation specifies five retained containers and their images by default, controlled by retain_containers. Regular deployments can use up that history quickly. Check the actual list after a deploy and make sure the known-good version remains available.
Store that version in the incident notes or another place the team can find easily. Knowing the tag helps you choose a target. It does not preserve a pruned local container or make an old release compatible with the current database.
A container rollback leaves the database at its current schema. If the latest migration removed or renamed a column, an older image can fail the moment it reads the table. Use an expand-and-contract migration: add the replacement, deploy code that works through the transition, then remove the old structure after every release you might restore has stopped using it. Check queued jobs as part of that decision.
Treat the Ruby version in the Dockerfile with the same care. Bumping the base image from 3.4 to 4.0 alongside a feature makes any rollback ambiguous, and the Ruby 3.4 to 4.0 upgrade checklist treats the runtime as its own change with its own return path. Deploy the runtime change separately so you can investigate it without a feature change in the same release.
Acquire the deployment lock before investigating: kamal lock acquire -m “investigating 500s”. This blocks another routine Kamal deployment while you inspect the host. Colleagues can read your reason with kamal lock status. Finish the investigation or recovery, then release it with kamal lock release.
Wrap-up takeaway
One server can house a Rails application for years. The useful work is specific: measure workers, test a dependency outage, allow heavy jobs to restart independently and inspect the rollback history. Before the next release, read deploy.yml beside the live container list. Be able to name the version you would restore and explain how it will work with today’s database. Otherwise, the rollback plan needs another rehearsal.
