Ruby Deploy

Ruby Deployment

Detection

Project is Ruby if Gemfile exists at the root.

Versions

Ruby version priority:

1. .ruby-version file
2. Gemfile → ruby directive
3. mise.toml or .tool-versions
4. Defaults to 3.4

Package Manager

Bundler. Detect Gemfile and Gemfile.lock.

Bundler Version

Read from BUNDLED WITH in Gemfile.lock. Install: gem install bundler -v <version>.

Install Commands

Runtime Variables

BUNDLE_GEMFILE=/app/Gemfile
GEM_PATH=/usr/local/bundle
GEM_HOME=/usr/local/bundle
MALLOC_ARENA_MAX=2

Build & Start

Start Command Resolution

1. Framework-specific (see below)
2. config/environment.rb → load and run
3. config.ru → Rack: bundle exec rackup config.ru
4. Rakefile → bundle exec rake <task>

Framework Detection

Rails-Specific

When config/application.rb is present:

• Asset precompile: bundle exec rake assets:precompile (Sprockets or Propshaft)
• API-only Rails (no asset pipeline gems) skip asset compilation
• Bootsnap: bundle exec bootsnap precompile --gemfile during deps; bundle exec bootsnap precompile app/ lib/ during build

System Dependencies

Asset Pipeline

Rails API-only (no sprockets-rails, propshaft) skip asset compilation.

Bootsnap

When bootsnap is in Gemfile:

• During deps: bundle exec bootsnap precompile --gemfile
• During build (Rails): bundle exec bootsnap precompile app/ lib/

Node.js Integration

If package.json detected, or execjs gem is used:

• Install Node.js
• Run npm install (or equivalent)
• Execute build scripts
• Prune dev dependencies

Common for Rails with Webpacker, Vite, or other frontend tooling.

Performance Optimizations

Install Stage Optimization

Copy Gemfile + Gemfile.lock first for layer caching.

Caching

RUN --mount=type=cache,target=/usr/local/bundle \
    bundle config set --local path /usr/local/bundle \
    && bundle install --frozen

Base Images

Dockerfile Patterns

Rails

FROM ruby:3.4-bookworm AS base

FROM base AS deps
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle config set --local path /usr/local/bundle \
    && bundle install --frozen

FROM base AS build
WORKDIR /app
COPY --from=deps /usr/local/bundle /usr/local/bundle
COPY . .
ENV RAILS_ENV=production
RUN bundle exec bootsnap precompile app/ lib/ \
    && bundle exec rake assets:precompile

FROM ruby:3.4-slim
WORKDIR /app
ENV RAILS_ENV=production
ENV BUNDLE_GEMFILE=/app/Gemfile
ENV GEM_HOME=/usr/local/bundle
ENV GEM_PATH=/usr/local/bundle
COPY --from=deps /usr/local/bundle /usr/local/bundle
COPY --from=build /app/public/assets /app/public/assets
COPY . .
EXPOSE 3000
CMD ["bundle", "exec", "puma", "-C", "config/puma.rb"]

Rack (config.ru)

FROM ruby:3.4-slim
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle config set --local path /usr/local/bundle \
    && bundle install --frozen
COPY . .
EXPOSE 9292
CMD ["bundle", "exec", "rackup", "config.ru", "-o", "0.0.0.0", "-p", "9292"]

Gotchas

• Bundler version mismatch is a top build failure — always install the exact version from BUNDLED WITH in Gemfile.lock
• Rails SECRET_KEY_BASE must be set even for asset precompilation — use a dummy value at build time: SECRET_KEY_BASE=dummy bundle exec rake assets:precompile
• bundle exec is required in Docker CMD — running puma directly may use a system gem instead of the bundled one
• jemalloc can reduce Rails memory usage 30-40% — LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 or install libjemalloc2
• Bootsnap precompilation caches must happen AFTER gems are installed — running bootsnap precompile --gemfile before bundle install will fail silently