Rails assets precompile is the build step that turns your stylesheets, JavaScript and images into fingerprinted files in public/assets, so production can serve them fast and cache them forever. It’s also one of the most common reasons a Rails deploy fails: the task boots your whole app in production mode, so a missing credential, a database call in an initializer or a missing Node binary stops the build. This guide explains what bin/rails assets:precompile does in Rails 8, how to run it in Docker, CI and on a PaaS, and how to fix the errors you’ll actually see.

TL;DR

• bin/rails assets:precompile runs any JS/CSS build hooks (jsbundling, cssbundling, tailwindcss-rails), then Propshaft or Sprockets copies every asset to public/assets with a content digest in the filename and writes a manifest.
• Run it once per release at build time with RAILS_ENV=production and SECRET_KEY_BASE_DUMMY=1. Never run it on boot, and never pass real credentials to the build.
• The task boots the full app, so initializers that read credentials or touch the database are the top cause of precompile failures.
• Keep the previous release’s assets during a deploy. assets:clean keeps two versions and anything from the last hour, while assets:clobber deletes everything and causes 404s for users mid-session.
• In production keep config.assets.compile = false (Sprockets) and serve public/assets with a one-year immutable cache header.

Table of Contents

• What does rails assets:precompile do?
• Prerequisites
• Step 1: Configure production for precompiled assets
• Step 2: Run precompile locally in production mode
• Step 3: Precompile inside the Docker build
• Step 4: Precompile in CI and keep old assets across deploys
• Step 5: Verify it works
• How Heroku, Render, Fly.io, Upsun and Enkihost precompile assets
• Troubleshooting assets:precompile errors
• Author Perspective: precompile is a smoke test
• Precompiled assets on Enkihost
• FAQ
• Sources

What does rails assets:precompile do?

assets:precompile runs any registered JavaScript and CSS build steps, then copies every file in the asset load path to public/assets with a content hash in the name, and writes a manifest that maps logical names like application.css to digested names like application-4f2a9c1e.css.

The details depend on which asset library your app uses:

Two things are true for both:

1. It boots the app. Precompile is a Rake task that loads config/environment.rb, so every initializer runs in the production environment.
2. Build hooks run first. jsbundling-rails, cssbundling-rails and tailwindcss-rails enhance assets:precompile with javascript:build, css:build or tailwindcss:build, so yarn build or the Tailwind CLI runs as part of the same command.

The output is what makes long caching safe. A file whose content changes gets a new name, so browsers and CDNs can cache public/assets/* for a year without serving stale code.

Prerequisites

• Rails 7.1+ (examples use Rails 8.0, Ruby 3.3, Propshaft and importmap; Sprockets differences are noted).
• If you use jsbundling-rails or cssbundling-rails: Node 20+ and Yarn, npm or Bun available where you build.
• A production config/credentials.yml.enc, but you won’t need its key at build time.

Step 1: Configure production for precompiled assets

Production should only ever serve precompiled files. It should never compile assets on request.

# config/environments/production.rb
Rails.application.configure do
  # Sprockets only: never compile on request in production.
  # (Propshaft has no live compilation in production; this line is ignored.)
  config.assets.compile = false

  # Cache digested assets for a year. Safe because filenames change with content.
  config.public_file_server.headers = { "cache-control" => "public, max-age=#{1.year.to_i}, immutable" }

  # Optional: serve assets from a CDN.
  # config.asset_host = "https://cdn.example.com"
end

With Sprockets, also make sure every entry point you load with stylesheet_link_tag or javascript_include_tag is declared:

// app/assets/config/manifest.js (Sprockets only)
//= link_tree ../images
//= link_directory ../stylesheets .css
//= link_tree ../../javascript .js
//= link_tree ../builds
//= link admin.css

Propshaft doesn’t need a manifest: everything in app/assets/*, lib/assets/*, vendor/assets/* and gem asset paths is included automatically. To exclude a folder, use config.assets.excluded_paths << Rails.root.join("app/assets/stylesheets/src").

Step 2: Run precompile locally in production mode

Run the exact command your build will run. If it fails on your machine, it will fail in CI and on the server. If it passes, you’ve ruled out most problems before pushing.

RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 bin/rails assets:precompile

Expected output with Propshaft and importmap looks like this:

Writing application-4f2a9c1e.css
Writing application-b81d03aa.js
Writing controllers/hello_controller-1d2e3f4a.js
...

Check the result and clean up afterwards, so you don’t commit compiled assets or accidentally serve stale ones in development:

ls public/assets | head
cat public/assets/.manifest.json | head -c 400; echo
bin/rails assets:clobber

What SECRET_KEY_BASE_DUMMY=1 does: since Rails 7.1 it makes Rails generate a temporary secret_key_base, so the app can boot without RAILS_MASTER_KEY. It only replaces the secret key base. Any code that reads other credentials at boot still fails, which is covered in Troubleshooting.

Pro Tip: Add public/assets to .gitignore. On Heroku, a committed .sprockets-manifest-*.json or .manifest.json makes the buildpack skip precompile entirely (“Detected manifest file, assuming assets were compiled locally”), and you end up shipping whatever you compiled last month.

Step 3: Precompile inside the Docker build

In a container build, precompile in the build stage after copying the code, and copy only the result into the final image. That keeps Node, Yarn and node_modules out of production.

# Dockerfile (build stage, excerpt)
FROM base AS build

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libpq-dev libyaml-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

COPY Gemfile Gemfile.lock ./
RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git

# If you use jsbundling/cssbundling, install JS deps before copying the app
# so this layer is cached until package.json or yarn.lock change.
# COPY package.json yarn.lock ./
# RUN yarn install --frozen-lockfile

COPY . .

RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# If node_modules exists, drop it before the final stage copies /rails.
RUN rm -rf node_modules tmp/cache

The complete multi-stage file, with the base and final stages, is in how to dockerize a Rails app.

Two Docker-specific details:

• Don’t pass RAILS_MASTER_KEY as a build argument. Build args are visible in docker history. SECRET_KEY_BASE_DUMMY=1 removes the need for it.
• Your .dockerignore should exclude /public/assets and /app/assets/builds/*. Otherwise stale local builds get copied in, and Propshaft may write them next to the fresh ones.

Step 4: Precompile in CI and keep old assets across deploys

When traffic switches to a new release, browsers that loaded the old HTML will still request the old digested files for a while. Your deploy must keep the previous release’s assets available, or those users get 404s and unstyled or broken pages.

How you keep them depends on how you deploy:

With Kamal 2, asset bridging is one line. Kamal extracts the assets from the old and new containers and serves the combined set during the switch. The rest of the Kamal setup is in minimal Rails deployments with Kamal 2 and Thruster:

# config/deploy.yml
service: myapp
image: myorg/myapp
servers:
  web:
    - 192.168.0.1
asset_path: /rails/public/assets

With a CDN and asset_host, precompile in CI and sync to the bucket before deploying, without deleting old files:

# .github/workflows/deploy.yml (excerpt)
- name: Precompile assets
  env:
    RAILS_ENV: production
    SECRET_KEY_BASE_DUMMY: "1"
  run: bin/rails assets:precompile

- name: Upload assets (never delete old digests)
  run: aws s3 sync public/assets s3://myapp-assets/assets --cache-control "public, max-age=31536000, immutable"

Leaving out --delete is deliberate. Old digests stay in the bucket, which costs a few megabytes per release, and pages rendered by the previous release never break. Clean up files older than 30 days with a bucket lifecycle rule.

Pro Tip: assets:clean keeps the two most recent versions of each asset plus anything compiled in the last hour. You can tune it with bin/rails "assets:clean[3]" if your deploys are frequent and sessions are long.

Step 5: Verify it works

After deploying, confirm that assets are digested, served with long cache headers, and that the HTML references the same digests that exist on disk.

# 1. The page references digested assets
curl -s https://example.com/ | grep -oE '/assets/[a-z_/-]+-[0-9a-f]{8,}\.(css|js)' | sort -u

# 2. Each one returns 200 with an immutable cache header
curl -sI https://example.com/assets/application-4f2a9c1e.css | grep -iE "^HTTP|cache-control|content-encoding"
# HTTP/2 200
# cache-control: public, max-age=31536000, immutable
# content-encoding: gzip

# 3. A non-digested path is not served (proves compile is off)
curl -sI https://example.com/assets/application.css | head -1
# HTTP/2 404

Then do one more check that most guides skip: deploy twice in a row, and request an asset digest from the first deploy after the second one finishes. It should still return 200.

How Heroku, Render, Fly.io, Upsun and Enkihost precompile assets

Every platform runs precompile during the build, not at runtime. The differences are whether it happens automatically, and whether old assets survive the next deploy.

Heroku is the only one that handles old-asset retention for you without configuration, because the buildpack carries the asset cache from build to build. On every container-based platform the image is the unit of deploy, so you have to bridge assets yourself.

Enkihost does zero-downtime deploys, so there’s a window where old and new releases overlap, just like on every platform above. The same rule applies: precompile at build time, and use a CDN or asset_host if your pages lazy-load assets long after the first page load.

Troubleshooting assets:precompile errors

Most precompile failures fall into four groups: the app can’t boot without secrets or a database, a JS/CSS build tool is missing, an asset reference doesn’t resolve, or the build runs out of memory.

Missing secret_key_base for 'production' environment

ArgumentError: Missing `secret_key_base` for 'production' environment, set this string with `bin/rails credentials:edit`

Set SECRET_KEY_BASE_DUMMY=1 on the precompile command. On Rails 7.0 and earlier, which don’t support it, use SECRET_KEY_BASE=placeholder bin/rails assets:precompile.

undefined method '[]' for nil or KeyError from credentials

NoMethodError: undefined method `[]' for nil (NoMethodError)
  config/initializers/stripe.rb:1:in `<main>'

An initializer reads a credential that doesn’t exist during the build. Make it tolerant:

# config/initializers/stripe.rb
Stripe.api_key = Rails.application.credentials.dig(:stripe, :secret_key) || ENV["STRIPE_SECRET_KEY"]

Or defer the read until it’s used, for example inside a service object, instead of at boot.

ActiveRecord::ConnectionNotEstablished during precompile

ActiveRecord::ConnectionNotEstablished: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory

Something queries the database at boot: an initializer, a model loaded with a scope evaluated at class-load time, or a gem that reads settings from a table. Find it with bin/rails assets:precompile --trace, then move the query into a method or wrap it in Rails.application.config.after_initialize and check defined?(Rails::Server). Precompile itself never needs a database.

The asset "admin.css" is not present in the asset pipeline

ActionView::Template::Error (The asset "admin.css" is not present in the asset pipeline.)

This shows up at runtime, not at build time: the view references an asset that precompile didn’t output. With Sprockets, add //= link admin.css to app/assets/config/manifest.js. With Propshaft, check the file exists in a load path and that it isn’t in excluded_paths. For jsbundling/cssbundling, make sure the build writes to app/assets/builds/.

jsbundling-rails: Command build failed

jsbundling-rails: Command build failed, ensure `yarn build` runs without errors

Node or Yarn is missing in the build environment, or yarn install didn’t run before precompile. In Docker, install Node in the build stage and run yarn install --frozen-lockfile before assets:precompile. Run yarn build on its own to see the real error.

JavaScript heap out of memory or the build gets Killed

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

esbuild and Tailwind are light, but webpack and large Sass builds aren’t. Raise Node’s heap for the build only, NODE_OPTIONS=--max-old-space-size=2048 bin/rails assets:precompile, or build on a machine with more memory than the runtime server. A plain Killed with exit code 137 means the OS OOM killer stopped the process.

ExecJS::RuntimeUnavailable

ExecJS::RuntimeUnavailable: Could not find a JavaScript runtime. See https://github.com/rails/execjs for a list of available runtimes.

You’re on Sprockets with a processor that needs JavaScript (often uglifier or terser). Install Node in the build stage, or switch the compressor off: config.assets.js_compressor = nil. HTTP compression already does most of the work.

Author Perspective: precompile is a smoke test

I’ve come to treat assets:precompile as the cheapest production smoke test there is. It boots the full app in production mode with no secrets and no database, and if anything in my initializers is fragile, this is where it shows up first, in CI and not at 3 AM after a deploy. I run RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 bin/rails assets:precompile as an explicit CI step on every pull request, even though the Docker build runs it again. When it fails, it’s almost always a credential read at boot, and fixing that makes the app more robust everywhere.

Precompiled assets on Enkihost

Enkihost doesn’t change how Rails builds assets. The same bin/rails assets:precompile you run locally is the command that has to pass, and everything in this guide applies as is:

• Zero-downtime deploys: the new release takes over without dropping in-flight requests. Precompile at build time with SECRET_KEY_BASE_DUMMY=1 and long-cached digested assets keep working through the switch.
• Per-app resource isolation with allocated memory and CPU, so the memory budget you plan for Puma is the one you get, without a build tool competing with it at runtime.
• PostgreSQL and Redis add-ons inject DATABASE_URL and REDIS_URL at runtime, which is one more reason to keep database access out of the precompile step.

Rails and Sinatra apps run on Ignite (5 EUR per month after a 14-day free trial, with PostgreSQL and Redis included) or Blaze (16 EUR per month, with high availability and autoscaling). The free Spark plan is for Jekyll sites. Start at enkihost.com.

FAQ

Do I need to run assets:precompile in development?

No. In development, Propshaft and Sprockets serve assets on demand, and bin/dev runs any JS or CSS watchers. If you precompile locally to test a production build, run bin/rails assets:clobber afterwards, or development will serve the stale compiled files from public/assets.

Should I commit public/assets to git?

No. Compiled assets bloat the repository, go stale, and on Heroku a committed manifest makes the buildpack skip precompile. Compile at build time instead and add public/assets to .gitignore.

What is the difference between assets:clean and assets:clobber?

assets:clean removes old compiled assets but keeps the two most recent versions of each file and anything compiled in the last hour, so pages from the previous release keep working. assets:clobber deletes the whole public/assets directory. Use clean in deploys and clobber only locally.

Does assets:precompile need the database?

No. Precompiling assets never needs a database connection. If the task fails with a connection error, some initializer or class-level code is querying the database at boot, and that code should be made lazy.

Why does precompile succeed but production still returns 404 for assets?

Usually the web server isn’t serving public/assets. Either RAILS_SERVE_STATIC_FILES is unset on an old Rails version, Nginx or Thruster isn’t pointed at public, or the HTML references a digest from a different build than the files on disk. Compare the digest in the page source with the filenames in public/assets.

Sources

• The Asset Pipeline — Rails Guides
• rails/propshaft — GitHub
• rails/sprockets-rails — GitHub
• rails/jsbundling-rails — GitHub
• Kamal configuration: asset_path (asset bridging) — Kamal docs
• Rails Asset Pipeline on Heroku — Heroku Dev Center
• Deploy a Ruby on Rails app — Render Docs
• Rails on Fly.io: Getting started — Fly Docs
• Deploy Ruby on Rails on Upsun — Upsun Docs

To dockerize a Rails app you need three files: a multi-stage Dockerfile that installs gems and precompiles assets in a throwaway build stage, a .dockerignore that keeps secrets and junk out of the build context, and an entrypoint that prepares the database on boot. Rails 7.1 and later generate all three for you, but the generated files assume things your app may not do. This guide walks through each line, adds a Docker Compose stack with PostgreSQL and a job worker, and covers the build errors you’ll hit on the way.

TL;DR

• Rails 7.1+ generates a production Dockerfile, .dockerignore and bin/docker-entrypoint in every new app. For older apps, run bin/rails generate dockerfile from the dockerfile-rails gem.
• Use a multi-stage build: compilers, headers and node_modules stay in the build stage, and the final image only contains runtime libraries, gems and precompiled assets.
• Copy Gemfile and Gemfile.lock before the rest of the code, so bundle install is cached until your dependencies change.
• Run assets:precompile with SECRET_KEY_BASE_DUMMY=1 so the build never needs real credentials, and keep config/master.key and .env out of the image with .dockerignore.
• If you build on an Apple Silicon Mac for x86 servers, build with --platform linux/amd64 and add x86_64-linux to Gemfile.lock.

Table of Contents

• What does it mean to dockerize a Rails app?
• Prerequisites
• Step 1: Generate the Docker files
• Step 2: Understand the production Dockerfile
• Step 3: Write a .dockerignore that protects secrets
• Step 4: The entrypoint script
• Step 5: Run it with Docker Compose and PostgreSQL
• Step 6: Verify it works
• How do I make a Rails Docker image smaller and faster to build?
• How Heroku, Render, Fly.io, Upsun and Enkihost run Rails containers
• Troubleshooting Rails Docker builds
• Author Perspective: the Dockerfile is the deploy contract
• Running a Rails app on Enkihost
• FAQ
• Sources

What does it mean to dockerize a Rails app?

Dockerizing a Rails app means packaging the app, its Ruby version, its gems and its system libraries into one container image that runs the same way on your laptop, in CI and on any server. The image becomes the unit you deploy, roll back and scale.

The payoff is that the server no longer needs Ruby, rbenv, libvips or the right libpq installed. It only needs a container runtime. That’s why Kamal, Render, Fly.io and Heroku’s container stack all start from a Dockerfile.

Since Rails 7.1, rails new generates a production-ready Dockerfile, written by Sam Ruby and based on the dockerfile-rails generator. Rails 8 refined it with Thruster and jemalloc. Use it as your starting point instead of a random blog snippet, then adjust it to your app.

Prerequisites

• Docker Engine 24+ or Docker Desktop with BuildKit. It’s the default builder in current Docker versions.
• A Rails 7.1+ app. The examples use Rails 8.0 and Ruby 3.3.7, PostgreSQL, Propshaft and importmap.
• Your app’s config/master.key, or RAILS_MASTER_KEY, available locally. You’ll pass it at runtime, never at build time.
• About 2 GB of free disk space for the build cache.

Step 1: Generate the Docker files

New Rails 7.1+ apps already contain Dockerfile, .dockerignore and bin/docker-entrypoint. For an older app, or to regenerate the files after adding gems with native extensions, use the dockerfile-rails generator. It inspects your Gemfile and adds the right system packages.

bundle add dockerfile-rails --optimistic --group development
bin/rails generate dockerfile --postgresql --jemalloc

Useful flags:

The generator is idempotent. Run it again after changing the Gemfile and it asks before overwriting each file.

Step 2: Understand the production Dockerfile

The production Dockerfile has three stages: a base with runtime libraries, a build stage that compiles gems and assets, and a final stage that copies only the results. Here is the Rails 8 version for a PostgreSQL app, with comments on what each block is for.

# Dockerfile
# syntax=docker/dockerfile:1
# check=error=true

# Must match .ruby-version
ARG RUBY_VERSION=3.3.7
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

WORKDIR /rails

# Runtime packages only: what the app needs while it runs.
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips postgresql-client && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development"

# ---------- build stage: thrown away after the build ----------
FROM base AS build

# Compilers and headers for native gems (pg, nokogiri, bootsnap...).
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libpq-dev libyaml-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Gemfile first: this layer is cached until dependencies change.
COPY Gemfile Gemfile.lock ./
RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    bundle exec bootsnap precompile --gemfile

# Now the application code.
COPY . .

# Precompile bootsnap cache for faster boot.
RUN bundle exec bootsnap precompile app/ lib/

# Precompile assets without real credentials.
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# ---------- final stage: what ships ----------
FROM base

COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails

# Run as a non-root user.
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
    chown -R rails:rails db log storage tmp
USER 1000:1000

ENTRYPOINT ["/rails/bin/docker-entrypoint"]

# Thruster serves assets, compresses responses and proxies to Puma.
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]

The choices that matter most:

• ruby:3.3.7-slim instead of the full ruby:3.3.7 image. The full Debian image ships compilers and hundreds of packages you don’t need at runtime. On Docker Hub the slim variant is roughly a fifth of the compressed size.
• BUNDLE_DEPLOYMENT=1 makes Bundler refuse to run if Gemfile.lock is out of date, so the image always contains exactly the locked versions.
• BUNDLE_WITHOUT=development skips development gems. Test gems are still installed unless you add test ("development:test"), which also shrinks the image.
• Two COPY steps. Copying Gemfile/Gemfile.lock before the code means a change to a controller doesn’t invalidate the bundle install layer. This is the single biggest win for build time.
• SECRET_KEY_BASE_DUMMY=1 tells Rails to use a throwaway secret during assets:precompile, so you never pass RAILS_MASTER_KEY as a build argument where it would end up in the image history.
• USER 1000:1000 means a compromised process can’t write outside db, log, storage and tmp.

What if my app uses Node, Yarn or jsbundling?

If you use jsbundling-rails or cssbundling-rails, add Node to the build stage only. The final stage doesn’t need Node, because assets are already compiled:

# Dockerfile (build stage, after the apt-get install line)
ARG NODE_VERSION=22.11.0
ARG YARN_VERSION=1.22.22
ENV PATH=/usr/local/node/bin:$PATH
RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \
    /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \
    npm install -g yarn@$YARN_VERSION && \
    rm -rf /tmp/node-build-master

COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

Then add RUN rm -rf node_modules after assets:precompile, so node_modules isn’t copied into the final stage with /rails.

Step 3: Write a .dockerignore that protects secrets

.dockerignore decides what COPY . . sends into the build. Without it you ship your .git history, your logs, your local .env and your master.key inside the image, where anyone who can pull it can read them.

# .dockerignore
/.git/
/.gitignore
/.github/

# Secrets: pass at runtime, never bake into the image
/.env*
!/.env.example
/config/master.key
/config/credentials/*.key

# Local state
/log/*
/tmp/*
!/log/.keep
!/tmp/.keep
/tmp/pids/*
/storage/*
!/storage/.keep
/tmp/storage/*

# Build artifacts rebuilt inside the image
/public/assets
/node_modules/
/app/assets/builds/*
!/app/assets/builds/.keep

# Dev tooling
/.devcontainer/
/.kamal/secrets*
/coverage/
/spec/
/test/
Dockerfile*
.dockerignore

Excluding /spec/ and /test/ is optional. Keep them if you run tests inside the image in CI.

Pro Tip: Check what actually ends up in the build context with docker build --no-cache --progress=plain . and look at the size of the “transferring context” line. If it’s hundreds of megabytes, something big is missing from .dockerignore. It’s usually node_modules, tmp/cache or a storage/ folder full of uploads.

Step 4: The entrypoint script

The entrypoint runs before your CMD. In Rails 8 it does two things: enables jemalloc and prepares the database when the container starts the web server.

#!/bin/bash -e
# bin/docker-entrypoint

# Enable jemalloc for reduced memory usage and latency.
if [ -z "${LD_PRELOAD+x}" ]; then
    LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit)
    export LD_PRELOAD
fi

# If running the rails server then create or migrate existing database
if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then
  ./bin/rails db:prepare
fi

exec "${@}"

db:prepare creates the database if it doesn’t exist and runs pending migrations otherwise. The condition means only the web container migrates; a worker running ./bin/jobs from the same image skips it. If you run several web containers, they’ll all try to migrate at once. Rails takes an advisory lock so only one actually runs, but slow migrations will still block the other containers’ boot. For large apps, run migrations as a separate release step instead. We’ll cover that in the zero-downtime migrations guide.

The file must be executable and use Unix line endings:

chmod +x bin/docker-entrypoint
git update-index --chmod=+x bin/docker-entrypoint

Step 5: Run it with Docker Compose and PostgreSQL

Docker Compose runs the image next to PostgreSQL and a job worker, so you can test the production image locally exactly as it will run on a server.

# compose.yaml
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_production
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app_production"]
      interval: 5s
      timeout: 3s
      retries: 10

  web:
    build: .
    image: myapp:latest
    ports:
      - "3000:80"
    environment:
      RAILS_MASTER_KEY: ${RAILS_MASTER_KEY}
      DATABASE_URL: postgres://app:app@db:5432/app_production
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/up"]
      interval: 10s
      timeout: 3s
      start_period: 30s

  jobs:
    image: myapp:latest
    command: ["./bin/jobs"]
    environment:
      RAILS_MASTER_KEY: ${RAILS_MASTER_KEY}
      DATABASE_URL: postgres://app:app@db:5432/app_production
    depends_on:
      web:
        condition: service_healthy

volumes:
  pgdata:

Notes on this file:

• DATABASE_URL uses db as the host, the Compose service name. Inside a container, localhost is the container itself.
• depends_on with condition: service_healthy waits for pg_isready before Rails boots, so db:prepare doesn’t fail on a database that’s still starting.
• jobs reuses the image built for web and only changes the command. That’s the same pattern Kamal roles and Heroku process types use. See running Rails background jobs in production for when a dedicated worker is worth it.
• The web health check hits /up, the built-in Rails endpoint. The Rails health check guide explains why it should stay shallow.
• Rails 8 uses multiple databases for Solid Queue, Solid Cache and Solid Cable by default. With a single DATABASE_URL, point config/database.yml’s queue, cache and cable entries at the same server with different database names, or give each its own URL.

For a Rails 8 app with a single PostgreSQL server, this database.yml production block works with the Compose file above:

# config/database.yml
production:
  primary: &primary_production
    adapter: postgresql
    encoding: unicode
    pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 3 } %>
    url: <%= ENV["DATABASE_URL"] %>
  cache:
    <<: *primary_production
    url: <%= ENV["DATABASE_URL"].to_s.sub(%r{/([^/?]+)(\?|$)}, '/\1_cache\2') %>
    migrations_paths: db/cache_migrate
  queue:
    <<: *primary_production
    url: <%= ENV["DATABASE_URL"].to_s.sub(%r{/([^/?]+)(\?|$)}, '/\1_queue\2') %>
    migrations_paths: db/queue_migrate
  cable:
    <<: *primary_production
    url: <%= ENV["DATABASE_URL"].to_s.sub(%r{/([^/?]+)(\?|$)}, '/\1_cable\2') %>
    migrations_paths: db/cable_migrate

db:prepare creates app_production, app_production_cache, app_production_queue and app_production_cable on first boot.

Step 6: Verify it works

Build the image, start the stack, and check that the app answers, the database migrated and the worker is running.

export RAILS_MASTER_KEY=$(cat config/master.key)
docker compose build
docker compose up -d
docker compose ps

You should see all three services as running, with db and web marked (healthy):

NAME          SERVICE   STATUS
myapp-db-1    db        Up 40 seconds (healthy)
myapp-web-1   web       Up 30 seconds (healthy)
myapp-jobs-1  jobs      Up 5 seconds

Then check the endpoints and the logs:

curl -i http://localhost:3000/up
# HTTP/1.1 200 OK

docker compose logs web | grep -E "Migrating|Listening"
docker compose exec web ./bin/rails runner 'puts ActiveRecord::Base.connection.select_value("SELECT version()")'
docker compose exec web sh -c 'grep -l jemalloc /proc/[0-9]*/maps'
# /proc/7/maps   <- the Puma process has jemalloc loaded

Finally, check the image itself:

docker image ls myapp
docker history myapp:latest --format "{{.Size}}\t{{.CreatedBy}}" | head -15
docker run --rm myapp:latest ls config/ | grep -c master.key
# 0

The last command should print 0. If it prints 1, your master key is baked into the image. Fix .dockerignore before you push it anywhere.

How do I make a Rails Docker image smaller and faster to build?

Order layers from least to most frequently changed, use a slim base, keep build tools in a separate stage, and cache gem and package downloads with BuildKit mounts. Together these usually turn a 5-minute rebuild into well under a minute when only app code changed.

If you want BuildKit cache mounts without the generator, replace the gem install step:

# Dockerfile (build stage)
COPY Gemfile Gemfile.lock ./
RUN --mount=type=cache,id=bundle,target=/srv/vendor \
    bundle config set app_config .bundle && \
    bundle config set path /srv/vendor && \
    bundle install && \
    mkdir -p vendor && \
    bundle config set path vendor && \
    cp -ar /srv/vendor . && \
    bundle exec bootsnap precompile --gemfile

On CI, use docker buildx build --cache-from type=registry,ref=ghcr.io/me/myapp:buildcache --cache-to type=registry,ref=ghcr.io/me/myapp:buildcache,mode=max so each runner reuses layers from the last build.

Pro Tip: Don’t chase the smallest possible image with Alpine. musl libc means many native gems compile from source, nokogiri and grpc builds get slow, and you’ll debug subtle DNS and locale differences. Debian slim is the pragmatic default.

How Heroku, Render, Fly.io, Upsun and Enkihost run Rails containers

All five platforms can run a Rails container, but they differ in who writes the Dockerfile and who builds it. Fly.io generates one for you, Render builds yours with BuildKit, Heroku prefers buildpacks and treats containers as an alternative, and Upsun runs prebuilt images from a public registry.

The common thread is that the Rails-generated Dockerfile works on every one of them with little or no change. That’s a strong reason to keep it close to the template rather than hand-crafting something clever. If you deploy with Kamal, our Kamal 2 and Thruster guide picks up exactly where this one ends.

Troubleshooting Rails Docker builds

Most Rails Docker failures come from four places: a lockfile without the Linux platform, credentials needed at build time, a CPU architecture mismatch, or a container trying to reach localhost.

Your bundle only supports platforms ["arm64-darwin-24"]

Your bundle only supports platforms ["arm64-darwin-24"] but your local platform is x86_64-linux.
Add the current platform to the lockfile with `bundle lock --add-platform x86_64-linux` and try again.

Your Gemfile.lock was generated on a Mac and doesn’t list Linux. Add the platforms you build for and commit the lockfile:

bundle lock --add-platform x86_64-linux aarch64-linux

Missing secret_key_base for 'production' environment

ArgumentError: Missing `secret_key_base` for 'production' environment, set this string with `bin/rails credentials:edit`

This appears during assets:precompile. Make sure the line is RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile. If an initializer reads Rails.application.credentials.some_api_key! at boot, guard it so the build can load the app without credentials, or move it into a lazy method.

exec format error

exec /rails/bin/docker-entrypoint: exec format error

You built an arm64 image on Apple Silicon and ran it on an amd64 server, or the other way round. Build for the target platform:

docker buildx build --platform linux/amd64 -t myapp:latest .

no such file or directory for an entrypoint that exists

exec /rails/bin/docker-entrypoint: no such file or directory

The file has Windows (CRLF) line endings, so the kernel looks for /bin/bash\r. Convert it with sed -i 's/\r$//' bin/docker-entrypoint and add * text=auto eol=lf to .gitattributes.

connection to server at "localhost" ... failed

ActiveRecord::ConnectionNotEstablished: connection to server at "127.0.0.1", port 5432 failed: Connection refused

Inside a container, localhost is the container. Use the Compose service name (db) or the database host your platform gives you in DATABASE_URL.

Permission denied @ rb_sysopen - /rails/tmp/pids/server.pid

The app runs as user 1000 but a directory it writes to is owned by root. Add the directory to the chown -R rails:rails db log storage tmp line, or mount a volume with the right owner.

Author Perspective: the Dockerfile is the deploy contract

I used to treat the Dockerfile as plumbing, something I copied once and forgot about. Now I see it as the contract between my app and wherever it runs. When a deploy breaks, it’s almost always because that contract changed without anyone noticing: a new gem with a native extension, a credential read at boot, a lockfile missing Linux. My habit is to build the production image locally with docker compose up before every dependency upgrade. It takes three minutes and has saved me from more failed deploys than any CI check.

Running a Rails app on Enkihost

A Dockerfile gives you a portable app. You still need somewhere to run it, a database next to it, and a way to ship new versions without downtime. That’s the part Enkihost takes care of, so the Rails conventions from this guide carry over as they are.

• PostgreSQL and Redis add-ons inject DATABASE_URL and REDIS_URL, the same variables the Compose file above uses, so your database.yml doesn’t change between your laptop and production.
• Zero-downtime deploys switch to the new release without dropping in-flight requests.
• Per-app resource isolation with allocated memory and CPU, so a jemalloc-tuned Puma process gets the resources you planned for.

Rails and Sinatra apps run on Ignite (5 EUR per month after a 14-day free trial, with PostgreSQL and Redis included) or Blaze (16 EUR per month, with high availability and autoscaling). The free Spark plan is for Jekyll sites. See enkihost.com.

FAQ

Does Rails generate a Dockerfile automatically?

Yes. Since Rails 7.1, rails new creates a production Dockerfile, a .dockerignore and a bin/docker-entrypoint script. Rails 8 versions add Thruster and jemalloc. For apps created before 7.1, the dockerfile-rails gem generates the same files with bin/rails generate dockerfile.

Should I use Docker for Rails development too?

It’s optional. The production Dockerfile is not meant for development because it excludes development gems and precompiles assets. Rails 7.2 and later can generate a dev container with rails devcontainer, which is the better route if you want a containerized development environment.

How big should a Rails Docker image be?

A typical Rails app built from the Rails 8 template on ruby slim usually lands in the low hundreds of megabytes uncompressed, depending mostly on native gems and system libraries like libvips. If your image is over 1 GB, check for compilers in the final stage, node_modules, test gems or a missing .dockerignore.

Where should RAILS_MASTER_KEY go when using Docker?

Pass RAILS_MASTER_KEY as a runtime environment variable or secret, never as a build argument and never copied into the image. Use SECRET_KEY_BASE_DUMMY=1 during assets:precompile so the build itself needs no credentials.

Can I use Alpine instead of Debian slim for Rails?

You can, but it rarely pays off. Alpine uses musl libc, so many native gems compile from source, builds get slower, and subtle differences in DNS and locale handling cause hard-to-debug issues. Debian slim images are only modestly larger and work with precompiled gems.

Sources

• Getting Started with Dev Containers and Docker — Rails Guides
• rails/rails: Dockerfile template (railties) — GitHub
• fly-apps/dockerfile-rails — GitHub
• Dockerfile reference — Docker Docs
• Build cache and cache mounts — Docker Docs
• ruby official image (slim variants) — Docker Hub
• Docker on Render — Render Docs
• Container Registry & Runtime (Docker Deploys) — Heroku Dev Center
• Rails on Fly.io: Getting started — Fly Docs
• Choose an image type — Upsun Docs

A Rails health check is the endpoint your proxy or platform polls to decide whether a container may receive traffic. Rails 7.1+ ships one at /up, but it only proves the app booted. It does not check the database, the cache or the job queue. This guide shows how to keep /up as a fast liveness check, add a deep readiness endpoint next to it, and wire both into Kamal, Render and Fly.io without turning a database hiccup into a full outage.

TL;DR

• Rails 7.1+ generates get "up" => "rails/health#show", which returns 200 if the app boots and 500 if it raises on boot. It never touches the database.
• Keep /up shallow and use it for deploy gating and restarts. Add a separate /health/ready that runs SELECT 1, a cache round-trip and a queue heartbeat check, each with a short timeout.
• Never put a database check on the endpoint that triggers restarts: Render restarts an instance after 60 seconds of failures, so a database blip would restart every instance at once.
• Exclude the health path from force_ssl redirects and host authorization, or the check fails with a 301 or a “Blocked hosts” 403 while the app is fine.
• Point an external uptime monitor at the deep endpoint; that’s what pages you when PostgreSQL or Redis go away.

Table of Contents

• What does the built-in Rails health check do?
• Prerequisites
• Step 1: Make sure /up is reachable in production
• Step 2: Build a deep readiness endpoint
• Step 3: Wire the health check into your deploy tool
• Step 4: Verify it works
• How Heroku, Render, Fly.io, Upsun and Enkihost handle health checks
• Troubleshooting Rails health check failures
• Author Perspective: the health check that took us down
• Health checks and zero-downtime deploys on Enkihost
• FAQ
• Sources

What does the built-in Rails health check do?

The built-in Rails health check returns HTTP 200 when the application has booted without raising, and HTTP 500 when it hasn’t. That’s all it does. It’s a liveness signal, not proof that your app can serve real requests.

Every app generated with Rails 7.1 or later has this in config/routes.rb:

# config/routes.rb
Rails.application.routes.draw do
  get "up" => "rails/health#show", as: :rails_health_check
end

Rails::HealthController renders a small green HTML page with status 200. If an exception happens while the request is handled, for example a broken initializer that only blows up when the app is loaded, it rescues it and renders a red page with status 500. It doesn’t open a database connection, ping Redis or check Solid Queue. That’s deliberate: a liveness check should be fast and should only fail when restarting the process would actually help.

The problem is that teams often treat /up as “the app is healthy” and stop there. Then PostgreSQL runs out of connections, every real request returns a 500, and /up stays green.

There are two questions to answer, and they need two endpoints:

Pro Tip: Kubernetes formalised this split as liveness and readiness probes. You don’t need Kubernetes to borrow the idea; it applies to Kamal, Render and Fly.io just as well.

Prerequisites

• A Rails 7.1+ app (examples use Rails 8.0 and Ruby 3.3).
• PostgreSQL via DATABASE_URL. Redis via REDIS_URL is optional.
• Solid Queue or Sidekiq if you want the queue check. It’s optional too.
• curl and jq locally to test the endpoints.

If your app predates Rails 7.1, add the route and controller yourself. Step 2 below works on any Rails 6.1+ app.

Step 1: Make sure /up is reachable in production

The /up route exists by default, but two production settings commonly break it: SSL redirects and host authorization. Exclude the health path from both, and silence it in the logs.

Rails 8 generates these lines in config/environments/production.rb, partly commented out. Here’s the version you want:

# config/environments/production.rb
Rails.application.configure do
  # The app sits behind a TLS-terminating proxy (kamal-proxy, Render, Fly).
  config.assume_ssl = true
  config.force_ssl = true

  # Health checks usually arrive over plain HTTP from inside the network.
  # Don't redirect them to HTTPS.
  config.ssl_options = { redirect: { exclude: ->(request) { request.path.start_with?("/up", "/health") } } }

  # Allow only your real domains...
  config.hosts = [
    "example.com",
    /.*\.example\.com/
  ]
  # ...but let health checks through: they hit the container by IP.
  config.host_authorization = { exclude: ->(request) { request.path.start_with?("/up", "/health") } }

  # A check every second means 86,400 log lines a day. Drop them.
  config.silence_healthcheck_path = "/up"
end

Why each line matters:

• ssl_options redirect exclude: when force_ssl is on without assume_ssl (common on Heroku, or after copying a config between platforms), a plain-HTTP GET /up from the proxy gets a 301 to https://. Kamal expects a 200, so the deploy fails. Render counts 3xx as healthy, so there you get a check that never reaches your app. The exclude keeps /up working either way.
• host_authorization exclude: health checks hit the container on its internal IP or hostname, for example 10.0.1.5:3000, which isn’t in config.hosts. Rails answers 403 Blocked hosts and the container looks dead.
• silence_healthcheck_path: available since Rails 8.0, it removes the health path from the request log entirely.

Step 2: Build a deep readiness endpoint

The readiness endpoint runs a cheap query against each critical dependency, applies a short timeout, and returns 503 with a JSON body that says which check failed.

Create the controller. It inherits from ActionController::API, not ApplicationController, so authentication filters, CSRF, locale switching and anything else you added to your app’s base controller can’t interfere:

# app/controllers/health_controller.rb
class HealthController < ActionController::API
  CHECK_TIMEOUT = 1.0 # seconds per dependency

  def ready
    checks = {
      database: run_check { database_check },
      cache: run_check { cache_check },
      queue: run_check { queue_check }
    }.compact

    healthy = checks.values.all? { |result| result[:status] == "ok" }

    response.headers["Cache-Control"] = "no-store"
    render json: {
      status: healthy ? "ok" : "fail",
      revision: ENV.fetch("GIT_REVISION", "unknown"),
      checks: checks
    }, status: healthy ? :ok : :service_unavailable
  end

  private

  def run_check
    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
    result = yield
    return nil if result == :skip

    { status: "ok", ms: elapsed_ms(started) }
  rescue StandardError => e
    Rails.logger.warn("[health] #{e.class}: #{e.message}")
    { status: "fail", ms: elapsed_ms(started), error: e.class.name }
  end

  def elapsed_ms(started)
    ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
  end

  def database_check
    ActiveRecord::Base.with_connection do |conn|
      conn.transaction do
        # Cap the query itself; a hung database must not hang the check.
        conn.execute("SET LOCAL statement_timeout = '#{(CHECK_TIMEOUT * 1000).to_i}ms'")
        conn.select_value("SELECT 1")
      end
    end
  end

  def cache_check
    key = "health:#{SecureRandom.hex(4)}"
    Rails.cache.write(key, "1", expires_in: 30.seconds)
    raise "cache read-back failed" unless Rails.cache.read(key) == "1"

    Rails.cache.delete(key)
  end

  def queue_check
    return :skip unless defined?(SolidQueue::Process)

    alive = SolidQueue::Process.where(kind: "Worker")
                               .where("last_heartbeat_at > ?", 2.minutes.ago)
                               .exists?
    raise "no Solid Queue worker heartbeat in 2 minutes" unless alive
  end
end

Add the route next to /up:

# config/routes.rb
Rails.application.routes.draw do
  get "up" => "rails/health#show", as: :rails_health_check
  get "health/ready" => "health#ready", as: :readiness_check
end

A few decisions in this controller are worth explaining:

• SET LOCAL statement_timeout limits the check query to one second without changing the timeout for the rest of the connection. If your database is unreachable rather than slow, connect_timeout in database.yml decides how long you wait. Set it to 2–3 seconds so the check fails fast:

# config/database.yml
production:
  primary:
    url: <%= ENV["DATABASE_URL"] %>
    connect_timeout: 2

• with_connection borrows a connection from the pool and returns it right away. It’s the Rails 7.2+ replacement for holding ActiveRecord::Base.connection for the whole request.
• The cache check writes and reads back a random key, so it catches a cache store that accepts writes but drops them. That works the same with Solid Cache, Redis or Memcached.
• The queue check reads Solid Queue’s heartbeat table. Workers update last_heartbeat_at every minute by default, so “no heartbeat in two minutes” means no worker is running. On Sidekiq, swap it for Sidekiq::ProcessSet.new.size.positive?. How those workers run is covered in Rails background jobs in production.
• revision lets you confirm which release answered. Set GIT_REVISION at build time (Kamal sets KAMAL_VERSION for you).

Pro Tip: Don’t add third-party APIs (Stripe, your email provider, S3) to the readiness check. If Stripe has an incident, restarting or un-routing your app won’t help, and a failing check would just add noise to your own alerts. Monitor those separately.

Should the readiness endpoint be public?

It’s fine to expose the readiness endpoint publicly as long as it returns only check names and statuses, never error messages, hostnames or versions of your dependencies. The controller above returns the exception class only. If you’d rather keep it private, require a token:

# app/controllers/health_controller.rb (inside the class)
before_action :require_health_token

def require_health_token
  expected = ENV["HEALTH_TOKEN"].to_s
  provided = request.headers["X-Health-Token"].to_s
  head :not_found unless expected.present? && ActiveSupport::SecurityUtils.secure_compare(provided, expected)
end

Most uptime monitors (Better Stack, UptimeRobot, Checkly) let you send a custom header. The Rails monitoring guide shows how to wire their alerts in next to your metrics.

Step 3: Wire the health check into your deploy tool

Point your deploy tool’s health check at the shallow /up and your uptime monitor at /health/ready. That way a failed dependency alerts you, but never blocks a rollback or triggers a restart loop.

Kamal 2

kamal-proxy polls /up by default, once per second with a five-second timeout, until the new container answers 200 or deploy_timeout (30 seconds by default) runs out. To make the defaults explicit and give slow-booting apps more room:

# config/deploy.yml
service: myapp
image: myorg/myapp

servers:
  web:
    - 192.168.0.1

proxy:
  ssl: true
  host: example.com
  app_port: 80
  healthcheck:
    path: /up
    interval: 1
    timeout: 5

deploy_timeout: 60

If you run a Kamal accessory or a role without the proxy (a job role running bin/jobs), it has no HTTP health check. Kamal just starts it. We covered a full Kamal setup in minimal Rails deployments with Kamal 2 and Thruster.

Render

Set the path in the dashboard (Settings → Health Check Path) or in render.yaml:

# render.yaml
services:
  - type: web
    name: myapp
    runtime: ruby
    buildCommand: bundle install && bin/rails assets:precompile
    startCommand: bundle exec puma -C config/puma.rb
    healthCheckPath: /up

Fly.io

Add an HTTP check to the service in fly.toml. Set grace_period longer than your boot time:

# fly.toml
[http_service]
  internal_port = 3000
  force_https = true

  [[http_service.checks]]
    grace_period = "15s"
    interval = "30s"
    timeout = "5s"
    method = "GET"
    path = "/up"

    [http_service.checks.headers]
      X-Forwarded-Proto = "https"

The X-Forwarded-Proto header tells Rails the request is already HTTPS, which is an alternative to the ssl_options exclude from Step 1.

Docker Compose or plain Docker

The official Rails 8 Dockerfile doesn’t include a HEALTHCHECK. Add one if you run containers with Compose or Swarm:

# Dockerfile (final stage)
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
  CMD curl -fsS http://localhost:80/up || exit 1

The Rails 8 base image already installs curl. Change the port to 3000 if you don’t run Thruster.

Step 4: Verify it works

Check both endpoints locally, then break a dependency on purpose and confirm the readiness check fails while /up stays green.

bin/rails server -e production

curl -i http://localhost:3000/up
# HTTP/1.1 200 OK

curl -s http://localhost:3000/health/ready | jq .
# {
#   "status": "ok",
#   "revision": "unknown",
#   "checks": {
#     "database": { "status": "ok", "ms": 1.8 },
#     "cache":    { "status": "ok", "ms": 0.9 },
#     "queue":    { "status": "ok", "ms": 2.4 }
#   }
# }

Now stop PostgreSQL (or point DATABASE_URL at a closed port) and repeat:

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/up
# 200
curl -s -w "\n%{http_code}\n" http://localhost:3000/health/ready
# {"status":"fail","revision":"unknown","checks":{"database":{"status":"fail","ms":2003.1,"error":"ActiveRecord::ConnectionNotEstablished"}, ...}}
# 503

The database check took about two seconds, which is the connect_timeout from database.yml. If it hangs for 30 seconds or more, that setting isn’t being applied.

Finally, test the deploy path. With Kamal, kamal deploy should print the health check polling and switch over within a few seconds. A useful drill is to deploy a commit whose initializer raises on purpose: the new container never turns healthy, the deploy is cancelled and the old version keeps serving.

How Heroku, Render, Fly.io, Upsun and Enkihost handle health checks

Render and Fly.io use an HTTP health check both to gate deploys and to monitor running instances. Heroku’s Cedar runtime and Upsun don’t let you configure an HTTP health check path at all; they decide readiness from port binding and timing.

Two details stand out:

• Render’s runtime restart is the strongest argument for keeping the platform check shallow. Point healthCheckPath at a deep endpoint, have the database go away for a minute, and Render will restart every instance of your app even though restarting fixes nothing.
• Heroku preboot is time-based. New dynos get traffic about three minutes after the deploy whether or not they’re warm. So on Heroku, an external uptime monitor on /health/ready is your only real readiness signal.

Enkihost does zero-downtime deploys, so the new release takes over without dropping requests, and the shallow /up and deep /health/ready split from this guide works there unchanged. Its deploy check is the container’s state rather than an HTTP path, so, as on Heroku, an external uptime monitor on /health/ready is what tells you the app is actually ready.

Troubleshooting Rails health check failures

Most failing Rails health checks are configuration problems, not application bugs: an SSL redirect, a blocked host, an authentication filter or a boot that takes longer than the deploy timeout.

target failed to become healthy (Kamal)

ERROR (SSHKit::Command::Failed): Exception while executing on host 192.168.0.1:
docker exit status: 1
docker stderr: Error: target failed to become healthy within configured timeout (30s)

Check what the container actually answers:

kamal app logs --since 5m
kamal app exec --reuse "curl -i http://localhost:80/up"

Common causes: a 301 from force_ssl (fix the ssl_options exclude), a 403 from host authorization, the app listening on 3000 while proxy.app_port says 80, or a boot that genuinely takes longer than 30 seconds (raise deploy_timeout).

Blocked hosts: 10.0.1.5:3000

[ActionDispatch::HostAuthorization::DefaultResponseApp] Blocked hosts: 10.0.1.5:3000

The check hits the container by IP, which isn’t in config.hosts. Add the host_authorization exclude from Step 1. Don’t fix it by clearing config.hosts, since host authorization protects against DNS rebinding.

Fly.io: Health check on port 3000 has failed

Health check on port 3000 has failed. Your app is not responding properly.
Services exposed on ports [80, 443] will have intermittent failures until the health check passes.

Usually the app listens on 127.0.0.1 instead of 0.0.0.0, the grace_period is shorter than the boot, or force_ssl redirects the check. Puma must bind 0.0.0.0 (port ENV.fetch("PORT", 3000) in config/puma.rb binds to all interfaces).

The readiness check returns 302 to /login

Your HealthController inherits from ApplicationController and picks up before_action :authenticate_user!. Inherit from ActionController::API (or ActionController::Base) as shown in Step 2.

Every check takes 30+ seconds when the database is down

connect_timeout isn’t set, so the PostgreSQL client waits for the OS TCP timeout. Add connect_timeout: 2 to database.yml, and check that a DATABASE_URL query string isn’t overriding it.

Logs are full of GET /up

On Rails 8, config.silence_healthcheck_path = "/up" removes them. On Rails 7.1/7.2, use config.lograge.ignore_actions = ["Rails::HealthController#show"] if you use Lograge, or filter at your log shipper.

Author Perspective: the health check that took us down

Years ago I wired a “thorough” health check into a load balancer: database, Redis, an external search cluster, the lot. One night the search cluster slowed down, every instance failed its check together, and the load balancer pulled all of them. A degraded search page became a site that was completely down. Since then I’ve followed one rule: the check that can take a box out of rotation only checks the box itself. Everything else goes to a monitor that wakes me up. A real person deciding what to do beats an automated restart loop that makes things worse.

Health checks and zero-downtime deploys on Enkihost

Health checks exist so that a deploy never sends users to a container that isn’t ready, and so that someone hears about a dependency failure before customers do. On Enkihost, the Rails pieces from this guide carry over as they are:

• Zero-downtime deploys: the new release takes over without dropping requests, so the /up route Rails generates for you, plus the ssl_options and host_authorization excludes, is all the app needs.
• PostgreSQL and Redis add-ons inject DATABASE_URL and REDIS_URL, which is exactly what the database_check and cache_check above read from.
• Per-app resource isolation: a noisy neighbour can’t starve your health check, so slow responses point at your own app.

Rails and Sinatra apps run on Ignite (5 EUR per month after a 14-day free trial, with PostgreSQL and Redis included) or Blaze (16 EUR per month, with high availability and autoscaling). The free Spark plan is for Jekyll sites. Start at enkihost.com.

FAQ

What is the /up route in Rails?

The /up route is the health check endpoint that Rails 7.1 and later generate in config/routes.rb. It maps to Rails::HealthController#show and returns 200 when the app has booted without exceptions and 500 otherwise. It does not check the database or any other dependency.

Does the Rails health check test the database connection?

No. The built-in Rails health check only confirms the application booted. To check PostgreSQL, write a separate controller that runs SELECT 1 with a short statement_timeout and returns 503 when the query fails, and point an uptime monitor at it rather than your deploy proxy.

Should a health check return 503 or 500 when a dependency is down?

Return 503 Service Unavailable for a failed dependency check. It tells load balancers and monitors the instance is temporarily unable to serve traffic, while 500 suggests a bug in the endpoint itself. Every major platform treats both as unhealthy, so the choice is about clarity in logs and alerts.

How often should a health check run?

For deploy gating, frequent checks are fine because they only run for seconds: Kamal polls every second by default. For runtime checks, every 10 to 30 seconds is typical. Uptime monitors on a deep readiness endpoint usually run every 30 to 60 seconds, which is enough to alert within a minute or two without loading the database.

Do Sidekiq or Solid Queue workers need a health check?

Workers don’t serve HTTP, so deploy proxies don’t health check them. Monitor them through the readiness endpoint instead: check Solid Queue’s process heartbeats or Sidekiq’s ProcessSet, and alert when no worker has reported in the last two minutes.

Sources

• Rails::HealthController — Rails API
• Configuring Rails Applications: silence_healthcheck_path, host_authorization — Rails Guides
• Kamal proxy configuration: healthcheck — Kamal docs
• Health Checks — Render Docs
• App configuration (fly.toml): http_service.checks — Fly Docs
• Preboot — Heroku Dev Center
• Build and deploy: post_start — Upsun Docs
• rails/solid_queue: process heartbeats — GitHub
• Dockerfile HEALTHCHECK reference — Docker Docs

Rails background jobs move anything slow out of the request cycle: emails, PDF exports, image processing, webhooks, third-party API syncs. In Rails 8 the default answer is Active Job on top of Solid Queue, which stores jobs in your existing database and needs no Redis. Sidekiq is still the right call for very high job volume or apps that already run it. Either way, production comes down to the same three choices: which backend, where the worker process runs, and how jobs behave when they fail and retry.

TL;DR:

• Use Active Job as the interface and pick a backend underneath: Solid Queue (Rails 8 default, database-backed) or Sidekiq (Redis-backed, highest throughput).
• Small apps can run Solid Queue inside Puma with SOLID_QUEUE_IN_PUMA; anything with heavy jobs deserves a dedicated worker process with its own CPU, memory and failure domain.
• Pass record IDs, not objects, and make every job idempotent: both Solid Queue and Sidekiq guarantee at least once, not exactly once.
• Size your database connection pool for web threads plus worker threads, or your jobs will starve your requests (and the other way round).
• Deploys and restarts send SIGTERM to workers; keep jobs short or resumable so a shutdown never loses work.

Table of Contents

• Why Rails apps need background jobs
• Active Job: the interface every backend shares
• Solid Queue vs Sidekiq: choosing a backend
• Setting up Solid Queue in Rails 8
• Where the worker runs: embedded vs dedicated
• How Heroku, Render, Fly.io, Upsun and Enkihost run Rails workers
• Writing jobs that survive retries
• Connection pools, concurrency and memory
• Deploys, shutdowns and recurring jobs
• Monitoring background jobs
• Author Perspective: keep it boring until it hurts
• Running Rails background jobs on Enkihost
• FAQ
• Sources

Why Rails apps need background jobs

A web request should answer in well under a second. Heroku’s own guidance puts the ideal response time under 500 ms and suggests background jobs as soon as requests regularly take more than one second. Anything that waits on the network or chews CPU breaks that budget quickly.

Typical candidates:

• Sending transactional email (welcome, password reset, receipts).
• Generating PDFs, CSV exports and reports.
• Resizing images or processing uploads with Active Storage.
• Calling third-party APIs: payment providers, CRMs, webhooks to customers.
• Periodic housekeeping: cleaning expired sessions, syncing data, sending digests.

The pattern is always the same. The web process enqueues a small message describing the work and responds immediately. A separate worker process picks up the message, does the slow part, retries if it fails and stores the result.

The win is not only speed for the user. A Puma thread blocked for eight seconds on a PDF is a thread that cannot serve anyone else, so moving that work out also raises how much traffic the same server can handle.

Active Job: the interface every backend shares

Active Job is Rails’ built-in abstraction for background work. You write the job once and choose the backend in configuration, which keeps your application code portable between Solid Queue, Sidekiq, GoodJob and others.

bin/rails generate job invoice_export

class InvoiceExportJob < ApplicationJob
  queue_as :default

  retry_on Net::ReadTimeout, wait: :polynomially_longer, attempts: 5
  discard_on ActiveJob::DeserializationError

  def perform(account_id)
    account = Account.find(account_id)
    InvoiceExporter.new(account).call
  end
end

Enqueue it from a controller or model:

InvoiceExportJob.perform_later(current_account.id)

A few things worth knowing from the start:

• perform_later enqueues; perform_now runs inline (useful in tests and consoles, never for slow work in a request).
• perform_all_later enqueues many jobs in one call, which is much cheaper than looping over perform_later when you fan out thousands of jobs.
• retry_on and discard_on declare failure behaviour in the job itself, so it reads the same regardless of backend.
• set(wait: 10.minutes) or set(wait_until: ...) schedules a job for later.

Solid Queue vs Sidekiq: choosing a backend

This is the decision most articles on Rails background jobs revolve around, and for good reason: it determines what infrastructure you run.

Solid Queue is the default in new Rails 8 apps. It stores jobs in a SQL database (PostgreSQL, MySQL or SQLite) and uses FOR UPDATE SKIP LOCKED so several workers can poll the same tables without blocking each other. It ships with recurring tasks, concurrency limits and pause/resume per queue, and failed jobs stay in the database until you retry or discard them.

Sidekiq stores jobs in Redis (or Valkey) and is the long-standing performance leader. One Sidekiq process runs many threads and processes a very high number of jobs per second. It has a mature Web UI and a large ecosystem; batches and rate limiting live in the paid Pro and Enterprise editions.

How to decide:

• New app, modest job volume, you’d rather not run Redis: Solid Queue. One less service to provision, patch, back up and pay for.
• Existing app already on Sidekiq: stay. Migrating a working queue rarely pays off.
• Very high volume, or you want queue traffic off the primary database: Sidekiq with a persistent Redis, or Solid Queue on a separate queue database.

Render’s production Rails guide lands on the same split: Solid Queue on Postgres for new apps with modest volume, Sidekiq on a dedicated key-value store once the database-backed default has been outgrown.

Pro Tip: If you choose Sidekiq, configure Redis with the noeviction memory policy and enable persistence. A Redis that evicts keys under memory pressure will silently delete queued jobs.

Setting up Solid Queue in Rails 8

New Rails 8 apps generate everything for you. The important pieces:

config/environments/production.rb sets the adapter and points Solid Queue at its own database:

config.active_job.queue_adapter = :solid_queue
config.solid_queue.connects_to = { database: { writing: :queue } }

config/database.yml declares a queue database next to the primary one, with migrations in db/queue_migrate. In PostgreSQL this can be a second database on the same server; keeping it separate means a flood of queue writes never fights your application tables for locks or vacuum time.

config/queue.yml defines dispatchers and workers:

default: &default
  dispatchers:
    - polling_interval: 1
      batch_size: 500
  workers:
    - queues: "*"
      threads: 3
      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
      polling_interval: 0.1

Start processing with:

bin/jobs start

For an existing app moving to Solid Queue, add the gem and run bin/rails solid_queue:install, which generates the same configuration files and the queue schema.

To limit how many jobs of a kind run at once (one export per account, say), use concurrency controls:

class InvoiceExportJob < ApplicationJob
  limits_concurrency to: 1, key: ->(account_id) { "invoice_export_#{account_id}" }, duration: 10.minutes
end

Where the worker runs: embedded vs dedicated

Once the backend is chosen, the next question is where the worker process lives. This is where hosting choices start to matter.

Embedded in Puma. Solid Queue ships a Puma plugin. With this line in config/puma.rb (already there in Rails 8):

plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]

setting SOLID_QUEUE_IN_PUMA=1 makes Puma start the Solid Queue supervisor alongside the web server. One container, one deploy, no extra bill. It is a great fit for side projects and apps whose jobs are mostly emails and small API calls. The trade-off: jobs and web requests share the same CPU and memory, so a heavy job slows page loads and a busy site slows the queue.

Dedicated worker. Run bin/jobs (or bundle exec sidekiq) as its own process, container or machine. The queue gets its own CPU, memory and failure domain: a runaway import can be killed or scaled without touching the web tier, and you can scale web and workers independently. This is what you want as soon as jobs do real work, like image processing, large exports or long API syncs.

With Kamal, a dedicated worker is just another role in config/deploy.yml:

servers:
  web:
    - 192.168.0.1
  job:
    hosts:
      - 192.168.0.1
    cmd: bin/jobs

Both roles are built from the same image and roll out together on kamal deploy.

How Heroku, Render, Fly.io, Upsun and Enkihost run Rails workers

Heroku, Render, Fly.io and Upsun all use the same model for Rails background jobs: a second process type built from the same code, scaled independently from web. Enkihost is the exception, with one process per app. What changes is how workers are declared and what they cost.

• Heroku uses the Procfile. You add a worker: line (for example worker: bundle exec sidekiq or worker: bin/jobs) and scale it with heroku ps:scale web=1 worker=1. Sidekiq needs a Heroku Key-Value Store add-on. Each worker is a separate dyno billed on its own.
• Render models workers as a separate Background Worker service. Sidekiq setups add a Render Key Value instance; Solid Queue apps can reuse Render Postgres. The docs recommend a separate worker as soon as a job needs CPU or memory that a page load should not wait for.
• Fly.io uses process groups in fly.toml, for example web = "bin/rails fly:server" and worker = "bundle exec sidekiq", scaled with fly scale count web=2 worker=4. The worker group has no HTTP service attached, so autostop only applies to the web machines.
• Upsun (formerly Platform.sh) declares workers under a workers key in the app configuration, each with its own commands.start (for example bundle exec sidekiq or bin/jobs) and its own container size. Workers inherit the app’s relationships, mounts and variables, so the database and Redis connections come for free, but deploy hooks and cron only run on the web container.
• Enkihost runs one process per app, so there is no worker process type. Jobs run inside Puma with Solid Queue (SOLID_QUEUE_IN_PUMA=true), or with Sidekiq’s embedded mode against the included Redis, and recurring jobs go in config/recurring.yml because there’s no cron. The trade-off: heavy jobs share CPU and memory with web requests, and you can’t scale them separately.

The pattern is sound, but notice the cost structure: on every one of these platforms a dedicated worker is another container or machine with its own resources to pay for, and Sidekiq adds Redis on top. For a small app that sends a handful of emails, that’s often more infrastructure than the problem deserves, which is exactly why embedding Solid Queue in Puma is such a useful option in Rails 8. On Enkihost it isn’t an option but the model, which keeps the bill flat and makes Step 3’s sizing advice more important.

Writing jobs that survive retries

Backends retry failed jobs automatically. Sidekiq retries up to 25 times with exponential backoff spread over roughly three weeks, and Solid Queue keeps failed jobs until you act on them. Both promise at least once execution, not exactly once. Your jobs need to be written with that in mind.

1. Pass IDs, not objects. Arguments are serialized. Pass user.id and load the record inside perform. Active Job’s GlobalID helps here, but a record deleted between enqueue and run will raise ActiveJob::DeserializationError, which you should usually discard_on.
2. Make jobs idempotent. Running the job twice must produce the same result as running it once. Check state before acting (return if invoice.sent?), use unique constraints, and pass idempotency keys to payment and email APIs.
3. Enqueue after commit. If you enqueue inside a transaction, a fast worker can pick up the job before the record is committed and fail to find it. Enqueue from after_commit callbacks or after the transaction block.
4. Keep jobs small. Ten thousand short jobs retry, parallelize and shut down far better than one job that loops for an hour. Fan out with perform_all_later.
5. Be explicit about failure. Use retry_on for transient errors (timeouts, rate limits) and discard_on for permanent ones, rather than letting everything fall into the default retry path.

Pro Tip: Set timeouts on every outbound HTTP call inside a job. A job without a timeout that hangs on a dead API holds a worker thread, and a database connection, until the process is killed.

Connection pools, concurrency and memory

This is the part competitors’ quick-start guides tend to skip, and it is the most common cause of mysterious production errors like ActiveRecord::ConnectionTimeoutError.

Every thread that touches the database needs a connection. Puma web threads hold one each, and so does every worker thread. Fly.io’s Rails hosting guide puts it bluntly: a Sidekiq concurrency of 25 means 25 additional database connections on top of what the web server already uses.

Do the arithmetic before you scale:

• Web: Puma workers × RAILS_MAX_THREADS per web server.
• Jobs: worker processes × threads per process (Sidekiq concurrency, Solid Queue threads in queue.yml), plus a little headroom for Solid Queue’s dispatcher and heartbeats.
• Total: sum both across every server, and stay comfortably under your PostgreSQL max_connections.

Make sure the pool value in database.yml matches the thread count of the process using it. Sidekiq’s default concurrency is 5; Solid Queue’s generated queue.yml uses 3 threads per worker. Raising threads beyond what your database and CPU can handle does not make jobs faster, it just moves the queue from Redis into connection waits.

Memory is the other ceiling. Workers that process images or large files grow over time; Ruby rarely gives memory back to the OS. Run workers with jemalloc (or MALLOC_ARENA_MAX=2) and set a memory limit for the worker container, so a leaking job gets restarted instead of dragging the whole server into swap.

Deploys, shutdowns and recurring jobs

Workers get restarted far more often than people expect: every deploy, every scaling event, and on Heroku, once a day as dynos cycle. The platform sends SIGTERM, waits a grace period, then kills the process.

• Sidekiq stops fetching new jobs on SIGTERM, waits up to its timeout (25 seconds by default) and pushes unfinished jobs back to Redis. Your platform’s shutdown grace period must be longer than that timeout, or jobs get killed mid-run. Upsun, for example, sends SIGKILL 15 seconds after SIGTERM, so Sidekiq there should run with a lower timeout such as bundle exec sidekiq -t 10.
• Solid Queue’s supervisor sends TERM to its workers and waits shutdown_timeout (5 seconds by default) before forcing them to stop. Jobs that were still running are released back to the queue.

The practical rule: long jobs should be resumable. Process in batches, store progress, and let a restarted job continue where it left off.

Recurring jobs used to require cron, whenever or Heroku Scheduler. Solid Queue handles them in config/recurring.yml:

production:
  cleanup_expired_sessions:
    class: CleanupSessionsJob
    schedule: every day at 3am
  sync_exchange_rates:
    command: "ExchangeRate.refresh!"
    schedule: every hour

The dispatcher enqueues them on schedule, and only one instance fires each task even if you run several worker processes.

Monitoring background jobs

A stuck worker fails silently far more often than a web request does. Users report broken pages; nobody reports an email that was never sent.

Watch, at minimum:

• Queue depth per queue, and how long the oldest job has been waiting (queue latency).
• Failed jobs and retry counts, grouped by job class.
• Job duration at p95, so you spot a job that quietly went from two seconds to two minutes.
• Worker memory over time.

Sidekiq’s Web UI covers most of this out of the box. For Solid Queue, mount Mission Control - Jobs to inspect queues, retry or discard failed jobs and pause queues from the browser. We covered the wider monitoring setup, including job metrics, in our Rails monitoring guide.

Author Perspective: keep it boring until it hurts

Start with Solid Queue inside Puma. For most small Rails apps it is enough for far longer than you would expect, and it means one process, one database and nothing extra to monitor. Split the worker into its own process the day a job visibly slows your pages, not before. Reach for Sidekiq and Redis when the numbers tell you to, not because a tutorial assumed you would. The best queue is the one you never have to think about at 2 AM.

Running Rails background jobs on Enkihost

Every platform above can run Rails background jobs; the difference is how many billed pieces it takes. On Enkihost, a Rails 8 app with Solid Queue embedded in Puma runs as a single app with PostgreSQL: set SOLID_QUEUE_IN_PUMA=1 and your jobs run next to your web server with no extra worker service and no Redis bill.

• PostgreSQL and Redis add-ons that inject DATABASE_URL and REDIS_URL automatically, so both Solid Queue and Sidekiq work without manual wiring.
• Zero-downtime deploys: the new container is health-checked before traffic switches, so a release never drops in-flight requests.
• Resource isolation per app, so another tenant’s traffic spike doesn’t slow down your queue.

Our Ignite and Blaze plans start at 5 EUR per month with PostgreSQL and Redis included, and Ignite has a 14-day free trial so you can test your job workload before committing.

FAQ

What are background jobs in Rails?

Background jobs are units of work that run outside the web request, in a separate worker process. Rails provides Active Job as a common interface, and a backend such as Solid Queue or Sidekiq stores the jobs and executes them. They are used for emails, exports, image processing and API calls that would otherwise slow down responses.

Is Solid Queue production ready?

Yes. Solid Queue is the default Active Job backend in Rails 8, it was built at 37signals to run their own production apps, and it supports PostgreSQL, MySQL and SQLite. For very high job volumes, run it on a separate queue database or consider Sidekiq.

Do I still need Redis for Rails background jobs?

Not with Rails 8 defaults. Solid Queue stores jobs in your SQL database, and Solid Cache and Solid Cable cover caching and Action Cable the same way. You only need Redis if you choose Sidekiq or another Redis-backed tool.

Should I run Sidekiq or Solid Queue inside my web process?

Solid Queue can run inside Puma with SOLID_QUEUE_IN_PUMA, which is ideal for small apps with light jobs. Sidekiq is normally run as its own process. Once jobs do CPU or memory-heavy work, give them a dedicated worker so they cannot slow down page loads.

How many threads should a Rails worker use?

Start with the defaults (5 for Sidekiq, 3 for Solid Queue) and make sure your database pool and max_connections can cover web threads plus worker threads. Increase only after measuring: I/O-heavy jobs benefit from more threads, CPU-heavy jobs benefit from more processes instead.

What does Enkihost cost to run a Rails app with background jobs?

A Rails app runs on Ignite at 5 EUR per month, with PostgreSQL and Redis included, or on Blaze at 16 EUR per month. With Solid Queue running inside Puma, background jobs don’t need an extra service, and Ignite includes a 14-day free trial.

Sources

• Active Job Basics — Ruby on Rails Guides
• rails/solid_queue — GitHub
• rails/mission_control-jobs — GitHub
• Sidekiq Best Practices — Sidekiq Wiki
• Worker Dynos, Background Jobs and Queueing — Heroku Dev Center
• Production-Grade Rails Hosting — Render
• Deploy Rails with Sidekiq — Render Docs
• Sidekiq Background Workers — Fly Docs
• Rails Hosting: What Your App Actually Needs — Fly.io
• Work with workers — Upsun Fixed (formerly Platform.sh) Docs

Monitor four signals in every Rails app: database queries and N+1 patterns, request latency at p95 and p99, background job health, and unhandled exceptions. Instrument with ActiveSupport::Notifications for Rails-native events, add OpenTelemetry for portable tracing, and correlate errors with traces so a spike points to a cause, not just a symptom. Start in staging, sample traces before you widen them in production, and route everything to one dashboard.

TL;DR:

• Monitoring query duration and connection pool usage helps catch slow database operations and prevent request queuing before user issues arise.
• Building dashboards that display request latency percentiles, slow route data, and background job trends enables rapid identification of bottlenecks and degraded performance.
• Sample traces at around 10-20% in staging and only widen collection in production after thresholds are tuned to avoid unnecessary overhead and costs.
• Alerts should focus on percentage jumps in latency or error rates rather than fixed thresholds, with tagging deployed code versions to identify recent changes causing issues.
• Using OpenTelemetry and structured, correlated logs improves traceability and faster root cause analysis across both performance and security-related incidents.

Table of Contents

• What to monitor in a Rails app: concrete checklist
• How to instrument Rails: ActiveSupport, OpenTelemetry, and monitoring gems
• Visualization and alerting: dashboards and actionable alerts
• Rollout, overhead, retention, and Rails version compatibility
• Enkihost perspective: how hosting choices affect monitoring
• Logging best practices and integration with monitoring tools
• Security monitoring such as protection against injection and CSRF attacks
• Monitoring external API calls and third-party service latency
• What actually matters once you start monitoring Rails apps
• Enkihost: a managed hosting option for Ruby apps
• FAQ
• Sources
• Primary documentation and implementation links

What to monitor in a Rails app: concrete checklist

Before picking a tool, know what you are actually trying to see. Rails apps fail in a handful of predictable ways, and each one leaves a different fingerprint.

Start with the database, since it is where most Rails slowdowns originate. Watch queries per request, flag anything resembling an N+1 pattern, and treat any query running past 100 milliseconds as worth a second look. Connection pool usage matters just as much: a pool that is constantly maxed out will quietly queue requests behind the scenes long before anyone files a bug report.

Request latency comes next. Average response time hides the problem; percentiles reveal it.

• Track median latency for the typical experience and higher percentiles to capture what slower users feel and what outliers experience, as these usually signal real issues.
• Build request trace waterfalls so you can see exactly where time goes: view rendering, database calls, external API waits.
• Watch throughput alongside latency, since a drop in both often means something upstream is broken, not just slow.
• Flag background job queue depth, runtime distribution, and retry counts for Sidekiq or ActiveJob.
• Group exceptions by type and track error rate over time rather than raw counts.

According to Rails Pulse, effective Rails monitoring hinges on four critical areas: database query performance and N+1 detection, request latency percentiles, background job health, and unhandled exception rates. That is a useful filter when you are deciding what deserves a dashboard tile and what can live in the logs.

System-level indicators round things out: CPU, memory, garbage collection pauses, and open database connections. None of these tell the whole story alone, but together they explain why a seemingly healthy app starts timing out under load.

How to instrument Rails: ActiveSupport, OpenTelemetry, and monitoring gems

Rails already ships with most of what you need. ActiveSupport::Notifications is the framework’s built-in instrumentation API, and it fires events like process_action.action_controller and sql.active_record without any extra gem.

• Subscribe to process_action.action_controller for full request timing, including view and database breakdowns.
• Subscribe to sql.active_record to catch slow or repeated queries as they happen.
• Use monotonic_subscribe instead of subscribe for timing-sensitive events, since it avoids wall-clock drift from system time changes.
• Keep subscriber logic lightweight; heavy synchronous work inside a callback slows down the very request you are trying to measure.

For portability across backends, OpenTelemetry for Ruby adds a vendor-neutral tracing layer. A typical setup lives in config/initializers/opentelemetry.rb:

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

c.use_all enables every available instrumentation gem it detects, which is convenient to start but worth narrowing down once you know which libraries actually matter for your app. Exporters are swappable: use the console exporter while testing locally, then switch to OTLP once you are shipping traces to a real backend.

A separate decision is where that telemetry lives. Self-hosted engines like Rails Pulse and Railswatch store everything in your own application database, which keeps infrastructure simple and data private, though it means watching table growth and retention. Sending traces to a hosted APM instead trades that operational simplicity for a dedicated backend built for querying at scale. Neither is wrong, but pick one deliberately rather than defaulting into whichever gem you found first.

Visualization and alerting: dashboards and actionable alerts

Collecting data is the easy part. Making it useful means building a handful of dashboards that answer specific questions fast.

• A latency histogram showing the full p50 to p99 spread, not just an average.
• A slow requests table sorted by p95, so the worst offenders surface immediately.
• A top routes table ranked by database time, since that is usually where the fix lives.
• A job queue trend chart showing depth and retry rate over the last few hours.

Alerts should fire on change, not just on absolute thresholds. A 30% jump in p95 latency over your rolling baseline matters more than a fixed number that might be normal for your traffic pattern. Pair that with an error-rate spike threshold, a Sidekiq queue depth ceiling, and a rule that flags anything correlated with a recent deploy timestamp.

Pro Tip: Tag every trace and log line with the current deploy SHA. When an alert fires, you will know in seconds whether it lines up with something you just shipped.

Root cause work goes faster when traces, logs, and metrics share a common identifier, usually a request ID, so you can jump from a graph spike straight to the exact trace and its related log lines. Whether you lean on a hosted APM dashboard or build your own with Grafana and Prometheus comes down to team size and appetite for running infrastructure. Hosted tools save setup time; a self-managed stack gives you more control over retention and cost at scale.

Rollout, overhead, retention, and Rails version compatibility

Instrumentation is not free, so roll it out with a plan rather than flipping it on everywhere at once.

1. Deploy instrumentation to staging first and measure the overhead directly, since even a few extra milliseconds per request compounds at scale.
2. Apply trace sampling (start around 10 to 20% of requests) before going to production, keeping full metrics collection separate from sampled traces to control storage cost.
3. Decide retention upfront: traces are expensive to store in full, so keep them sampled, while aggregate metrics can reasonably live longer at low cost.
4. Confirm your instrumentation libraries support your current Rails version. Rails has published end-of-support dates, with supported versions now at 7.2.x, 8.0.x, and 8.1.x, so an app still running 7.0 or 7.1 should prioritize upgrading before adding new tooling on top.
5. Widen trace sampling only after your dashboards and alert thresholds have been tuned against real production data.

Enkihost perspective: how hosting choices affect monitoring

Deploy noise is one of the most common false alarms in Rails monitoring: a latency spike that is really just a slow restart, not a real problem. Our hosting includes zero-downtime deploys specifically designed to remove that category of incident, so the spikes your dashboards do show are worth investigating. Resource isolation per app also means one noisy neighbor’s traffic burst stops showing up as unexplained jitter in your own metrics.

Managed hosting tends to make the most sense for small teams and indie hackers who would rather spend evenings shipping features than tuning infrastructure. Larger teams with dedicated ops staff often prefer to self-host telemetry for full control over retention and cost.

Logging best practices and integration with monitoring tools

Logs and metrics answer different questions, and conflating them is a common mistake. Metrics tell you something is wrong; logs tell you why.

Structure your logs as JSON from the start rather than retrofitting it later. A structured log line with request ID, user ID, and controller action attached turns a grep session into a filtered query. Rails’ built-in tagged logging can attach a request ID automatically, which becomes the thread that ties a log line back to a specific trace.

Keep log levels disciplined: info for request lifecycle events, warn for recoverable issues like a retried job, and error reserved for actual failures that need attention. A codebase that logs everything at error trains everyone to ignore error-level alerts, which defeats the purpose.

Where logging earns its keep is integration. Shipping logs to the same backend as your traces and metrics means a single request ID can pull up the full story: the trace showing where time went, the metric showing it was part of a broader spike, and the log line showing the exact exception message and stack trace. Without that correlation, you end up with three separate tools and no fast way between them.

Security monitoring such as protection against injection and CSRF attacks

Monitoring is not only about speed and uptime. Catching an attempted attack early is just as much a part of the job as catching a slow query.

Rails protects against SQL injection by default when you use parameterized ActiveRecord queries, but raw SQL fragments or string interpolation in a where clause reopen that door. Watching for unusual query patterns, especially ones with suspicious characters in parameters, is a reasonable early warning signal worth adding to your logging pipeline.

CSRF protection is enabled by default in Rails through protect_from_forgery, and a spike in CSRF token verification failures is worth alerting on rather than silently discarding. A sudden rise usually means either a broken frontend integration or someone probing for a weakness, and the only way to tell the difference is to look.

Rate limiting unusual request patterns, particularly repeated failed authentication attempts from the same source, belongs in the same monitoring layer as your performance metrics. Treat a burst of 401s the same way you would treat a latency spike: as a signal worth a dashboard tile and an alert, not just a log line nobody reads until after the fact.

Monitoring external API calls and third-party service latency

Your app’s reliability is only as good as the slowest third-party service it depends on. A payment processor having a bad afternoon can make your entire checkout flow look broken, even though your own code never changed.

Instrument outbound HTTP calls the same way you instrument database queries: capture duration, status code, and the specific endpoint being called. This is one area where OpenTelemetry’s auto-instrumentation for common HTTP libraries saves real setup time, since it wraps outbound calls without requiring you touch every integration point by hand.

Set separate latency thresholds for third-party calls than you would for your own database, since network round trips to another company’s servers are inherently less predictable. A timeout and retry strategy, with circuit breaking for services that are clearly down, keeps one failing dependency from cascading into a full outage. Track these calls on their own dashboard panel rather than folding them into general request latency. A 2-second request that spent 1.8 seconds waiting on a third-party API tells a completely different story than one that spent that time in your own database, and your monitoring should make that distinction obvious at a glance.

What actually matters once you start monitoring Rails apps

Most teams over-invest in dashboards and under-invest in alert quality. A beautiful Grafana setup that pages nobody when p95 latency doubles is decoration, not monitoring. The conventional advice to “instrument everything” sounds responsible but usually produces so much noise that real signals get lost in it.

Prioritize in this order: unhandled exceptions first, since they represent concrete broken experiences, then request latency percentiles, then background job health. N+1 detection deserves more attention than most teams give it, since it is often the single highest-leverage fix available, quietly degrading performance across dozens of endpoints at once.

The self-hosted-versus-hosted-APM debate gets more airtime than it deserves. Pick whichever keeps you looking at the data regularly. A self-hosted gem you actually check every day beats a feature-rich APM dashboard gathering dust behind a login nobody remembers the password to.

Enkihost: a managed hosting option for Ruby apps

Monitoring tells you what is wrong; good hosting prevents a chunk of those problems from happening in the first place. We offer hosting aimed at Ruby developers, with zero-downtime deploys designed to eliminate restart-related noise in latency graphs, automated database provisioning to reduce connection-pool misconfiguration, and resource isolation to prevent one app’s traffic spike from causing jitter in another.

• Zero-downtime deploys help ensure deploy events do not masquerade as incidents on your dashboards.
• Automated PostgreSQL and Redis provisioning, with practical defaults from the start.
• Resource isolation to support consistent performance under load.

This fits indie hackers and small startups who want fewer moving parts to monitor in the first place. Check Ignite and Blaze to see which plan fits your app, with a 14-day free trial on Ignite to test it against your own workload.

FAQ

What is a Rails app?

A Rails app is a web application built on Ruby on Rails, a server-side framework that follows the model-view-controller pattern and emphasizes convention over configuration. It handles routing, database interaction through ActiveRecord, and view rendering, which is why monitoring a Rails app means watching those same three layers for slowdowns.

Is Rails still relevant?

Yes, Rails continues to receive active development and official support, with the project regularly publishing new releases and support timelines for current versions like 7.2.x, 8.0.x, and 8.1.x. Ongoing maintenance and a mature ecosystem of monitoring and deployment tooling are strong signals that the framework remains a practical choice for new projects.

Is GitHub still a Rails app?

GitHub’s core platform has long been built on Ruby on Rails, and the company has publicly discussed its continued investment in the framework rather than migrating away from it. Exact architecture details change over time, but Rails remains central to how the platform is described publicly.

What will Ruby on Rails be like in 2026?

Based on the project’s own release pattern, expect continued point releases building on the 8.x line, with support maintained for 7.2.x, 8.0.x, and 8.1.x and older versions like 7.0 and 7.1 reaching end of life. Teams still running unsupported versions should plan an upgrade path, since instrumentation and monitoring gems increasingly target current releases first.

Should I use a self-hosted monitoring gem or OpenTelemetry?

Self-hosted gems like Rails Pulse store telemetry directly in your app database, which keeps setup simple and data private but requires watching table growth over time. OpenTelemetry trades that simplicity for vendor-neutral tracing that can export to multiple backends, which suits teams expecting to scale their observability stack beyond a single app.

Sources

• Rails Pulse — Observability for Rails
• Active Support Instrumentation — Ruby on Rails Guides
• OpenTelemetry Ruby — Getting started
• railspulse/rails_pulse — GitHub
• Rubyonrails

Primary documentation and implementation links

• Active Support Instrumentation — Ruby on Rails Guides
• New Rails releases and end of support announcement
• Rails Pulse — Observability for Rails
• OpenTelemetry Ruby — Getting started
• railspulse/rails_pulse — GitHub

For most Rails apps today, the fastest production path is Rails 8’s Kamal 2 to a Linux VM, or a Rails-focused managed host that handles zero-downtime deploys for you. Either route needs the same checklist: secrets handled properly, database provisioning sorted, assets built, and a rollback plan you’ve actually tested. Puma tuning, and safe migrations come right after that.

TL;DR:

• Fully control your stack with a Linux VM or opt for managed Rails hosting to reduce operational complexity and deployment time.
• Rails 8’s improvements, including Kamal 2, enable deploying a production-ready server on a Linux VM in under two minutes, simplifying infrastructure choices.
• Always build a reproducible Docker image, manage secrets securely, handle migrations carefully, and test health checks and critical paths after each deployment.
• Puma’s default settings are conservative; tuning worker processes and threads based on your hardware and load testing can improve latency and throughput.
• Use backward-compatible migrations, feature flags, and Kamal’s rollback features to ensure safe upgrades and quick recovery from failed deployments.

Table of Contents

• 1. Choosing Between VM, Container, and Managed Hosting
• 2. What Rails 8 Changes About Deployment
• 3. Your Production Deployment Checklist
• 4. Puma Tuning: Workers, Threads, and Memory
• 5. Zero-Downtime Deploys and Safe Migrations
• 6. Deploying Background Jobs and Worker Processes
• 7. Scaling Rails Apps: Horizontal Growth and Load Balancing
• 8. Rollback Strategies Beyond the Deploy Itself
• 9. Disaster Recovery and Backup Planning
• 10. Author Perspective: Matching the Flow to Team Size
• Getting Started With Enkihost
• FAQ
• Sources

1. Choosing Between VM, Container, and Managed Hosting

Every Rails deployment ends up in one of three buckets, and picking the right one upfront saves you weeks of regret later.

• VM or bare container deploy: full control over the stack, lowest monthly cost, but you own patching, monitoring, and the 2 AM pager duty.
• PaaS (Heroku-style): fastest to a first deploy, predictable billing tiers, but you pay a premium as traffic grows and you’re boxed into their buildpacks.
• Managed Rails hosting: Rails-specific automation (database provisioning, zero-downtime deploys, SSL) without the general-purpose cloud console sprawl.

Rails 8’s Kamal 2 narrows the gap between the first two options considerably: a VM deploy that used to take a weekend of systemd configuration now runs through a handful of commands. The deciding factors are how much control you need, how much time you want to spend on ops, your budget, and how fast you need to ship. If your team has no dedicated infrastructure person, that question answers itself pretty quickly.

2. What Rails 8 Changes About Deployment

Rails 8 shipped under the banner “No PaaS Required,” and it’s not just marketing. The release bundles tooling that used to require three or four separate services bolted onto a stock Rails app.

• Kamal 2: turns a fresh Linux VM into a production-ready app server with a single kamal setup command, handling the proxy, SSL certificates, and container orchestration for you.
• Thruster: a lightweight proxy that sits in front of Puma, providing asset caching, compression, and X-Sendfile acceleration, which means many apps can skip a dedicated Nginx setup entirely.
• Solid Queue, Solid Cache, Solid Cable: database-backed adapters for jobs, caching, and Action Cable that let SQLite or Postgres stand in for Redis in a lot of common setups.
• Propshaft: the new default asset pipeline, replacing Sprockets, with a simpler precompilation model.

Setup time to a working production server with Kamal 2 on a standard Linux VM is under two minutes. That’s the number that made a lot of “we need a PaaS” conversations shorter.

3. Your Production Deployment Checklist

Here’s the order that actually works, whether you’re going self-managed or handing it to a managed host.

1. Build a reproducible image. Use the Rails-generated Dockerfile as your base; it already includes Thruster and sensible defaults for Rails 8 apps.
2. Handle secrets properly. Pull credentials from a vault like 1Password or Bitwarden into your CI pipeline rather than hardcoding them into .env files committed anywhere near your repo.
3. Provision the database. Create the production database, run migrations with backward-compatible patterns (more on that below), and confirm connection pooling matches your worker count.
4. Precompile assets. Propshaft simplifies this step considerably since it skips the heavy fingerprinting logic Sprockets used to do, but you still want a CDN in front of static files for anything with real traffic.
5. Deploy. Run kamal setup for a first deploy or kamal deploy for subsequent ones, or push to your managed host’s Git remote if you’ve gone that route.
6. Run health checks. Confirm the app responds on /up (Rails’ built-in health check route) before routing traffic to the new version.
7. Smoke test. Hit your critical paths manually: sign-in, checkout, whatever makes you money, immediately after the deploy completes.

Pro Tip: Keep a one-line rollback command ready before you deploy, not after something breaks.

4. Puma Tuning: Workers, Threads, and Memory

Puma ships as the default web server, and its defaults are conservative on purpose. The generated Puma configuration sets threads to 3 per process, which is a safe starting point but rarely the optimal one for production traffic.

• WEB_CONCURRENCY controls worker processes; set it close to your available CPU cores for throughput-heavy apps.
• RAILS_MAX_THREADS controls threads per worker; fewer threads reduce contention and latency for CPU-bound work, more threads help with I/O-bound requests.
• jemalloc is the recommended memory allocator to fight fragmentation when running multiple threads; MALLOC_ARENA_MAX=2 is the fallback if jemalloc isn’t available on your platform.

Puma’s default thread count is 3 per process, a number meant to be tuned, not trusted blindly. Run a load test before and after any config change, and track P50, P95, and P99 latencies rather than just the average. A warmup period before measurement keeps your numbers honest since cold JIT and connection pools skew the first few requests.

5. Zero-Downtime Deploys and Safe Migrations

Kamal Proxy makes zero-downtime deploys the default behavior rather than a project you have to build yourself. It health-checks the new container before routing any traffic to it, then drains connections from the old one instead of killing it outright.

• Write migrations that are backward-compatible: add columns before you reference them in code, never remove a column the running version still reads.
• Push risky schema changes into background jobs that run after deploy rather than blocking the release.
• Avoid migrations that take long table locks during business hours; test them against a staging copy of production data first.

Pro Tip: Gate anything scary behind a feature flag so a bad release is a toggle, not a redeploy.

6. Deploying Background Jobs and Worker Processes

Background jobs don’t deploy themselves just because your web containers updated, and this is where a lot of first-time Rails deployments quietly break. If you’re running Sidekiq, it needs its own process definition in your Kamal config or Procfile, separate from the web role, with its own restart policy and its own memory ceiling.

Active Job sits on top of whichever backend you’ve picked, and Rails 8’s Solid Queue changes the calculus here: since it stores jobs in your existing database instead of Redis, you can run the worker as another role in the same deploy without standing up a separate Redis instance. That’s one less moving part to monitor, patch, and pay for.

Whichever backend you use, workers need to restart in step with web containers during a deploy, or you’ll run old job code against a new database schema, which is a reliable way to generate 2 AM alerts. Kamal handles multi-role deploys natively: define a workers role alongside web in your deploy.yml, and both roll out together. Watch queue depth and job latency after every deploy, not just web response times, since a stuck worker process fails silently far more often than a web request does.

7. Scaling Rails Apps: Horizontal Growth and Load Balancing

Vertical scaling (bigger server, more RAM) gets you further than most people expect with Rails 8’s leaner dependency list, but eventually you’ll need more than one box. Horizontal scaling means running multiple app servers behind a load balancer, and Kamal supports this directly by letting you list multiple hosts under the same role in your configuration.

The database usually becomes the bottleneck before the app servers do. Read replicas help for read-heavy workloads, and connection pooling (via PgBouncer or similar) keeps a growing worker count from exhausting your database’s connection limit. Rails’ built-in support for multiple databases makes splitting reads from writes a configuration change rather than a rewrite.

Session storage matters too once you have more than one web server: make sure sessions live in the database or a shared store rather than in-process memory, or users will get logged out every time the load balancer routes them to a different box. Solid Cache handles this cleanly since it’s already database-backed by default in Rails 8.

8. Rollback Strategies Beyond the Deploy Itself

Zero-downtime deploys solve the “swap containers without dropping requests” problem, but a bad release still needs a way back. Kamal makes application rollbacks straightforward: kamal rollback redeploys the previous container image, and because Kamal Proxy health-checks it the same way, the switch is just as safe as a forward deploy.

Database rollbacks are the harder half. Reversing a migration that already ran against production data can lose information if you’re not careful, which is why backward-compatible migrations matter so much: when new code and old code can both run against the same schema, a code rollback doesn’t require a schema rollback at all. Reserve destructive migrations (dropping columns, renaming tables) for a separate deploy after the new code has been live and stable for a while.

Keep a written rollback runbook, not a mental one. It should name the exact commands, who has access to run them, and what “stable” looks like before anyone approves removing the safety net.

9. Disaster Recovery and Backup Planning

A deployment strategy that doesn’t account for losing a server entirely isn’t finished. Automated, regular database backups are the baseline: most managed Postgres offerings handle this out of the box, but a self-managed VM setup needs an explicit backup job and, more importantly, a tested restore process.

Store backups somewhere other than the server they came from. Test the restore periodically rather than assuming the backup file is valid; a backup you’ve never restored is a guess, not a safety net. For Rails apps using Active Storage, make sure uploaded files are backed up with the same rigor as the database, since they often live in a separate bucket that’s easy to forget.

Document your recovery time objective and recovery point objective in plain terms: how long can the app be down, and how much data can you afford to lose. Those two numbers decide whether nightly backups are enough or whether you need continuous replication.

10. Author Perspective: Matching the Flow to Team Size

Solo devs should lean on a managed host or a bare Kamal setup. Either way, avoid building ops tooling nobody else will maintain. Small teams do well with managed hosting plus CI, reserving self-managed infrastructure for genuinely custom needs. Larger teams can justify orchestration investment, but Rails 8’s defaults are worth keeping even then.

Getting Started With Enkihost

If you’ve read this far and the idea of running your own VM, patching it, and writing a disaster recovery runbook sounds like a project you’d rather skip, specialized managed hosting can fill that gap. Such services handle zero-downtime deploys, automated database provisioning, and SSL and custom domain setup so a git push can be the whole deployment process.

We’re purpose-built for Ruby: Rails, Sinatra, and Jekyll apps get resource isolation for predictable performance, without the general-purpose cloud console you’d get elsewhere. If you still want full control over the box, a self-managed Kamal 2 setup is the right call, and nothing here argues against that. For everyone else, our Ignite and Blaze plans start at 5 EUR per month with PostgreSQL and Redis included, and Ignite has a 14-day free trial, so you can see the deploy flow before committing.

FAQ

Does Airbnb still use Rails?

Airbnb is widely known in the Rails community as a long-running, large-scale production user of the framework, though we don’t have a sourced figure for their current stack composition here. What’s clear industry-wide is that Rails continues to power major production applications well past the startup stage.

Is Rails better than Django?

Neither framework is universally “better”: Rails favors convention over configuration and ships with more built-in defaults, while Django’s “batteries included” philosophy leans more explicit. The right choice usually comes down to your team’s existing Ruby or Python experience and the ecosystem you’d rather work in.

Is Rails still used?

Yes, and Rails 8’s “No PaaS Required” release shows active, modern investment in the framework, with Kamal 2, Thruster, and the Solid adapters all shipped to simplify production deployment. Rails remains a common choice for startups and established companies building web applications.

What apps are made with Rails?

Rails has powered production apps across e-commerce, marketplaces, SaaS products, and content platforms since its release, though specific current company stacks change over time and aren’t something we track here. The framework’s strength has always been getting a full-featured web app to production quickly.

What does Enkihost cost to deploy a Rails app?

A Rails app runs on Ignite at 5 EUR per month, with PostgreSQL and Redis included, or on Blaze at 16 EUR per month, which adds dedicated vCPUs, high availability and autoscaling. Ignite has a 14-day free trial so you can test the deployment flow before paying. The free Spark plan is for Jekyll sites.

Sources

• Rails 8.0: No PaaS Required
• Tuning performance for deployment — Ruby on Rails Guides

The infrastructure world is fundamentally divided into two camps: developers who want to git push and forget about it, and sysadmins who want complete control over their systemd services.

This division manifests in the eternal debate between using a Managed Platform as a Service (PaaS) and spinning up a raw, Dedicated Debian Server (or VPS).

The industry often sells a binary narrative: PaaS is for modern, fast-moving teams, and dedicated servers are legacy infrastructure for neckbeards. However, the reality is far more nuanced. Let’s take a pragmatic look at when it’s actually worth paying for a managed PaaS, and when a dedicated Debian server wins in pure simplicity.

When a Managed PaaS is Worth Every Penny

A managed PaaS (like Heroku, Render, or specialized platforms like Enkihost) abstracts away the operating system, the web server, and the deployment pipeline. You pay a premium on raw compute resources, but you buy time.

1. Speed to Market and Developer Focus When you are validating a startup idea or rushing to launch an MVP, your bottleneck is development time, not server costs. A PaaS handles SSL certificate provisioning, reverse proxies, and automated builds out of the box. If paying 20€/month saves your developers five hours of sysadmin work, the ROI is immediate.

2. Out-of-the-Box CI/CD & Zero-Downtime Setting up a reliable, zero-downtime deployment pipeline (Blue/Green deployments) on a raw server requires orchestrating Docker, Traefik/Nginx, and health checks. A good PaaS gives you this instantly. When you git push, traffic isn’t routed to the new version until it’s fully healthy.

3. Team Scalability If you have a team of frontend and backend developers without a dedicated DevOps engineer, a PaaS provides a unified dashboard where anyone can view logs, manage environment variables, and rollback bad deployments without needing SSH keys or Linux administration skills.

When a Dedicated Debian Server Wins in Simplicity

There is a massive misconception that managing a single server is complex. For many applications, a dedicated Debian server (from providers like Hetzner, OVH, or DigitalOcean) is actually simpler and far more robust than navigating the proprietary limitations of a PaaS.

1. Predictable, Flat-Rate Economics PaaS providers make their margins on convenience and bandwidth. If your application suddenly requires heavy CPU processing (like image manipulation) or consumes terabytes of bandwidth, a PaaS bill can skyrocket overnight. A dedicated Debian server gives you massive amounts of RAM, CPU, and bandwidth for a flat, predictable monthly fee (often under 40€ for absolute beast machines).

2. The Elegance of Boring Technology Sometimes, a PaaS forces you to adopt complex paradigms (like ephemeral file systems or specific containerization strategies) that your app doesn’t actually need. For a simple API or a background worker, setting up a Debian server is beautifully boring:

• Install Ruby/Node/Python.
• Run git pull.
• Set up a basic systemd service.
• Let it run for 5 years without touching it.

No forced container restarts, no sleeping tiers, no arbitrary timeout limits on web requests. Just Linux doing what Linux does best.

3. State and Storage Simplicity Modern PaaS architectures require everything to be stateless. If you want to store a file, you must configure AWS S3. If you want to run a database, you need a managed database cluster. On a dedicated Debian server, everything can live together. You can run PostgreSQL locally, save files directly to the SSD, and back up the entire machine via cron job. For small to medium projects, this monolithic architecture is significantly easier to reason about and debug.

The Pragmatic Verdict

So, how do you choose?

• Choose a PaaS if your primary constraint is engineering time, your application is stateless, you deploy multiple times a day, and you want hands-off CI/CD pipelines without knowing what Nginx is.
• Choose a Dedicated Debian Server if your application is resource-hungry (needs lots of RAM or CPU), you value predictable billing over automated pipelines, or you prefer the “boring” simplicity of having your database, files, and application running on one massively overpowered machine.

Bridging the Gap

The sweet spot often lies somewhere in the middle. With tools like Docker and self-hosted orchestrators, or specialized, reasonably-priced platforms like Enkihost (which offers PaaS-like git push deployments for Ruby apps without the exorbitant enterprise pricing), you can increasingly get the deployment simplicity of a PaaS backed by the predictable economics of dedicated servers.

Choose the tool that lets you sleep at night—whether that’s a dashboard with a “Deploy” button, or an SSH terminal connected to Debian 12.

For years, the Ruby community has accepted a false premise: if you want a reliable, zero-downtime deployment for your Ruby on Rails, Sinatra, or Jekyll applications, you have to pay a premium.

Developers are routinely pushed toward expensive “Platform as a Service” (PaaS) providers where a basic setup starts at 7€/month for a hobby tier that sleeps, and quickly scales to 50€/month or more once you need production-grade reliability and zero-downtime deployments.

But what if you could get the same developer experience, seamless GitHub integration, and robust zero-downtime architecture for just 5€ a month?

Let’s break down the real cost of hosting your Ruby applications and compare a typical 50€/month premium setup with Enkihost.

The 50€/Month Trap: The “Premium” PaaS

When you use a popular premium provider, you aren’t just paying for server resources—you are paying for the brand, the ecosystem, and bloated overhead.

To achieve a true zero-downtime deployment on these platforms, you typically can’t rely on their basic 7€ or 10€ tiers. To ensure that your users don’t experience a 502 Bad Gateway while your new code compiles and your application restarts, these providers require you to run multiple instances (dynos or containers).

A typical production setup looks like this:

• 2x Web Instances (required for rolling restarts): 25€/month each = 50€/month
• Automated Deployments: Included
• Total Cost: 50€/month (and this doesn’t even include a managed database).

You are essentially forced into a multi-node architecture just to avoid dropping connections during a 30-second deployment window.

The 5€/Month Solution: Enkihost

Enkihost was built specifically for Ruby developers who want the PaaS experience without the PaaS price tag. Designed exclusively for Rails, Sinatra, and Jekyll, it cuts out the bloat and delivers exactly what modern developers need.

For just 5€/month, Enkihost provides a streamlined, fully automated pipeline:

• Direct Git Integration: Connect directly to your GitHub repositories. Push to your main branch, and Enkihost handles the rest.
• Zero-Downtime Architecture Built-In: Unlike legacy platforms that require you to buy multiple servers to achieve rolling restarts, Enkihost utilizes a modern reverse-proxy and containerized deployment strategy.
• How it works: When you deploy, Enkihost builds your new application container in the background. Your old application continues to serve traffic until the new container is fully healthy and ready to accept requests. The router then instantly flips the traffic to the new version. Zero dropped connections. Zero downtime. One single server instance.

Real Cost Comparison

Why Pay More for the Same Result?

The reality is that server infrastructure has become incredibly cheap and efficient. You shouldn’t have to subsidize a massive corporate cloud platform just to get your Rails app live with professional-grade deployment pipelines.

By focusing strictly on the Ruby ecosystem, Enkihost provides a tailored, highly optimized environment. You get the automated CI/CD experience you love, the zero-downtime architecture your users demand, and a server bill that actually makes sense.

It’s time to stop overpaying for Ruby hosting. Build your app, push to Git, and let Enkihost handle the rest for a fraction of the cost.

Every developer who has ever run a SaaS or side project knows the dread of email deliverability.

For years, the conventional wisdom was simple: “Never run your own mail server. Just pay SendGrid, Mailgun, or Postmark.”

Until recently, that advice made total sense. But then reality caught up:

1. Aggressive Pricing & Tier Traps: The free tiers shrank or vanished, and introductory plans quickly scaled to hundreds of dollars per month as volume climbed.
2. Arbitrary Account Bans: A single false-positive spam complaint or a shared IP pool flag can get your SaaS account suspended overnight with zero human support.
3. Privacy & Data Sovereignty: Piping every user’s transaction, verification link, and password reset through a third-party intermediary creates an unnecessary privacy liability.

While building Enkimail and managing transactional notifications across our infrastructure at Enkihost, we made a conscious choice: take back control of our email delivery pipeline.

We set up a dedicated Debian 12 virtual server running Postfix alongside OpenDKIM, paired with strict DNS authentication (SPF, DKIM, DMARC, and PTR/rDNS), and integrated it directly into our Ruby/Puma application stack.

The outcome? A 9.9/10 score on Mail-Tester, zero emails in Gmail or Outlook spam folders, sub-5ms local queue submission times, and a 78% drop in server RAM usage.

Here is the complete, battle-tested blueprint to achieve 9.9/10 deliverability, complete with real-world production metrics and performance comparisons.

Step 1: The Non-Negotiable Prerequisite: rDNS (PTR Record)

If you ignore this step, nothing else in this guide will save you. Gmail, Microsoft 365, and Yahoo will drop your emails into the void if your server IP fails reverse DNS validation.

1. Choose your Mail FQDN: e.g., mail.yourdomain.com.
2. Create an A record:

   mail.yourdomain.com.    IN A    203.0.113.42
   

3. Configure your VPS Reverse DNS (PTR): Log into your hosting provider dashboard (Hetzner, OVH, DigitalOcean, Linode, etc.), locate your server’s networking settings, and set the PTR / Reverse DNS of your IP (203.0.113.42) to match mail.yourdomain.com.

Verify it locally via terminal:

dig -x 203.0.113.42 +short
# Must return: mail.yourdomain.com.

Step 2: Installing Postfix and OpenDKIM on Debian

Update your system and install the required packages:

sudo apt update && sudo apt install -y postfix postfix-pcre opendkim opendkim-tools mailutils

During the Postfix configuration prompt:

• General type of mail configuration: Select Internet Site.
• System mail name: Enter your primary domain (e.g., yourdomain.com or mail.yourdomain.com).

Step 3: Generating 2048-Bit DKIM Keys

We will use OpenDKIM to cryptographically sign every outgoing email with an RSA key.

Create the directory hierarchy:

sudo mkdir -p /etc/opendkim/keys/yourdomain.com
sudo chown -R opendkim:opendkim /etc/opendkim
sudo chmod go-rwx /etc/opendkim/keys

Generate a 2048-bit DKIM keypair using the selector mail:

sudo opendkim-genkey -b 2048 -d yourdomain.com -s mail -D /etc/opendkim/keys/yourdomain.com
sudo chown -R opendkim:opendkim /etc/opendkim/keys/yourdomain.com
sudo chmod 600 /etc/opendkim/keys/yourdomain.com/mail.private

This generates two files:

• /etc/opendkim/keys/yourdomain.com/mail.private (Your private key — never share this).
• /etc/opendkim/keys/yourdomain.com/mail.txt (Your public key for DNS).

Step 4: Configuring OpenDKIM Tables

OpenDKIM relies on three lookup tables: KeyTable, SigningTable, and TrustedHosts.

1. Key Table: /etc/opendkim/key_table

sudo nano /etc/opendkim/key_table

Add:

mail._domainkey.yourdomain.com yourdomain.com:mail:/etc/opendkim/keys/yourdomain.com/mail.private

2. Signing Table: /etc/opendkim/signing_table

sudo nano /etc/opendkim/signing_table

Add:

*@yourdomain.com mail._domainkey.yourdomain.com

3. Trusted Hosts: /etc/opendkim/trusted_hosts

sudo nano /etc/opendkim/trusted_hosts

Add:

127.0.0.1
localhost
::1
203.0.113.42
.yourdomain.com

4. Master OpenDKIM Configuration: /etc/opendkim.conf

Edit /etc/opendkim.conf:

# OpenDKIM core settings
Syslog          yes
SyslogSuccess   yes
LogWhy          yes
UMask           007
Mode            s
Canonicalization relaxed/simple
OversignHeaders From

# Multi-domain tables
KeyTable            refile:/etc/opendkim/key_table
SigningTable        refile:/etc/opendkim/signing_table
ExternalIgnoreList  refile:/etc/opendkim/trusted_hosts
InternalHosts       refile:/etc/opendkim/trusted_hosts

# Network Socket (avoid chroot permissions issues with TCP loopback)
Socket          inet:8891@127.0.0.1

Restart and enable the OpenDKIM service:

sudo systemctl restart opendkim
sudo systemctl enable opendkim

Check that OpenDKIM is listening on port 8891:

sudo ss -tlpn | grep 8891
# LISTEN 0 5 127.0.0.1:8891

Step 5: Connecting Postfix to OpenDKIM Milter

Now configure Postfix to route all outbound messages through OpenDKIM prior to transmission.

Edit /etc/postfix/main.cf:

# Host and banner identity
myhostname = mail.yourdomain.com
mydomain = yourdomain.com
myorigin = $mydomain
inet_interfaces = loopback-only
inet_protocols = ipv4

# Milter configuration (OpenDKIM integration)
milter_default_action = accept
milter_protocol = 6
smtpd_milters = inet:127.0.0.1:8891
non_smtpd_milters = $smtpd_milters

# Outbound TLS security
smtp_tls_security_level = may
smtp_tls_loglevel = 1
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

# Disable open relay
smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination
mynetworks = 127.0.0.0/8 [::1]/128

Pro Tip: Setting inet_interfaces = loopback-only ensures your Postfix server only accepts mail dispatched locally (e.g. from your web app or background jobs), completely closing off external open-relay attack vectors!

Restart Postfix:

sudo systemctl restart postfix
sudo systemctl enable postfix

Step 6: The Golden Quartet of DNS Records

Deliverability hinges on four DNS records configured at your DNS registrar/Cloudflare:

┌────────────────────────────────────────────────────────────────────────┐
│                        DNS Authentication Matrix                       │
├─────────┬─────────────────────────┬────────────────────────────────────┤
│ Type    │ Host                    │ Value                              │
├─────────┼─────────────────────────┼────────────────────────────────────┤
│ A       │ mail                    │ 203.0.113.42                       │
│ TXT     │ @                       │ v=spf1 ip4:203.0.113.42 -all       │
│ TXT     │ mail._domainkey         │ v=DKIM1; k=rsa; p=MIIBIjANBgkq...  │
│ TXT     │ _dmarc                  │ v=DMARC1; p=quarantine; pct=100;   │
│         │                         │ rua=mailto:dmarc@yourdomain.com   │
└─────────┴─────────────────────────┴────────────────────────────────────┘

1. SPF (Sender Policy Framework)

yourdomain.com.    IN TXT    "v=spf1 ip4:203.0.113.42 -all"

The -all flag indicates a hard fail: no server other than 203.0.113.42 is authorized to send mail on behalf of yourdomain.com.

2. DKIM (DomainKeys Identified Mail)

Inspect the generated public key file:

sudo cat /etc/opendkim/keys/yourdomain.com/mail.txt

Copy the string enclosed in parentheses and publish:

mail._domainkey.yourdomain.com.    IN TXT    "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

3. DMARC

_dmarc.yourdomain.com.    IN TXT    "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-reports@yourdomain.com; adkim=r; aspf=r"

The Proof: 9.9/10 Score on Mail-Tester

To verify the complete pipeline, send a test email to mail-tester.com:

echo "Testing deliverability from Debian Postfix with OpenDKIM" | mail -s "Test Email Delivery" test-xyz123@srv1.mail-tester.com -a "From: hello@yourdomain.com"

Check /var/log/mail.log in real time:

tail -f /var/log/mail.log

You will observe:

postfix/cleanup[14220]: message-id=<202609271105.xyz@mail.yourdomain.com>
opendkim[13110]: 14220: DKIM-Signature field added (s=mail, d=yourdomain.com)
postfix/qmgr[14210]: 14220: from=<hello@yourdomain.com>, size=628, nrcpt=1 (queue active)
postfix/smtp[14222]: 14220: to=<test-xyz123@srv1.mail-tester.com>, relay=mail.mail-tester.com[...]:25, status=sent (250 2.0.0 Ok: queued as ABC)

The result on Mail-Tester: 9.9/10 - Excellent Score!

• SPF check: Passed
• DKIM signature: Valid & aligned
• DMARC check: Passed
• Reverse DNS: Matched FQDN
• SpamAssassin score: -0.1 (No penalty points)

Production Benchmarks: Real Metrics & Optimizations

Running a mail daemon is only half the battle. How does local mail dispatching compare against standard SaaS APIs, and what does it do to backend memory and CPU usage?

We benchmarked three critical dimensions on our production Debian node running a Ruby (Sinatra/Puma) API with asynchronous Sidekiq job dispatching:

1. Latency Comparison: Local Postfix vs Third-Party REST API

Sending transactional emails via an external SaaS API (SendGrid / Mailgun) involves TLS handshakes, HTTP payload serialization, DNS lookups, and cloud round-trips. With local Postfix, our application deposits messages straight into the local UNIX/loopback queue in microseconds.

Response Time per 1,000 Outbound Requests (Milliseconds)

External SaaS API (HTTP/TLS)
████████████████████████████████████████████ 384 ms (P50) / 840 ms (P99)

Remote SMTP over TLS
████████████████████████ 210 ms (P50) / 495 ms (P99)

Local Postfix Loopback (127.0.0.1:25)
█ 4.1 ms (P50) / 12.8 ms (P99)

Local queue submission is 93x faster than a cloud API. Even if external mail servers experience transient downtime, Postfix handles exponential backoff, retry queues, and bounce processing automatically in the OS background without tying up application worker threads.

2. Memory Footprint: Before vs After Optimizing Puma & Ruby

When integrating mail services with Ruby web servers, improper concurrency and memory fragmentation can quickly bloat virtual machines.

Before optimization, our application ran Puma in standard clustered mode (4 workers, default glibc allocator). Under steady mail-dispatch load, memory creeped steadily toward 2 GB RAM.

By applying three targeted optimizations:

1. Switching to jemalloc (LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2).
2. Downscaling Puma to 2 workers, 5 threads with preload_app!.
3. Offloading mail delivery strictly to local background queues.

Here is the RAM evolution:

RAM Consumption (MB) Under Continuous 50 req/sec Load

Before Optimization (Default glibc, Puma 4 workers):
[0h]   480 MB  ████████
[6h]   1,240 MB ████████████████████
[24h]  1,920 MB ████████████████████████████████ (OOM Risk Zone)

After Optimization (jemalloc, Puma 2 workers, preloaded):
[0h]   185 MB  ███
[6h]   390 MB  ██████
[24h]  412 MB  ██████ (Completely Flat & Stable)

┌────────────────────────────────────────────────────────┐
│               RAM Footprint Comparison                 │
├─────────────────────────┬──────────────┬───────────────┤
│ Metric                  │ Before       │ After (Tuned) │
├─────────────────────────┼──────────────┼───────────────┤
│ Boot RAM                │ 480 MB       │ 185 MB        │
│ 24h Steady-State RAM    │ 1,920 MB     │ 412 MB (-78%) │
│ Ruby GC Pauses          │ 35-50 ms     │ 8-12 ms       │
│ Out-of-Memory Restarts  │ 2 per week   │ 0             │
└─────────────────────────┴──────────────┴───────────────┘

3. CPU Utilization Under Burst Queueing (10,000 Emails)

When dispatching a batch notification or security broadcast to 10,000 users, CPU overhead is dominated by RSA-2048 cryptographic signing inside OpenDKIM and Postfix queue operations:

CPU Usage (%) During 10,000 Email Burst Dispatch

OpenDKIM (RSA-2048 Signing) : ████████████ 24.5%
Postfix Queue Manager (qmgr): ████ 8.2%
Ruby / Sidekiq Process      : ██████ 12.1%
Idle CPU Headroom           : █████████████████████████ 55.2%

Even on a budget 2-vCPU Debian VPS, processing 10,000 signed emails completed in under 3.5 minutes, consuming less than 45% total aggregate CPU capacity.

Ruby Integration Example

Here is how cleanly you can dispatch mail through your local Postfix daemon from any Ruby or Sinatra/Rails app using the native mail gem:

require 'mail'

Mail.defaults do
  delivery_method :smtp, {
    address: '127.0.0.1',
    port: 25,
    enable_starttls_auto: false # Local loopback does not require TLS overhead
  }
end

# Fast, non-blocking asynchronous email delivery
def send_transactional_email(to:, subject:, body_html:)
  Mail.deliver do
    from     'Enkihost Support <hello@yourdomain.com>'
    to       to
    subject  subject
    
    html_part do
      content_type 'text/html; charset=UTF-8'
      body body_html
    end
  end
end

Because it talks to 127.0.0.1:25, the method finishes in milliseconds. Postfix accepts the message, queues it on disk, feeds it to OpenDKIM for instant RSA signing, and delivers it to the recipient MX servers asynchronously.

Key Takeaways

1. Self-hosted mail is alive and well: The narrative that only mega-corporations can deliver email to inboxes is false. Deliverability is governed by mathematical cryptography (DKIM), verifiable identities (SPF/DMARC), and network cleanliness (PTR/rDNS).
2. Infrastructure sovereignty saves money: Zero recurring per-email costs, zero arbitrary API rate limits, and full ownership of user data.
3. Massive latency gains: Replacing an external HTTP API round-trip with a local Postfix submission queue dropped dispatch times from ~400ms to ~4ms.
4. Tune your Ruby environment: Adopting jemalloc and tuning Puma worker concurrency prevents memory bloat, allowing your web app and mail daemon to coexist comfortably on a minimal VPS.

If you have questions about Postfix tuning or DKIM key rotation, drop a comment below.

Developers love the simplicity of modern PaaS platforms like Heroku, Render, and Fly.io: you push your git repository, configure a custom domain, add environment variables, and your application goes live with automated SSL certificates in seconds.

When building Enkihost.com—a specialized hosting platform for Ruby on Rails, Sinatra, and Jekyll websites—we faced an architectural dilemma: should we build an entire cloud orchestration layer from scratch, or could we leverage existing open-source tools?

That’s when we turned to Coolify.

Coolify is widely known as a self-hostable open-source Heroku and Netlify alternative. However, out of the box, Coolify is designed as an admin control panel for solo developers and DevOps teams managing internal infrastructure. It is not built to act as a multi-tenant commercial hosting service with user accounts, custom billing, resource tiering, and white-label deployments.

Instead of writing a custom reverse proxy and certificate manager from scratch, we designed Enkihost to stand on the shoulders of Coolify, Traefik, and the Docker engine.

In this article, we’ll take a deep dive into the real-world architecture of our backend engine (enkihost-sinatra) and explore how we dynamically generate Docker containers, configure Traefik routing labels, manage custom domains with automated Let’s Encrypt certificates, and inject environment variables per deployed website.

High-Level Architecture Overview

Here is how the entire system connects together:

 ┌────────────────────────────────────────────────────────┐
 │             Enkihost Dashboard (Next.js)               │
 └───────────────────────────┬────────────────────────────┘
                             │ REST API / WebSockets
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │            Enkihost Engine (Ruby / Sinatra)            │
 │                                                        │
 │  • App Management & User Quotas (CPU/Memory Limits)   │
 │  • Deployment Worker (Sidekiq / Async Jobs)           │
 │  • DockerService (Container Lifecycle & Traefik)      │
 │  • CoolifyService (API Sync & Fallback Orchestration) │
 └─────────────────────┬──────────────────┬───────────────┘
                       │                  │
        Docker Socket  │                  │ Coolify v4 API
        / CLI Control  │                  │ (Optional Sync)
                       ▼                  ▼
 ┌────────────────────────────────────────────────────────┐
 │                     Host Server (VPS)                  │
 │                                                        │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │      Traefik Reverse Proxy (Coolify Gateway)     │  │
 │  │      - Auto-discovers containers on Docker net   │  │
 │  │      - Automated Let's Encrypt TLS generation   │  │
 │  └──────────────────────────┬───────────────────────┘  │
 │                             │ Docker Network: "coolify"│
 │     ┌───────────────────────┼────────────────────┐     │
 │     ▼                       ▼                    ▼     │
 │ ┌───────────────┐   ┌───────────────┐    ┌───────────┐ │
 │ │ enkihost-app- │   │ enkihost-app- │    │ Managed   │ │
 │ │  12-34 (Web)  │   │  15-35 (Web)  │    │ Addons:   │ │
 │ │ (Rails/Sinatra│   │(Jekyll+Nginx) │    │ Postgres/ │ │
 │ │  Container)   │   │  Container)   │    │  Redis    │ │
 │ └───────────────┘   └───────────────┘    └───────────┘ │
 └────────────────────────────────────────────────────────┘

1. The Strategy: Standing on the Shoulders of Coolify & Traefik

Coolify configures a battle-tested infrastructure environment on your VPS:

1. A Traefik reverse proxy running in a container listening on ports 80 and 443.
2. A dedicated Docker bridge network named coolify.
3. Traefik configured with Docker provider integration and an automated Let’s Encrypt SSL certificate resolver.

Traefik listens to the Docker daemon event socket (/var/run/docker.sock). Whenever a container is launched with specific traefik.* labels on the coolify network, Traefik immediately reads those labels, registers new HTTP/HTTPS routing rules, requests Let’s Encrypt SSL certificates, and forwards incoming traffic to the container’s private port—all with zero configuration file reloads and zero proxy downtime.

By taking advantage of this existing setup, our Sinatra backend only needs to:

• Clone the user’s repository (handling private GitHub credentials securely).
• Generate an optimized Dockerfile (if the user repo doesn’t provide one).
• Build the Docker image.
• Spawn the container attached to the coolify Docker network with the correct Traefik labels, environment variables, resource limits, and persistent storage mounts.

2. Automated Multi-Stage Dockerfile Generation

Not every developer wants to maintain a Dockerfile. In Enkihost, users can push standard Rails, Sinatra, or Jekyll repositories, and our DockerService generates an optimized build recipe on the fly:

def generate_dockerfile
  # If the user already provides a Dockerfile, respect their custom setup
  if File.exist?(File.join(@build_path, "Dockerfile"))
    log("Using existing Dockerfile from repository")
    return
  end

  dockerfile_content = case @app.kind
                       when 'rails'
                         rails_dockerfile
                       when 'sinatra'
                         sinatra_dockerfile
                       when 'jekyll'
                         jekyll_dockerfile
                       end
  
  File.write(File.join(@build_path, 'Dockerfile'), dockerfile_content)
  log("Generated optimized Dockerfile for #{@app.kind}")
end

Multi-Stage Builds for Static Jekyll Sites

For static sites like Jekyll, we don’t want a heavy Ruby runtime running in production. Instead, we use a two-stage build: stage one compiles the site using Ruby and Jekyll, and stage two serves the static _site directory using an ultra-lightweight Alpine Nginx web server:

FROM ruby:3.3-slim AS build
RUN apt-get update -qq && apt-get install -y build-essential libyaml-dev
WORKDIR /rails
COPY Gemfile* ./
RUN bundle install
COPY . .
RUN bundle exec jekyll build

FROM nginx:alpine
RUN echo 'server { \
    listen 80; \
    server_name localhost; \
    location / { \
        root /usr/share/nginx/html; \
        index index.html index.htm; \
        try_files $uri $uri/ /index.html; \
    } \
}' > /etc/nginx/conf.d/default.conf

COPY --from=build /rails/_site /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

This reduces the final container size from ~600MB down to under ~25MB, boots in 100 milliseconds, and consumes almost zero RAM.

3. Dynamic Subdomains, Custom Domains, and Automatic SSL

The real magic happens when provisioning the container. We assign each hosted app:

1. A default platform subdomain: #{app.subdomain}.enkihost.com.
2. Any custom vanity domains the user has added to their dashboard (app.domains.pluck(:fqdn)).

We format these domains into Traefik routing rules and pass them as container labels:

def start_new_container
  image_tag = "enkihost-#{@app.id}-#{@deployment.id}"
  container_name = "enkihost-app-#{@app.id}-#{@deployment.id}"
  
  internal_port = case @app.kind
                  when 'rails' then 3000
                  when 'sinatra' then 4567
                  when 'jekyll' then 80
                  end

  proxy_network = 'coolify'

  # Build domains list
  base_domain = Rails.env.production? ? "enkihost.com" : "localhost"
  default_subdomain = "#{@app.subdomain}.#{base_domain}"
  custom_domains = @app.domains.pluck(:fqdn)
  
  # Format rule for Traefik v3: Host("subdomain.enkihost.com") || Host("custom.com")
  all_domains_rule = ([default_subdomain] + custom_domains)
                     .map { |domain| "Host(\"#{domain}\")" }
                     .join(" || ")

  router_name = "enkihost-app-#{@app.id}-#{@deployment.id}"
  service_name = "enkihost-app-#{@app.id}-#{@deployment.id}"

  labels = [
    "traefik.enable=true",
    "traefik.http.routers.#{router_name}.rule=#{all_domains_rule}",
    "traefik.http.routers.#{router_name}.priority=1000",
    "traefik.http.routers.#{router_name}.service=#{service_name}",
    "traefik.http.routers.#{router_name}.entrypoints=http,https",
    "traefik.http.routers.#{router_name}.tls=true",
    "traefik.http.routers.#{router_name}.tls.certresolver=letsencrypt",
    "traefik.http.services.#{service_name}.loadbalancer.server.port=#{internal_port}",
    "enkihost.app_id=#{@app.id}"
  ]

  # ...

What happens here?

• traefik.http.routers.*.rule: Traefik intercepts incoming HTTP requests matching either the assigned Enkihost subdomain or any of the user’s custom domains.
• traefik.http.routers.*.tls.certresolver=letsencrypt: Traefik automatically contacts Let’s Encrypt via ACME challenge, verifies the domain, and mounts an SSL certificate without manual intervention.
• loadbalancer.server.port: Traefik proxies traffic directly to the container’s internal listening port over the Docker internal virtual bridge, meaning we never have to bind or expose arbitrary host ports on the VPS!

4. Dynamic Environment Variables and Addon Provisioning

Each application needs custom environment variables: API keys, secrets, and database connection strings.

In DockerService, we assemble these into standard -e KEY=VALUE flags:

# 1. Custom user-defined environment variables
env_args = @app.environment_variables.map do |ev|
  ["-e", "#{ev.key}=#{ev.value}"]
end.flatten

# 2. System environment defaults
if %w[rails sinatra].include?(@app.kind)
  env_args += ["-e", "RAILS_ENV=production", "-e", "RACK_ENV=production"]
end

# 3. Automatic Addon Injection (PostgreSQL, Redis)
@app.addons.running.each do |addon|
  case addon.kind
  when 'postgresql'
    env_args += ["-e", "DATABASE_URL=#{addon.config['url']}"]
  when 'redis'
    env_args += ["-e", "REDIS_URL=#{addon.config['url']}"]
  end
end

When a user toggles a PostgreSQL or Redis addon from their Enkihost dashboard, our system spins up an isolated database container and automatically injects DATABASE_URL or REDIS_URL into the application container on the next deployment.

5. Persistent Volumes and Tier-Based Resource Limits

In a multi-tenant hosting platform, you cannot allow a single rogue process to consume 100% of the host server’s CPU or memory. You also need to ensure that user-uploaded files (like images in /rails/storage) survive redeployments.

We enforce resource quotas using native Docker cgroup controls:

cmd_args = [
  docker_bin, "run", "-d", 
  "--name", container_name,
  "--network", proxy_network,
  "--cpus", @app.cpu_limit.to_s,       # e.g., "1.0" or "0.5"
  "--memory", @app.memory_limit.to_s,   # e.g., "512m" or "1g"
  "--restart", "unless-stopped"
]

# Attach Persistent Storage
if @app.storages.any?
  @app.storages.each do |storage|
    cmd_args += ["-v", "#{storage.source}:#{storage.destination}"]
  end
else
  # Default persistent volume for Rails ActiveStorage / file uploads
  default_source = "enkihost-app-#{@app.id}-data"
  default_dest = @app.kind == 'rails' ? "/rails/storage" : "/app/storage"
  cmd_args += ["-v", "#{default_source}:#{default_dest}"]
end

# Add Traefik labels, Environment Variables, and Docker Image
labels.each { |label| cmd_args += ["--label", label] }
cmd_args += env_args
cmd_args << image_tag

system_cmd_array(cmd_args)

By assigning a persistent named Docker volume (enkihost-app-#{app.id}-data), user assets remain safe across code updates, rebuilds, and restarts.

6. Zero-Downtime Container Swapping

When deploying a new version of an app, you cannot immediately kill the existing container—if the new build crashes during boot, your user’s site will go down.

We implement a safe swap pattern:

1. Boot new container: Start enkihost-app-#{app.id}-#{new_deployment.id}.

2. Health poll loop: Poll docker inspect --format '{{.State.Running}}' until the container is confirmed healthy and active.
3. Graceful cleanup: Only once the new container is healthy do we search for older containers belonging to this app (or squatting on the same domain rules) and remove them:

def wait_for_readiness(container_name)
  log("Waiting for container #{container_name} to be ready...")
  max_retries = 30
  retries = 0

  loop do
    is_running = `#{docker_bin} inspect -f '{{.State.Running}}' #{container_name}`.strip == 'true' rescue false
    
    if is_running
      log("Container is up and running.")
      break
    end

    retries += 1
    if retries >= max_retries
      # Abort: clean up failed container and do NOT touch the old running container
      system("#{docker_bin} stop #{container_name}") rescue nil
      system("#{docker_bin} rm #{container_name}") rescue nil
      raise "Container readiness timeout"
    end

    sleep 1
  end
end

def stop_old_container
  current_container = "enkihost-app-#{@app.id}-#{@deployment.id}"

  # Locate previous containers by App ID label
  old_ids = `#{docker_bin} ps -a --filter "label=enkihost.app_id=#{@app.id}" --format "{{.ID}}"`.split("\n")
  
  # Ensure we NEVER kill the new active deployment
  current_id = `#{docker_bin} inspect --format '{{.Id}}' #{current_container}`.strip rescue nil
  old_ids.reject! { |id| id == current_id || current_id&.start_with?(id) }

  old_ids.each do |id|
    log("Pruning superseded container #{id}...")
    system("#{docker_bin} stop #{id}")
    system("#{docker_bin} rm #{id}")
  end
end

Because Traefik routes traffic by container IP and label priority, the moment the new container joins the network and the old one is stopped, Traefik routes 100% of new requests to the new container without dropping a connection.

7. Alternative Path: Coolify v4 REST API Orchestration

While direct Docker daemon control gives us millisecond-level responsiveness for container orchestration, we also built a full integration with Coolify’s official v4 REST API via CoolifyService.

If you prefer to let Coolify handle the build queue directly rather than building on the host Docker daemon, you can interact with its API programmatically:

class CoolifyService
  def initialize
    @url = "#{ENV['COOLIFY_URL']}/api/v1"
    @conn = Faraday.new(url: @url) do |f|
      f.request :json
      f.response :json
      f.headers['Authorization'] = "Bearer #{ENV['COOLIFY_TOKEN']}"
    end
  end

  def create_and_deploy(app)
    # 1. Create Application
    res = @conn.post('applications/public', {
      project_uuid: ENV['COOLIFY_PROJECT_UUID'],
      server_uuid: ENV['COOLIFY_SERVER_UUID'],
      environment_name: 'production',
      git_repository: clean_repo_url(app),
      git_branch: app.branch || 'main',
      build_pack: 'nixpacks'
    })
    coolify_uuid = res.body['uuid']

    # 2. Sync Domains
    domains = ([app.subdomain + ".enkihost.com"] + app.domains.pluck(:fqdn)).join(',')
    @conn.patch("applications/#{coolify_uuid}", {
      domains: domains,
      ports_exposes: "3000"
    })

    # 3. Sync Environment Variables
    app.environment_variables.each do |env|
      @conn.post("applications/#{coolify_uuid}/envs", {
        key: env.key,
        value: env.value.to_s,
        is_literal: true
      })
    end

    # 4. Trigger Deployment
    @conn.post("deploy", { uuid: coolify_uuid, force: true })
  end
end

This hybrid flexibility allows us to deploy either via lightweight Docker commands directly on the server or delegate complex multi-service stacks to Coolify’s native build engine.

8. Hard-Won Production Gotchas & Lessons Learned

Building a hosting platform taught us several valuable lessons that aren’t in the documentation:

1. Traefik v3 Rule Syntax Changes:
   In Traefik v2, multiple host rules could be combined with commas (Host(a.com, b.com)). In Traefik v3, passing multiple arguments to Host() throws a router parse error. You must explicitly chain them with boolean OR operators: Host("a.com") || Host("b.com").
2. Never Expose Host Ports:
   Avoid mapping random host ports like -p 10042:3000. By placing all containers on the shared coolify Docker network, Traefik can talk to containers directly on their internal IP address and internal listening port. This completely eliminates port collisions on the host machine.
3. Token Scrubbing in Build Logs:
   When cloning private repositories with tokens (e.g. https://oauth2:TOKEN@github.com/...), you must sanitize your deployment logs. If Git throws an authentication error or a command echo executes, personal access tokens could leak into public deployment logs. Always pipe build output through a tokenizer sanitizer before broadcasting to WebSockets.
4. Volume Naming Hygiene:
   Always namespace your Docker volumes (e.g. enkihost-app-#{app_id}-data). When an application is deleted by the user, run a comprehensive resource cleanup job (CleanupAppResourcesJob) to remove orphan images, volumes, and stopped containers to prevent disk leaks.

Conclusion

By combining the robustness of Coolify and Traefik with a lightweight Sinatra orchestration backend, we were able to launch Enkihost with the features developers expect from modern cloud hosting—instant deployments, automated Let’s Encrypt certificates, custom domains, and dynamic environment variables—without reinventing the wheel or running bloated infrastructure.

Are you running a self-hosted PaaS or building developer tools on top of Docker and Coolify? Let us know your thoughts, or try deploying your next Ruby or Jekyll site on Enkihost.com!