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?
answer
- three stages: base, build, final
- compilers and -dev headers only in build
- bundle install, bootsnap, assets:precompile
- COPY --from=build gems and /rails
- USER 1000:1000, then ENTRYPOINT and CMD
basics
~20 sThe 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 sThe 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 linesFROM 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
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.
Explain the BUNDLE_* variables, why assets precompile with SECRET_KEY_BASE_DUMMY, and why COPY --from=build copies only the gem directory and /rails.
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.
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.