kamal-docker-production

Kamal + Docker for Rails Production

Ship a Rails 8 app to production without managing Kubernetes or paying Heroku 10× markup. AI agents generate Dockerfiles that work but waste 500MB of image size and 4 minutes of build time. They reach for alpine and trip on native gem compilation. This skill encodes the choices a senior infra-aware Rails dev makes.

Why this matters

Rails 8 ships a Dockerfile out of the box, plus Kamal 2 for deployment. Both are good. But the defaults need understanding — what to keep, what to customize, and how to wire secrets without leaking them to images or logs.

The opinion

Use the Rails-generated multi-stage Dockerfile as the starting point. Base on ruby:3.x-slim (debian-slim), not alpine — alpine's musl libc causes subtle native-gem failures with nokogiri, pg, sassc, and libvips. Use bin/docker-entrypoint for runtime setup (db:prepare). Deploy with Kamal 2. Use Rails credentials for app secrets, Kamal envs (.kamal/secrets) for deployment secrets. Health check at GET /up. Never put secrets in the Dockerfile.

Counter-positions:

• Distroless base images (gcr.io/distroless) are smaller and safer than slim, but every native gem becomes a debugging session. Worth it for super-locked-down envs; over-investment for most.
• Heroku, Fly.io, Render — managed PaaS. Trade money for engineer-hours. Pick if the team's time is better spent on product than ops. Kamal is the answer when you've decided you want your own VMs.
• Kubernetes — appropriate when you actually need its features (multi-cluster, auto-scaling on real signals, multi-team isolation). Don't pick K8s for a single Rails app.

Core patterns

Pattern 1: Multi-stage Dockerfile

# syntax=docker/dockerfile:1
# Pin major+minor; pin patch for reproducibility
ARG RUBY_VERSION=3.3.7
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

# Rails app directory
WORKDIR /rails

# Common deps both stages need
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

# Production env defaults
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development:test" \
    RAILS_SERVE_STATIC_FILES="1" \
    RAILS_LOG_TO_STDOUT="1" \
    MALLOC_ARENA_MAX="2" \
    LD_PRELOAD="libjemalloc.so.2"

# ===== BUILD STAGE =====
FROM base AS build

# Build deps — only here, not in runtime image
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y \
      build-essential git pkg-config libpq-dev libyaml-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Bundle install — cache-friendly: copy Gemfiles first, then app
COPY Gemfile Gemfile.lock ./
RUN bundle install --jobs=4 --retry=3 && \
    bundle exec bootsnap precompile --gemfile && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git

# Copy app code
COPY . .

# Precompile bootsnap caches + assets
RUN bundle exec bootsnap precompile app/ lib/ && \
    SECRET_KEY_BASE_DUMMY=1 bundle exec rails assets:precompile

# ===== RUNTIME STAGE =====
FROM base AS runtime

# Copy gems and app from build stage
COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails

# Non-root user — defense in depth
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 rails:rails

# Entrypoint runs db:prepare on boot; exec replaces shell
ENTRYPOINT ["/rails/bin/docker-entrypoint"]

EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]