skip to content

In the Dockerfile that Rails 8.1's `rails new` generates, what do the base, build and final stages each do, and what ends up in the image you run?

level: juniorimportance: must knowfreq 58%

answer

  1. three stages: base, build, final
  2. compilers and -dev headers only in build
  3. bundle install, bootsnap, assets:precompile
  4. COPY --from=build gems and /rails
  5. USER 1000:1000, then ENTRYPOINT and CMD

basics

~20 s

The base stage sets RAILS_ENV=production, the Bundler variables and runtime packages; the build stage adds compilers, installs gems and precompiles assets; the final stage restarts from base, copies only gems and app, and runs as UID 1000.

solid answer

~40 s

The generated Dockerfile has three stages. `base` starts from `ruby:$RUBY_VERSION-slim`, sets `WORKDIR /rails`, installs runtime packages (curl, jemalloc, libvips, the database client) and sets `RAILS_ENV="production"`, `BUNDLE_DEPLOYMENT="1"`, `BUNDLE_PATH="/usr/local/bundle"` and `BUNDLE_WITHOUT="development"`. `build` inherits that, installs `build-essential`, `git`, `pkg-config`, `libyaml-dev` and the database `-dev` package, runs `bundle install`, `bootsnap precompile` and `SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile`. The final stage starts again `FROM base`, creates a `rails` user with UID/GID 1000, switches to `USER 1000:1000` and copies `/usr/local/bundle` and `/rails` from `build` with `--chown=rails:rails`. So the image you run has the gems, the app and its compiled assets, but no compilers and no root process; `ENTRYPOINT` runs `bin/docker-entrypoint` and `CMD` runs `./bin/thrust ./bin/rails server`.

code

dockerfile · 22 lines
dockerfile
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
WORKDIR /rails
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development"

FROM base AS build
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

FROM base
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash
USER 1000:1000
COPY --chown=rails:rails --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --chown=rails:rails --from=build /rails /rails
ENTRYPOINT ["/rails/bin/docker-entrypoint"]
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]

go deeper

for a junior

Name the three stages and say what each contributes: production settings, a throwaway build with compilers, and a final image that runs as an unprivileged user.

for a middle

Explain the BUNDLE_* variables, why assets precompile with SECRET_KEY_BASE_DUMMY, and why COPY --from=build copies only the gem directory and /rails.

for a senior

Show you can extend the file safely: runtime versus -dev packages, frozen lockfile failures in CI, and keeping keys and caches out of every layer.

for a principal

Weigh keeping the generated Dockerfile close to upstream for easy upgrades against customising it, and decide who owns base-image and Ruby version bumps.

## Why the generated Dockerfile is split in three Since Rails 7.1, `rails new` writes a production `Dockerfile` (plus `.dockerignore` and `bin/docker-entrypoint`) unless you pass `--skip-docker`. Its header says it is "designed for production, not development" and is meant to be built and run with Kamal or by hand with `docker build` and `docker run`. The file uses three stages so that everything needed to *build* the app (a C compiler, header packages, git) never reaches the image that *runs* it. ## The base stage: what every later stage shares `base` starts from `docker.io/library/ruby:$RUBY_VERSION-slim`, where `RUBY_VERSION` is an `ARG` set to the Ruby that generated the app (keep it in step with `.ruby-version`). It then: - sets `WORKDIR /rails`, so the app lives at `/rails`; - installs **runtime** packages only: `curl` (the generator adds it for Kamal's default health check), `libjemalloc2`, `libvips` unless Active Storage is skipped, and the database client (`postgresql-client`, `default-mysql-client` or `sqlite3`); - sets the environment that every stage inherits: `RAILS_ENV="production"`, `BUNDLE_DEPLOYMENT="1"`, `BUNDLE_PATH="/usr/local/bundle"`, `BUNDLE_WITHOUT="development"` and an `LD_PRELOAD` line that loads jemalloc. Two Bundler details interviewers probe: 1. `BUNDLE_DEPLOYMENT=1` freezes the lockfile: if `Gemfile` and `Gemfile.lock` disagree, `bundle install` fails with a frozen-mode error instead of rewriting the lock. The explicit `BUNDLE_PATH` wins over the `vendor/bundle` path deployment mode would otherwise pick. 2. `BUNDLE_WITHOUT="development"` drops only gems whose every group is excluded. In the generated Gemfile that is `web-console`; `debug`, `brakeman`, `rubocop-rails-omakase` and `bundler-audit` (in `group :development, :test`) and `capybara` / `selenium-webdriver` (in `group :test`) are still installed. They are not loaded at runtime, because `config/application.rb` calls `Bundler.require(*Rails.groups)`, which requires the default group and the current environment's group (plus any named in `RAILS_GROUPS`). ## The build stage: compile once, throw it away `build` is `FROM base AS build`, so it already has production settings. It adds `build-essential`, `git`, `pkg-config`, `libyaml-dev` and the database's `-dev` package (`libpq-dev` or `default-libmysqlclient-dev`; nothing for SQLite), plus Node or Bun only when the app was generated with a JavaScript bundler. Then, in order: 1. copies `vendor/*`, `Gemfile` and `Gemfile.lock`, runs `bundle install` and deletes the gem caches and git checkouts' `.git` directories; 2. runs `bootsnap precompile -j 1 --gemfile` for the gems; 3. copies the rest of the app (`COPY . .`) and runs `bootsnap precompile -j 1 app/ lib/`; 4. unless the app is API-only or skips the asset pipeline, runs `SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile`, so assets compile without the master key. ## The final stage: only what runs The last `FROM base` has no name and becomes the image. It creates a `rails` system group and user with GID and UID 1000, switches to `USER 1000:1000`, and copies two directories from `build` with `--chown=rails:rails`: the installed gems at `/usr/local/bundle` and the app at `/rails` (now including `public/assets` and the bootsnap cache). It ends with `ENTRYPOINT ["/rails/bin/docker-entrypoint"]` and, with Thruster, `EXPOSE 80` plus `CMD ["./bin/thrust", "./bin/rails", "server"]`. | Stage | Adds | Survives into the image? | |---|---|---| | `base` | Ruby, runtime packages, `RAILS_ENV` and `BUNDLE_*` variables | Yes, the final stage starts from it | | `build` | Compilers, `-dev` headers, gem install, bootsnap cache, compiled assets | Only `/usr/local/bundle` and `/rails` are copied out | | final | `rails` user, ownership, `ENTRYPOINT`, `CMD` | Yes, this is the image | ## Variations the generator applies - `--skip-thruster` swaps the last lines for `EXPOSE 3000` and `CMD ["./bin/rails", "server"]`. - `--api` or `--skip-asset-pipeline` drops the `assets:precompile` line. - `--skip-bootsnap` drops both `bootsnap precompile` steps. - `--skip-active-record` removes the database packages and the `db:prepare` block from the entrypoint. ## Edits that break it Interviewers often hand over a modified copy and ask what goes wrong: - **A runtime library added only to `build`.** The gem's extension compiles, but the final stage starts from `base`, so the shared library is missing and `require` fails at boot. - **`COPY` without `--chown` after `USER 1000:1000`.** `COPY` creates files owned by root unless told otherwise, so the app user cannot write `tmp/`, `log/` or `storage/`. - **Assuming test gems are already excluded.** `BUNDLE_WITHOUT="development"` still installs the `:test` group; list `"development:test"` if the image should not carry `capybara` and `selenium-webdriver`. - **Bumping `.ruby-version` alone.** The `ARG RUBY_VERSION` default must change with it, or the image builds on the old Ruby. Read this way, every line has a reason: build tools and caches stay in `build`, secrets stay out of the build, and the running process is an unprivileged user that owns only the files it needs.

  • Why does the final stage start from `base` rather than from `build`?
    Starting from `base` gives the final image Ruby, the runtime packages and the production environment variables without the compilers, header packages and gem caches the `build` stage installed. Only the two directories copied with `COPY --from=build`, the gems and `/rails`, carry over, so the image stays smaller and has less installed software to patch.
  • The bookstore app adds a gem with a C extension that links against a system library. What do you change in the generated Dockerfile?
    Add the library's `-dev` package to the `build` stage's `apt-get install` so the extension compiles, and add the runtime library package to the `base` stage so the compiled extension can load in the final image. Installing only the `-dev` package in `build` makes the image build but fail when the gem is required.

  • The final image still contains build-essential and the compiler toolchain
  • BUNDLE_WITHOUT=development skips every gem in the development and test groups
  • The container runs as root because the Dockerfile never switches user
  • The final stage runs bundle install again against the Gemfile
  • config/master.key is copied in so production can decrypt credentials

Assumes the Rails 8.1 app generator; the Dockerfile arrived in 7.1, jemalloc in 7.2 and Thruster as the default CMD in 8.0.