The Rails Tech Debt Blog

Why To Use A Multi-Stage Dockerfile

2026-08-13T12:54:59-04:00

Docker has made it easy to use the same environment everywhere, from development to production. But the most basic Dockerfile, where all your dependencies are lumped together in one image, has hidden costs. In this article, we’ll learn the advantages of multi-stage Dockerfiles both from a security and a performance standpoint, primarily for production images.

What is a Multi-Stage Dockerfile?

You might have a Dockerfile in your application that looks something like this:

FROM ruby:3.2

WORKDIR /app

# Install system dependencies needed to compile native gems
RUN apt-get update && apt-get install -y \
    gcc \
    make \
    libpq-dev

# Install gems
COPY Gemfile Gemfile.lock ./
RUN bundle install

# Copy application code
COPY . .

EXPOSE 3000
CMD ["ruby", "app.rb"]

This is a typical single-stage setup. There’s one base image, for example, ruby:3.2, and everything your application needs gets installed inside it: the full Bundler toolchain, build utilities like gcc and make for compiling native gem extensions, and dev dependencies like RSpec or Pry, all living side by side. The appeal is obvious. It’s straightforward to write, easy to reason about, and gets the job done.

But that simplicity comes with a trade-off. For example, every tool you used to build your application is still sitting inside the image you ship to production even though you no longer need it there.

In contrast, a multi-stage Dockerfile introduces the idea of stages, discrete phases of your build process, each defined by its own FROM statement. Here’s what that looks like in practice:

Multiple FROM statements: each one starts a new stage with its own base image and its own filesystem. You might have a builder stage that installs compilers and build tools, and a separate production stage that only contains what your application needs to run.
Selective artifact copying stages can pull specific files from a previous stage using COPY --from=. This means your final image gets only the output of the build such as compiled code and static assets, and not the tools that produced it.

Here’s an example of what a multi-stage Dockerfile looks like in practice. This multi-stage Dockerfile is from the most recent version of Rails:

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

# This Dockerfile is designed for production, not development. Use with Kamal or build'n'run by hand:
# docker build -t rails_demo .
# docker run -d -p 80:80 -e RAILS_MASTER_KEY= --name rails_demo rails_demo

# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html

# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
ARG RUBY_VERSION=4.0.4
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

# Rails app lives here
WORKDIR /rails

# Install base packages
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips sqlite3 && \
    ln -s /usr/lib/$(uname -m)-linux-gnu/libjemalloc.so.2 /usr/local/lib/libjemalloc.so && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Set production environment variables and enable jemalloc for reduced memory usage and latency.
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development" \
    LD_PRELOAD="/usr/local/lib/libjemalloc.so"

# Throw-away build stage to reduce size of final image
FROM base AS build

# Install packages needed to build gems
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libvips libyaml-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Install application gems
COPY vendor/* ./vendor/
COPY Gemfile Gemfile.lock ./

RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    # -j 1 disable parallel compilation to avoid a QEMU bug: https://github.com/rails/bootsnap/issues/495
    bundle exec bootsnap precompile -j 1 --gemfile

# Copy application code
COPY . .

# Precompile bootsnap code for faster boot times.
# -j 1 disable parallel compilation to avoid a QEMU bug: https://github.com/rails/bootsnap/issues/495
RUN bundle exec bootsnap precompile -j 1 app/ lib/

# Precompiling assets for production without requiring secret RAILS_MASTER_KEY
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# Final stage for app image
FROM base

# Run and own only the runtime files as a non-root user for security
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash
USER 1000:1000

# Copy built artifacts: gems, application
COPY --chown=rails:rails --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --chown=rails:rails --from=build /rails /rails

# Entrypoint prepares the database.
ENTRYPOINT ["/rails/bin/docker-entrypoint"]

# Start server via Thruster by default, this can be overwritten at runtime
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]

Here’s what’s happening across the three stages:

base: this stage sets up the common foundation (slim Ruby image, shared env vars) that both other stages build on.
build: the throw-away stage. Installs build-essential, git, compiles gems, precompiles assets. None of these tools ship to production.
the unnamed third FROM base: this copies only the built artifacts from build and runs as a non-root user.

Why Use a Multi-Stage Dockerfile?

Now that we know what the differences are between a single-stage and multi-stage Dockerfile, let’s talk about why you might choose a multi-stage Dockerfile.

Two main advantages of multi-stage builds are performance and security:

Performance

Multi-stage builds usually have a smaller final image size since the build tools and dev dependencies don’t make it into the final image. Multi-stage builds also play nicely with Docker’s layer caching. Because each stage is isolated, Docker can cache them independently. If your dependencies haven’t changed, the builder stage can be skipped entirely on the next run. You only rebuild the stages that actually changed, which adds up to significant time savings over hundreds of pipeline runs. Smaller images and cached stages mean faster pulls, faster deployments, and less time waiting around in your CI/CD pipeline.

Security

A multi-stage build is more secure than a single-stage build because the production image contains only what’s needed to run the application, nothing more.

Every package installed in your image is a potential vulnerability. Build tools like gcc, make, and curl are common in single-stage images and they’re also common exploit vectors. With a multi-stage build, those tools never make it into your production image. Fewer packages means fewer CVEs to worry about, and a much smaller surface for attackers to target.

You can reduce this even further by pairing your final stage with a slim base image. For example, ruby:4.0-slim strips out packages that aren’t needed for most Ruby apps, and ruby:4.0-alpine goes even further, using Alpine Linux as its base, a minimal OS that keeps only the bare essentials by default.

Tips and Common Pitfalls

Skip multi-stage for development and test environments. The security and build-performance wins mostly matter for what you ship to production. In dev you’re rebuilding constantly and want to run commands like bundle install, rails console, or add a gem on the fly. A multi-stage setup adds friction for little payoff there, since your dev tools need to stay in the image anyway. Keep a single-stage Dockerfile (or a dedicated dev stage in the same file) for local development and testing, and reserve the multi-stage build for your production image.
Name your stages. Using AS builder and AS production in your FROM statements makes your Dockerfile much easier to read and maintain, especially as the number of stages grows.
Know what to copy. The most common stumbling block is figuring out exactly which files need to move between stages. For a Ruby app, that’s typically your installed gems directory and your application code. Take the time to map this out before you write the COPY --from lines.
Run as a non-root user in your final stage, like the Rails example above does. Even if an attacker gets into the container, they won’t have root access to work with.
Build cache ordering matters: Put the steps least likely to change at the top of each stage and most likely to change at the bottom. For example, copy your Gemfile and run bundle install before copying your application code. That way, if you change a Ruby file, Docker doesn’t re-run bundle install unnecessarily.
Match your base images when going slim or Alpine. If your final stage switches to a musl-based image like ruby:4.0-alpine, but your builder stage compiled native gem extensions on a glibc-based image like ruby:4.0 or ruby:4.0-slim, those extensions may fail at runtime. Either build and run on matching bases, or compile your gems inside an Alpine builder stage.
Forgetting build dependencies at runtime. A very common mistake is copying your compiled gems into the final stage but forgetting to install the runtime system libraries they depend on. For example, the pg gem needs libpq5 at runtime even though it only needs libpq-dev to compile. Your app will build fine but crash at runtime. This is probably the most common real-world gotcha with multi-stage builds.
Secret leakage between stages. People sometimes assume that because secrets (API keys, credentials) used in the build stage don’t get copied to the final stage, they’re safe. But they can still be exposed in the image’s layer history. Use Docker BuildKit secrets instead:
```
RUN --mount=type=secret,id=my_secret ...
```
If you want to go even further than slim images, look into distroless images. These images contain absolutely nothing except your app and its runtime- no shell, no package manager, nothing. They represent the ultimate reduction in attack surface. Just be aware that Ruby support for distroless is still limited compared to languages like Go or Java, so do your research before committing to it for a Ruby project.

Conclusion

Multi-stage Dockerfiles require slightly more work upfront. But in return, you get images that are dramatically smaller, meaningfully more secure, and faster to build. That’s a trade-off worth making for any production workload.

Want to convert your single-stage Dockerfiles to multi-stage? We can help!

Measuring Test Code Coverage For Non-Ruby Runners

2026-08-10T15:51:50-04:00

When we think about Ruby code coverage, our go-to gem for this is SimpleCov, which works great when the test suite uses Minitest, RSpec, Cucumber, Capybara, and all these tools that are integrated with Ruby and Rails. But many applications also use other tools like Playwright or Cypress to run e2e tests, and we can’t use SimpleCov the same way.

Most of the time, what we have seen is that the Ruby code executed when running these tools ends up left behind and not being counted for the total code coverage, even though we know the code is actually being tested.

Sample Application

To make it easier to try this, we created a sample application that uses the cypress-on-rails gem along with Minitest, and includes the instructions and custom Rake tasks to get the final code coverage when running both test suites.

Note that this could be done with any other tool like Playwright or Protractor (deprecated) since the actual integration is independent of the tool as long as it runs the Rails server.

Approach Summary

The main problem that we are facing when using these external tools is that the Rails server is controlled by this runner and not started by a Ruby runner, so we can’t easily control the lifecycle of the server to measure and extract the coverage information.

We can see how the cypress-on-rails gem already overcomes some of these limitations with custom helpers to execute fixtures, factories, and db cleanup in their generated sample tests.

We have a few moving pieces here, so this is a quick summary of the process:

when we run rails test we get the code coverage of the Minitest test suite
then we’ll run Coverband’s standalone server on the side, so it collects stats from the Rails servers started by Cypress
once the e2e tests are done (running rails cypress:run), we can use a custom Rake task to extract the code coverage from Coverband into a JSON file
finally, we can merge the code coverage of the 2 tools into a single final report

The Details

Minitest Code Coverage

This step is the standard SimpleCov setup: we only need to add the SimpleCov gem in the :test group, and enable SimpleCov at the beginning of our test_helper.rb file.

After this we can do a quick test, run rails test and see the generated report:

We can see the total coverage is around 35%, and we can see the details of the UsersController coverage that we’ll use for this example too:

Note the total coverage of this file is around 39%, with many lines not covered (lines 15, 24, and 26). This is expected, as we are only testing the index action in our Minitest suite.

But we know we have more tests for this file; the Cypress test suite is testing an invalid form submission of the new user form.

Coverband Standalone Server

As mentioned above, we can’t simply add SimpleCov to the Cypress tests, so we are going to use Coverband (which uses SimpleCov internally) to capture the code that is being executed by the tests, similar to what we would do if running Coverband in production.

Coverband provides a standalone server that we can use so we can control the lifecycle of the code coverage tracking independently of the lifecycle of the Cypress runner.

First we have to add the coverband gem (note that we are adding it only in the test group, we are not using it to track production coverage!). Then, we can execute the server with RAILS_ENV=test rails coverband:coverage_server and leave it running on the side.

Note that, now that Coverband is added, we get an error message at the end of the Minitest run. Ideally, we could use a different Rails environment for the e2e tests so the gem wouldn’t be loaded, but the cypress-on-rails gem hardcodes the test Rails environment.

E, [2026-01-02T16:29:34.221521 #322239] ERROR -- : coverage failed to store
E, [2026-01-02T16:29:34.221579 #322239] ERROR -- : Coverband Error: # coverage measurement is not enabled

Running Cypress Tests

Now it’s time to run the e2e tests. In this example we run rails cypress:run, but it would be the same for any other tool, as long as we set the same RAILS_ENV variable as the Coverband server (so the gem is required).

When the tests finish, we won’t see any information about the code coverage, but we can open the Coverband server in the browser to check how the percentage is being tracked in http://localhost:9022.

It’s important to note that Coverband will calculate all the coverage of any code that gets executed (even for Ruby files we don’t really care about when looking at the final code coverage value) and we get some information like coverage of config files or test files that will affect the coverage percentage. With SimpleCov, we use the 'rails' profile to ignore those extra files, but we don’t need to worry about it at this point for Coverband. We’ll clean that up at the end.

Extracting the Code Coverage from Coverband

Coverband provides a coverband:coverage_html task that uses SimpleCov to process the internal coverage data. There’s also a coverband:coverage_json but these tasks don’t generate the raw data we need to merge it with the Minitest resultset. To solve this, we created a custom Rake task that will extract the raw data and format the JSON file to have a structure that we can then merge.

# https://github.com/fastruby/coverage-with-cypress-sample-app/blob/main/lib/tasks/json_coverage.rake#L2

desc "JSON formatted report of Coverband code coverage"
task :simplecov_json_report do
  require "coverband"
  require "coverband/utils/result"
  require "coverband/utils/file_list"
  require "coverband/utils/source_file"
  require "coverband/utils/lines_classifier"
  require "coverband/utils/results"

  require "simplecov"
  require "simplecov_json_formatter"

  `mkdir -p #{SimpleCov.coverage_path}`

  # SimpleCov hardcodes this constant as `coverage.json`, we are renaming this here to make it more
  # clear, but this step is not necessary
  SimpleCovJSONFormatter::ResultExporter.send(:remove_const, "FILENAME")
  SimpleCovJSONFormatter::ResultExporter::FILENAME = "cypress_coverage.json"

  coverband_reports = Coverband::Reporters::Base.report(Coverband.configuration.store)
  Coverband::Reporters::Base.fix_reports(coverband_reports)
  result = Coverband::Utils::Results.new(coverband_reports)
  SimpleCov::Formatter::JSONFormatter.new.format(result)

  # fix json structure so it can be merged with coverage:merge
  # we want a `"Cypress"` key at the root of the JSON object, with the `"coverage"` inside it
  generated_json_file = File.join(SimpleCov.coverage_path, SimpleCovJSONFormatter::ResultExporter::FILENAME)
  content = { "Cypress" => JSON.parse(File.read(generated_json_file)) }
  File.write(generated_json_file, content.to_json)
end

Now we can run rails simplecov_json_report to generate the coverage/cypress_coverage.json file.

Note that this step will show a really high code coverage percentage, over 75%, but this is not correct since it includes config, test, and other files for this calculation!

Merging Results

Now we get to the final step: we have the coverage/.resultset.json and coverage/cypress_coverage.json files that we need to merge into a single file.

For this, we have created another custom Rake task that uses SimpleCov’s collate method:

# https://github.com/fastruby/coverage-with-cypress-sample-app/blob/main/lib/tasks/json_coverage.rake#L34

namespace :coverage do
  desc "Merge Minitest's and Cypress' code coverage json files into one"
  task :merge do
    require "simplecov"

    # change this if you use different json result names
    coverage_files = Dir["#{SimpleCov.coverage_path}/.resultset.json"] + Dir["#{SimpleCov.coverage_path}/cypress_coverage.json"]

    # make sure to use the `rails` profile to not add noise with files we won't test
    SimpleCov.collate coverage_files, "rails"
  end
end

And we can run this task with rails coverage:merge and see the new generated code coverage report:

Here we can see the total percentage went up to almost 53%.

And here we can see the UsersController coverage is over 60% and we can see the lines inside the new and create actions are now green as we expected from the Cypress test.

Conclusion

This is a basic example of the approach; in a real production application it may require some tweaks depending on the tool being used, along with the proper setup for CI and proper automation of the extraction and merging of the coverage data.

A similar problem happens when we want to measure the JavaScript/TypeScript code coverage and we are using a Ruby runner like Capybara along with runners like Jest or Cypress. You can read about capturing all the code coverage and merge results together in this article: JavaScript Test Code Coverage in Rails.

Do you need help with your tests? Let’s talk!

Opening a Repo Is Now an Execution Event

2026-08-06T10:32:40-04:00

If you work on Rails for a living, you clone repositories you didn’t write all week long: a gem you’re debugging, a client’s application you’re about to audit, a bug reproduction attached to an issue. For years, opening one of those in your editor was the safe part. You were reading someone else’s code, not running it, and the only real rule was to not run anything until you had looked.

That rule quietly stopped being enough. AI coding editors like Claude Code and Cursor read project-local configuration the moment you open a repository, and some of that configuration is executable. A repo you cloned five seconds ago can hand your editor a command to run before you have read a line of it, and this is not hypothetical: the npm worm that hit keyv this week (Socket, Aikido, and Microsoft all covered it) weaponized exactly this, writing itself into .claude/settings.json so it runs again for anyone who opens the project.

In this post, we’ll look at why opening a repository in an AI editor is now an execution event, how the keyv worm turned that into a live attack, and what to check in a cloned repo’s .claude/ and .vscode/ directories before you point your editor at it.

Why opening a repo now executes code

For years the mental model was simple: untrusted code runs when you tell it to. You install a package and its install scripts run, you run the app and its code runs, but opening a repository to read it was passive. Looking wasn’t doing.

AI editors break that model by design. Claude Code reads .claude/settings.json on every session start, and one of the things that file can configure is a SessionStart hook, a shell command that runs when the session begins, with no separate step asking you to approve it first. A .claude/ directory you didn’t create can hand your session a command just as easily as one you built yourself.

Cursor and VS Code have the same shape with more friction: a task in .vscode/tasks.json can be set to run on folder open, though only in a workspace you have trusted and only once you have opted into automatic tasks. Either way, the config is meant to be read and acted on the moment the project opens, which is exactly what makes it useful to someone who has slipped it into a repo you are about to clone.

A configuration-injection bug in marimo, a Python notebook tool (CVE-2026-67618), surfaced the same week and leaked API keys the moment you opened a crafted notebook, a different mechanism with the same shape. Two unrelated tools hitting the same problem in the same week is a sign this is a shift in how tools treat project-local config, not an npm or a Rails quirk. The common thread is that the more a tool reads and acts on configuration shipped inside a project, the more of its behavior a repo you didn’t write controls the moment you open it.

Already weaponized: the keyv worm

The keyv worm shows this is not a theoretical risk. The npm package keyv, along with a few hundred others, was compromised on August 4th, 2026, in a self-propagating worm variously called ChainDrop or “Shai-Hulud: Here We Go Again”. The credential-stealing half of it is ordinary: an install script harvests tokens and keys from the filesystem and ships them out to the attacker. The half that matters here is how it sticks around. As Socket noted, listing it among techniques “not documented in earlier Shai-Hulud reporting,” the payload writes a SessionStart hook into .claude/settings.json and a folderOpen task into .vscode/tasks.json.

Those files are never touched by npm install. The next time you or a teammate opens the project, they are read by your editor, which means the infection outlives the dependency. You can pull the compromised package out of your lockfile and the hook waiting in .claude/ is still there, ready to run the next time someone opens the repo in Claude Code. That is the difference between “we shipped a bad dependency” and “everyone who opens this repo runs the payload,” and it is why cleaning up after this worm is not just a lockfile edit.

Why your usual instincts miss it

None of the usual reflexes catch this. “Don’t run code you haven’t read” and “only install signed, attested packages” are both good habits, and both miss the point here, because the dangerous part isn’t something you run or install at all. The hook rides in the repository’s own files. Provenance, a signed record tying a package back to the exact source commit and CI build that produced it, tells you which pipeline published a dependency; it says nothing about a .claude/settings.json committed straight into a repo you cloned. Ruby has its own take on verifying the packages you install, the gem signing and --trust-policy we looked at in The Forgotten Flag: How –trust-policy Works, and it shares the same blind spot: signing covers the artifacts you install, not the config you open.

Why this lands on Rails teams

This started as an npm story, but the exposure isn’t really about your dependencies. If your Rails app has a Node asset pipeline it is worth keeping an eye on your lockfile, and keeping Gemfile.lock honest matters too (we have written before about supply-chain risk in your Gemfile and about how patching a gem isn’t always the whole fix). But a gem or npm dependency audit looks at what you install. The .claude/ and .vscode/ vector is about what you open, and opening repositories you didn’t write is something Rails teams do constantly.

Consultancies live this at the extreme: at FastRuby.io we open other people’s Rails codebases for a living, cloning client applications to audit and upgrade them, more often than not with an AI editor already running. Every one of those repositories is, by definition, one we did not write, and any of them could ship a .claude/settings.json that runs the moment the session starts. A dependency audit answers “did I install something bad?” but it has nothing to say about the question that actually applies here: whose repo did I just open in Claude Code?

What to check before you open a repo

So before you open a freshly cloned repository in Claude Code, Cursor, or VS Code, especially one from outside your team, spend a minute on the config it ships with (the kind of check worth eventually baking into a Claude Code skill so you are not relying on memory):

Open .claude/settings.json and look for a hooks key, particularly a SessionStart hook. A legitimate hook is one your own team added on purpose; anything you don’t recognize is worth reading in full, because it runs on session start whether or not you asked.
Open .vscode/tasks.json and look for a task set to run on folder open, and read exactly what its command does.
If the repo has a JavaScript pipeline, check whether your lockfile resolves keyv, flat-cache, file-entry-cache, or cacheable to one of the poisoned releases (keyv@6.0.0, flat-cache@6.1.24, file-entry-cache@11.1.6, cacheable@2.5.1) rather than to the older, clean lines. yarn why keyv or npm ls keyv shows what actually resolved.

If any of that turns up something you didn’t put there, deleting the file isn’t the end of it. Assume the command already ran, and rotate every credential the machine or CI run could have reached since you opened the repo, from a separate, uncompromised machine. A hook you remove after the fact doesn’t recall whatever it already sent out.

Conclusion

Opening a repository in your editor used to be the safe step, the thing you did precisely because you weren’t ready to run anything yet. AI editors changed that: Claude Code and Cursor read project-local config on open and can act on it, so cloning a repo you didn’t write and pointing an AI editor at it is an execution event in its own right. The keyv worm is the first widely seen case of someone weaponizing that, and it will not be the last.

For Rails teams, and especially for anyone who clones client code for a living, the habit worth building is a small one: before you open an unfamiliar repo in an AI editor, look at its .claude/ and .vscode/ directories the same way you would look at a shell script someone emailed you. A few minutes there is a lot cheaper than rotating every credential on the box afterward.

Wondering what is hiding in the .claude/ or .vscode/ config of the repos your team has been cloning, or want a second set of eyes on a codebase before you trust it? Send us a message!

Why Your Yarn App Suddenly Looks for Bun

2026-08-06T09:38:52-04:00

You run bundle update, kick off a build, and asset precompilation stops on this:”

cssbundling-rails: Command install failed, ensure bun is installed
Tasks: TOP => assets:precompile => css:build => css:install

Except your application uses Yarn. It has always used Yarn. Nothing in the project references Bun, and nobody on the team added it.

This is not an exotic edge case. It can happen to ordinary Yarn applications, and it lingers because the fix has been merged upstream but never released. In this post, we’ll walk through why cssbundling-rails misidentifies your package manager, and how to unblock your build.

The Short Version

cssbundling-rails 1.4.3 added yarn.lock to the list of lockfiles that mark a project as a Bun project. While preparing to install JavaScript dependencies, cssbundling-rails determines that Bun should be used when the Bun binary exists in the PATH. The issue explored in this post occurs when two things are true at once: the project contains a yarn.lock file and the build environment happens to have Bun installed.

When both are true, the gem runs bun install against a project that has never used Bun. If that command fails, the rake task reports ensure bun is installed even though Bun is installed, because the message is assembled from the name of the command it just tried to run.

The fix is PR #172, commit 466cd57, merged to main in July 2025. As of August 2026 it is still not in a released version, and 1.4.3 remains the latest gem. So the workaround is to pin to the commit rather than to a version:

gem "cssbundling-rails", github: "rails/cssbundling-rails", ref: "466cd57"

You are likely to hit this if all of the following are true:

You use cssbundling-rails with Yarn, and yarn.lock is committed.
Your resolved version is 1.4.3. It is currently the latest release, so bundle update lands you there by default.
Bun is reachable on PATH wherever you run assets:precompile, whether that is a Docker build, CI, or a PaaS build step. This is easier to hit than it sounds: Render’s images ship Bun by default, plenty of custom base images install it alongside Node, and so does any developer who has ever tried Bun locally.

Note that your project does not need to use Bun in any way, and you do not need both a yarn.lock and a bun.lock. An ordinary Yarn application is enough, as long as the Bun binary happens to be sitting in the environment that runs the build.

How We Ran Into It

We hit this while moving a Rails application onto a newer Ruby base image. It had used Yarn for years. Bun had never entered the picture.

Everything built cleanly until assets:precompile, which stopped on ensure bun is installed. Our first assumption was that some dependency had quietly started pulling Bun in, so we went looking through package.json and the lockfile. Neither pointed to Bun. The gem had not failed to run a command; it had decided on its own to run the wrong one.

The answer was in a shared base image. A little above the Ruby setup, it installed Bun, so it would be available to other projects using it, and put it on the path:

RUN curl -fsSL https://bun.com/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

Our project did not need Bun, but every build now ran with Bun in PATH. Those two lines (above) are what turned a quirk in a gem’s detection logic into a failed build.

That reframed the investigation. The question was not “why is Bun broken”, it was “why is a Yarn application attempting to use Bun?”

What’s Actually Happening

The task graph in the error message is the first clue:

assets:precompile => css:build => css:install

cssbundling-rails hooks into assets:precompile and runs css:build, which depends on css:install, which shells out to a package manager to install your JavaScript dependencies. The gem picks that package manager automatically, based on which lockfiles it finds in the project.

For the precompile path, that decision lives in Cssbundling::Tasks, in lib/tasks/cssbundling/build.rake. The relevant parts of version 1.4.3 looks like this:

LOCK_FILES = {
  bun: %w[bun.lockb bun.lock yarn.lock],
  yarn: %w[yarn.lock],
  pnpm: %w[pnpm-lock.yaml],
  npm: %w[package-lock.json]
}

def install_command
  case
  when using_tool?(:bun) then "bun install"
  when using_tool?(:yarn) then "yarn install"
  when using_tool?(:pnpm) then "pnpm install"
  when using_tool?(:npm) then "npm install"
  else raise "cssbundling-rails: No suitable tool found for installing JavaScript dependencies"
  end
end

def tool_exists?(tool)
  system "command -v #{tool} > /dev/null"
end

def using_tool?(tool)
  tool_exists?(tool) && LOCK_FILES[tool].any? { |file| File.exist?(file) }
end

Two details: yarn.lock sits in the Bun list, so every Yarn project matches the Bun branch. And using_tool? joins both checks with &&, so the Bun match only wins when tool_exists? actually finds the bun binary. With Bun absent, the check falls through to Yarn and everything works, which is why this bug stays invisible on a plain ruby:* image. With Bun present, install_command returns bun install for a project that has never used Bun.

From there the misclassification lands in one of two ways. If bun install succeeds, it quietly writes a bun.lock into the repository alongside your yarn.lock, which is what most of the upstream reports describe. If it fails, the css:install task raises:

task :install do
  command = Cssbundling::Tasks.install_command
  unless system(command)
    raise "cssbundling-rails: Command install failed, ensure #{command.split.first} is installed"
  end
end

That is the message we saw, and it is built from command.split.first. It points you at Bun as the problem, when Bun was never part of the application to begin with.

Where the Regression Came From

The git history explains how a change meant to help Bun users introduced a bug that impacted Yarn users.

PR #165, “Improve package manager detection for Bun 1.2 compatibility”, was merged in March 2025 and shipped in 1.4.3. Bun 1.2 made a new text-based bun.lock the default lockfile in place of the older binary bun.lockb, and bun install --yarn produces a yarn.lock. To cover those cases, the PR broadened Bun detection to accept bun.lockb, bun.lock, or yarn.lock.

That last option is the problem. Every Yarn project has a yarn.lock, so detection meant for a narrow Bun workflow started capturing ordinary Yarn projects too, on any machine where Bun was installed.

PR #172, “Remove yarn from bun detect tool”, commit 466cd57, was merged in July 2025 to correct it. It stops treating yarn.lock as a Bun signal, so a Yarn project is detected as Yarn again.

It is worth knowing that this was not a simple typo. Issue #183 is still open and asks for the opposite behavior: Bun preferred for freshly generated applications. The same few lines are being pulled in two directions, and there is no clear consensus upstream on how it should behave.

Merged Is Not Yet Released

Unfortunately the usual “just bump the version” instinct does not work in this case. The latest released gem is 1.4.3, tagged March 3, 2025. The fix, 466cd57, was merged to main on July 10, 2025, but not yet released. The only way to get the fix today is to point Bundler at the commit itself:

# cssbundling-rails 1.4.3 misdetects bun for yarn projects (regression from
# PR #165). The fix is PR #172 / 466cd57, merged to main but unreleased as of
# August 2026. Unpin only once a release LATER than 1.4.3 ships with that commit.
gem "cssbundling-rails", github: "rails/cssbundling-rails", ref: "466cd57"

As a side note, when you pin a gem to a commit, it is a good idea to add a comment that describes the condition that makes it safe to remove. In this case, once a release later than 1.4.3 ships with commit 466cd57. A comment like ‘unpin after v1.4.3’ is easy to misread and does not explain why the dependency was pinned in the first place.

Now we can bundle install, and confirm that the Gemfile.lock records a GIT source pointing at the commit:

GIT
  remote: https://github.com/rails/cssbundling-rails.git
  revision: 466cd57...
  specs:
    cssbundling-rails (1.4.3)

Rebuild, and precompilation detects Yarn again. That one-line pin unblocked the applications that still needed a CSS build.

Conclusion

The alarming ensure bun is installed message is not about Bun at all, it is an ordinary Yarn application tripping over a detection change in cssbundling-rails 1.4.3, in an environment that happened to have Bun lying around. The fix exists upstream, it is simply stuck there, so a commit pin is the pragmatic move until a new version ships. A shared base image is a dependency too, so check it when a build breaks over something your code never asked for.

Snags like this one slowing down your Rails upgrade? We can help.

Running a Ruby MCP Server in Production

2026-08-04T07:58:08-04:00

In a previous post, AI Assistant for Our Blog Writing Process, I introduced the assistant we built to help with our blog writing. At the core of that assistant is an MCP server, which serves as the source of truth for both of our blogs. It exposes that knowledge through tools the client can call and documentation the client can read.

Getting an MCP server running is the easy part. Every quickstart, in every language, gives you a server that runs as a subprocess on your own machine and disappears when the client exits. That’s enough to experiment locally, but it’s a long way from something a team can rely on. Once you want to deploy it, questions about where it runs, state management, authentication, and security become your responsibility. The Ruby SDK’s defaults don’t solve most of those problems, and one of them even comes with a published security advisory.

In this article, we’ll cover what changes when a Ruby MCP server stops being a subprocess: the two shapes it can take in a Rails shop, why session state breaks down when running behind multiple Puma workers, the DNS rebinding vulnerability the transport shipped with, and what the specification asks of you once a shared token is no longer enough.

From subprocess to service

MCP defines two transports. With stdio, the client launches your server as a subprocess and talks to it over standard input and output. It is the fastest way to see something working, but it puts a copy of the server on every machine that uses it. Everybody needs the code and credentials for the database, and every change means everybody pulls. Our marketing team uses these tools too, and “clone this repository and check your Ruby version” is not a reasonable thing to ask of them.

Streamable HTTP puts the server in one place instead. Everyone points a client at a URL, and an update is a deploy rather than an announcement.

One nice thing about the Ruby implementation is that the transport is just a Rack application, so everything else is familiar:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(BlogServer.build)
mcp_token = ENV.fetch("MCP_AUTH_TOKEN")

app = Rack::Builder.new do
  map "/mcp" do
    use Auth::BearerToken, token: mcp_token
    run transport
  end

  map "/up" do
    run ->(_env) { [200, { "content-type" => "text/plain" }, ["ok"]] }
  end
end.to_app

run app

BlogServer.build is our own factory, a method that returns a fresh MCP::Server with our tools and resources already registered. The transport wraps that server, the token comes from the environment, and everything below those two lines is just Rack.

Nothing in this file knows it is serving MCP, which is exactly what we want. It means everything we already know about running Rack applications still applies.

Two shapes for a server

Once it is a service, there are two places it can live, and the choice has more consequences than it first appears.

Ours is standalone, because the data it serves lives in its own database, filled by a pipeline that reads both blog repositories. The server is a read-only layer over that, so it has no reason to be part of anything else, and a config.ru with Puma in front of it is the whole deployment.

The other shape is an MCP endpoint inside an application you already run, which is the more common case for a Rails team wanting to expose what their app already knows. The SDK supports two ways of doing it. The first mounts the transport in your routes, wrapping a server you have already built elsewhere:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)

Rails.application.routes.draw do
  mount transport => "/mcp"
end

That builds one server when the process boots, and every caller gets the same one. The second builds a server per request, in a controller:

class McpController < ActionController::API
  def create
    server = MCP::Server.new(
      name: "my_server",
      version: "1.0.0",
      tools: [SomeTool, AnotherTool],
      server_context: { user_id: current_user.id },
    )
    transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
    status, headers, body = transport.handle_request(request)

    render(json: body.first, status: status, headers: headers)
  end
end

That is more work per request, but it has a benefit you cannot get from the mounted version: current_user is in scope. The tool list can differ by caller, and server_context carries identity down into the tools themselves, which is what per-customer scoping is built on. If the server will ever answer to more than one account, this is the shape to start from, because retrofitting identity into a server built at boot means rebuilding it.

Living inside the Rails app buys two more things. You inherit whatever authentication is already there, and your tools read the same models as the rest of the application, so there is no second connection to configure and no schema drift between two codebases. What you give up is isolation: MCP traffic now shares workers and a deploy cycle with everything else the app does.

Sessions, and the trap in the Ruby SDK

Here is the part that makes this interesting: StreamableHTTPTransport stores session and SSE stream state in memory. The SDK’s own documentation is blunt about the consequence: it must run in a single process. Puma with workers > 0, or Unicorn, forks processes that do not share memory, and session management and open SSE connections break. Behind a load balancer, you need sticky sessions so that a client’s requests keep landing on the instance that remembers it.

The escape hatch is stateless: true, which drops the session requirement and works with any process configuration. It is what we pass, along with a Puma config that defaults to no workers anyway:

max_threads = ENV.fetch("MCP_MAX_THREADS", 5).to_i
threads max_threads, max_threads

workers_count = ENV.fetch("WEB_CONCURRENCY", 0).to_i
workers workers_count

if workers_count.positive?
  preload_app!

  on_worker_boot do
    ActiveRecord::Base.establish_connection(ENV.fetch("DATABASE_URL")) if defined?(ActiveRecord::Base)
  end
end

Threads by default, workers only if someone deliberately asks for them, and if they do, the Active Record connection gets re-established after the fork rather than inherited.

This whole area got simpler the day before this post went out. The 2026-07-28 specification removes protocol-level sessions and the Mcp-Session-Id header entirely, along with the initialize handshake. Any request can now land on any instance, which means the sticky routing and shared session stores that horizontal deployments used to need are no longer part of the picture. So stateless: true has stopped being a workaround and turned into a description of how the transport is supposed to behave. The single-process constraint above is only yours to worry about while you are on a gem release that still implements sessions, which is the first thing to check before planning a deployment around any of it.

Host and Origin are not optional

Earlier this month, the mcp gem got a security advisory, GHSA-rjr6-rcgv-9m7m, covering every version before 0.23.0. The Streamable HTTP transport processed every incoming JSON-RPC request without ever inspecting the HTTP Host or Origin headers.

That sounds mild until you think about where MCP servers actually run. A malicious page could use DNS rebinding to point its own hostname at 127.0.0.1 and then talk to an MCP server running on the visitor’s machine, invoking its tools and reading whatever they return. For a server with filesystem or credential access, that is sensitive data disclosure and, depending on the tool set, local action execution.

Version 0.23.0 added allowed_hosts and allowed_origins, and they are the reason those parameters appear in our transport:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(
  BlogServer.build,
  stateless: true,
  enable_json_response: !ENV["MCP_SSE_RESPONSES"],
  allowed_hosts: allowed_hosts,
  allowed_origins: allowed_origins
)

An empty allowlist is not a safe default. On a current gem it means every request comes back with a 403, and on anything older than 0.23.0 it meant no check happened at all, so the two ways to get this wrong are a server nobody can reach and a server anybody can. Both look like a healthy process from the outside, so the file refuses to start rather than guess:

allowed_hosts = ENV.fetch("MCP_ALLOWED_HOSTS", "").split(",").map(&:strip).reject(&:empty?)

if allowed_hosts.empty? && ENV["RACK_ENV"] == "production"
  raise "MCP_ALLOWED_HOSTS is unset. Set it to this deployment's host name " \
        "(e.g. blog-mcp-rb.herokuapp.com) or every request will be rejected with a 403."
end

The same file does the same thing for a missing authentication token. Refusing to boot is an unfashionable pattern, but the alternative is a deployment that comes up green and is either open to the internet or broken for everyone, and neither is a state you want to learn about from a client. Noticing that you are on a vulnerable version in the first place is a separate concern, and bundler-audit is the tool for it. We covered it along with the rest of what we run in 4 Essential Security Tools for Rails Apps, and a young gem moving quickly is exactly the case it earns its keep on.

From a shared token to OAuth

Ours is an internal tool, so authentication is a shared bearer token checked by a Rack middleware:

def authorized?(env)
  scheme, value = env["HTTP_AUTHORIZATION"].to_s.split(" ", 2)
  return false unless scheme&.downcase == "bearer" && value

  Rack::Utils.secure_compare(value, @token)
end

Anything that fails gets a 401 with a WWW-Authenticate header, and nothing downstream runs. Rack::Utils.secure_compare rather than ==, because a plain string comparison returns as soon as two characters differ, which leaks how much of the token a caller got right. That is a floor. A shared token cannot tell one caller from another, cannot be scoped to part of the data, and cannot be revoked for one person without rotating it for everybody. The moment the server has users outside the team, or needs to know which of them is asking, you need OAuth.

That prospect sounds heavier than it is, because two separate questions tend to get run together. The first is what your server owes as an OAuth 2.1 resource server, and that part is yours no matter what. The second is who issues the tokens, and there the answer is usually somebody else: an identity provider you already pay for, a dedicated auth service, or your own application if it already does this. Your server does not issue tokens and does not run a login flow. What it owes is discovery and validation:

Four requirements are worth reading closely, because they are all on your side of the line. You MUST implement Protected Resource Metadata (RFC 9728), which is a JSON document naming the authorization servers that can issue tokens for you. Your 401 has to point at it:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="posts:read"

You MUST validate that an access token was issued specifically for you as the intended audience, per RFC 8707, and reject anything else. A token that is valid, unexpired, and meant for a different service is not a token you may accept, and this is the requirement most likely to be skipped by someone who has previously written “verify the JWT signature” and stopped there. When a token is valid but its scopes are not enough, the server should answer with a 403 carrying error="insufficient_scope" and the scopes the operation actually needs, so the client can ask for them rather than guess.

The client’s side of that diagram, the PKCE parameters and the redirect dance, is the client’s problem, and the ecosystem largely handles it.

Which leaves the question of who plays the authorization server, and the specification is deliberately quiet about it: any OAuth 2.1 provider will do, so Okta, Entra, Auth0, Keycloak and friends are all fair game, as is Doorkeeper in your own Rails app if it is already an OAuth provider. That is the reassuring part. The part worth checking before you commit is that “our users can already sign in with it” is not the same question. Signing people in is authentication of humans. What an MCP client needs is an authorization server that can issue an access token scoped to your server, which is a shorter list of capabilities than most provider comparison pages lead with:

It publishes discovery metadata, either RFC 8414 or OpenID Connect Discovery, since clients are required to find its endpoints that way.
A client can obtain a client ID, whether through Client ID Metadata Documents (what the specification now prefers), Dynamic Client Registration (allowed, and deprecated), or plain pre-registration by an administrator.
It honors the resource parameter, so the token it issues is bound to your server as the audience rather than being a general-purpose token for the whole provider.

Not every provider does all three, and the one that catches people is registration. If yours has no dynamic registration, the fallback the specification allows is pre-registering each client out of band, which is fine for a handful of known clients and painful past that. It is worth knowing which of these you have before the auth decision is made for you by whatever is already in the app.

The SDK will not do any of this for you. It has no authentication story at all, which is the right call for a transport, and it means the work lands in Rack middleware or a before_action, both of which you have written before.

Limiting what a caller can reach

Authentication answers who is calling. What they can reach is a separate question, and a tool’s blast radius is whatever its query can touch.

Our server only reads, and every model says so:

class Post < ActiveRecord::Base
  self.table_name = "posts"

  belongs_to :source
  belongs_to :category
  has_one :content, class_name: "PostContent", foreign_key: :post_id

  def readonly? = true
end

That is one line per model, and it is a guard against the common case, an accidental save or update reached from a tool that was only ever meant to read. It is not a hard guarantee: update_all, delete_all, and raw SQL all skip the instance-level check entirely. What sits on the other end of the connection is a model with a set of tools, and the boundary between answering questions about the data and changing it deserves more than a single override, a database user with no write grants being the actual floor.

For a server with more than one customer, the same principle applies to rows rather than to writes, and server_context is how identity gets there. A tool receives it as a keyword argument, which means scoping is a where clause like any other:

def self.call(query:, server_context:)
  posts = Post.where(account_id: server_context.fetch(:account_id))
  # ...
end

fetch rather than [] on purpose. If the context is ever missing an account, that should raise rather than quietly return a relation scoped to nil. The rule underneath is: never ask a description to enforce something a query can enforce. A model that is told to only look at one account will usually comply, but usually is not a security control.

Testing

Start with the cheapest question there is, which is whether the MCP server is running at all:

curl http://127.0.0.1:9292/up

That is the health endpoint from the Rack file, and it answers without going anywhere near the transport, so a failure there is Puma or boot configuration rather than anything to do with MCP.

For the protocol itself, the MCP Inspector connects the way a client would. It is a Node tool, so testing a Ruby server means having npx around. It has a browser UI, and it also has a CLI mode which takes the same arguments a client would use, prints the JSON-RPC result, and can go in a script. Listing the tools over HTTP, with the token:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:9292/mcp \
  --transport http --header "Authorization: Bearer $MCP_AUTH_TOKEN" \
  --method tools/list

Reading one of our own resource URIs, which exercises a different path through the server:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:9292/mcp \
  --transport http --header "Authorization: Bearer $MCP_AUTH_TOKEN" \
  --method resources/read --uri "blog://fastruby.io/style-guide"

Those two are worth running every time you change something. tools/list is the only place you see your tool descriptions and input schemas the way a client actually receives them, which is a different experience from reading them in the source, and it will show you an enum that quietly became a string or an optional parameter that became required. resources/read goes through the read handler and, for us, the files on disk, which is where a bad path or a bad encoding turns up. Both commands also test the middleware, because they are going through it. Run either one with the token changed by a character and you should get a 401 rather than a result, on the real path, with no mocking involved.

Locally, the stdio entry point is still the fastest thing to point the Inspector at, since it needs no server running at all:

npx @modelcontextprotocol/inspector bundle exec ruby server.rb

One warning about debugging any of this. When something goes wrong inside a handler, what comes back is “Internal error” and nothing else, and the detail is on stderr.

Conclusion

In this article, we went through what a Ruby MCP server needs once it stops being a subprocess: Streamable HTTP instead of stdio, a choice between a standalone service and an endpoint inside an existing Rails app, statelessness so it survives more than one Puma worker, Host and Origin validation that a security advisory made mandatory, a shared token as the internal floor with OAuth as the answer beyond it, and read-only models and server_context deciding what any caller can actually reach.

Almost none of that is protocol code. It is Rack, Puma, OAuth, and being careful about what your tools can touch, which is to say it is the work you already know how to do. The MCP-specific part is small, and the parts most likely to hurt you are the ones that look like configuration.

Two caveats worth carrying. The gem is young and its API has moved between releases, so pin it and re-read the changelog rather than trusting a snippet you found, including these. And the specification itself moved this week, so anything written about sessions before the 2026-07-28 revision is now describing a protocol that no longer exists.

Are you looking at putting an MCP server in front of your Rails application’s data and wondering what it takes to do it safely? Talk to us today!

Why Patching the Gem Didn’t Fix CVE-2026-66066

2026-08-03T00:00:00-04:00

You saw the advisory for CVE-2026-66066, the Active Storage vulnerability in the way Rails processes image variants with libvips. You bumped activestorage to the patched version, ran your tests, deployed, and moved on. That is the responsible thing to do, and for most Ruby vulnerabilities it would be the whole job.

This one is different. The patched version of Active Storage will not run on an old copy of libvips. It raises an exception during boot and refuses to start:

/usr/local/bundle/gems/activestorage-8.1.3.1/lib/active_storage/vips.rb:36:in '': libvips's unfuzzed operations are not safe to use with untrusted content, and Active Storage cannot disable them. Disabling them requires libvips 8.13 or later and ruby-vips 2.2.1 or later. Please upgrade libvips and ruby-vips, or remove the ruby-vips gem from your Gemfile. (RuntimeError)

libvips is a system library that lives in your container image, not a gem in your Gemfile, so bumping the gem does nothing on its own until you rebuild the image. If your image still ships the old library, you are in one of two states, and neither is the one you think you are in: either your app won’t boot, or it never received the patched gem at all and is quietly still vulnerable.

In this post, you’ll learn why upgrading activestorage doesn’t close CVE-2026-66066 on its own, how a stale container image both hides the vulnerability and blocks the fix, and why rebuilding on the wrong base still leaves you exposed.

The CVE, and why the gem bump isn’t the whole fix

CVE-2026-66066 is a vulnerability in the way Active Storage processes image variants. When Active Storage generates a variant, a thumbnail or a resized copy, it hands the work off to libvips, a fast image-processing library. The trouble is that some of libvips’s operations are not safe to run on untrusted input, and older versions of the library give you no way to turn those operations off. An attacker who can get your app to process a malicious file can abuse this. The official Rails advisory describes the impact as unauthenticated arbitrary file read that can escalate to remote code execution. Its severity rating is Critical, and public write-ups of the exploit are already circulating.

As of early August 2026 it is not yet listed in CISA’s Known Exploited Vulnerabilities catalog, but that is not a reason to relax. Arbitrary file read on a production host usually means your credentials and environment variables are readable, which is often enough for an attacker to move further into your infrastructure.

If you use Active Storage with image variants, you are very likely affected. The vips processor has been the default variant processor since config.load_defaults 7.0, and it has stayed the default since, so most modern Rails apps rely on it without ever opting in. The versions that carry the fix are activestorage 7.2.3.2, 8.0.5.1, and 8.1.3.1.

Patching the gem is normally the reliable fix for a Rails CVE, and usually that is where the story ends (we have written before about several Rails CVEs worth checking). If your app is on an end-of-life branch like 7.0 or 7.1, there is no patched release to bump to at all, and your only options are upgrading libvips together with the mitigation below, or upgrading Rails to a supported version.

The fix is genuinely both/and: you need the patched activestorage and you need libvips 8.13 or newer, because libvips 8.13 is the first version that can block those unsafe operations. Patched Active Storage checks for that capability when it boots, and if libvips is too old it raises the exception I showed above and refuses to start rather than run in what the advisory calls an “unsecurable environment”. The newer library does the actual securing; the gem only knows how to ask for it.

If you can’t bump the gem right away, the advisory documents two workarounds that still require libvips 8.13 or newer: calling Vips.block_untrusted(true) from an initializer (with ruby-vips 2.2.1 or newer), or setting the VIPS_BLOCK_UNTRUSTED environment variable, which libvips reads at initialization.

And if there is any chance your app processed a malicious upload before you patched, rotate whatever secrets were reachable from that host. To find out whether that actually happened, Rails published forensic tooling that scans your Active Storage blobs for the crafted files the attack depends on and estimates how long you were exposed, though the maintainers note a clean result is strong evidence rather than proof.

The proof: same gem, two images

To make the problem concrete, I built a small demo: one Rails app, one Dockerfile, and two images that differ in exactly one thing. The app has the patched activestorage (8.1.3.1) and Active Storage configured with the vips variant processor. The boot check fires from the configuration and the environment, not from a request.

The Dockerfile takes the Debian suite as a build argument, so the only thing that changes between the two builds is the base image, and therefore the version of libvips that apt installs:

# syntax=docker/dockerfile:1
ARG RUBY_VERSION=3.4
ARG SUITE=bookworm
FROM docker.io/library/ruby:${RUBY_VERSION}-slim-${SUITE}

# libvips comes from the OS package repo, NOT from a gem.
# The base image (SUITE) decides which libvips version you get:
#   bullseye -> 8.10.x (< 8.13, cannot block untrusted ops)
#   bookworm -> 8.14.x (>= 8.13, can)
RUN apt-get update -qq \
 && apt-get install --no-install-recommends -y build-essential git libvips libvips-tools libpq-dev pkg-config \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .

ENV RAILS_ENV=production \
    SECRET_KEY_BASE_DUMMY=1

# Print the receipts, then boot.
CMD ["bash", "-lc", "echo '== libvips =='; vips --version; echo '== activestorage =='; bundle list | grep activestorage; echo '== boot =='; bin/rails runner 'puts :booted_ok'"]

Then I built the same file twice, changing only the suite:

docker build -f Dockerfile.demo --build-arg SUITE=bookworm -t asdemo:new .
docker build -f Dockerfile.demo --build-arg SUITE=bullseye -t asdemo:old .

Each container prints its libvips version, confirms which activestorage is installed, and then tries to boot the app. Running the bookworm image first:

$ docker run --rm asdemo:new
== libvips ==
vips-8.14.1
== activestorage ==
  * activestorage (8.1.3.1)
== boot ==
booted_ok

libvips 8.14.1, the patched gem, and a clean boot. Now the bullseye image, which is identical except that apt installed an older libvips:

$ docker run --rm asdemo:old
== libvips ==
vips-8.10.5-Wed Apr 30 17:29:54 UTC 2025
== activestorage ==
  * activestorage (8.1.3.1)
== boot ==
/usr/local/bundle/gems/activestorage-8.1.3.1/lib/active_storage/vips.rb:36:in '': libvips's unfuzzed operations are not safe to use with untrusted content, and Active Storage cannot disable them. Disabling them requires libvips 8.13 or later and ruby-vips 2.2.1 or later. Please upgrade libvips and ruby-vips, or remove the ruby-vips gem from your Gemfile. (RuntimeError)
        ... backtrace trimmed ...

But the bullseye image ships libvips 8.10.5, which is older than 8.13, so patched Active Storage does exactly what the advisory says it will and refuses to boot. To rule out the gem layer, ruby-vips is 2.3.0 in both images and the Gemfile.lock is identical. The only moving part is the system library. The same patched Gemfile produced one app that boots and one that won’t.

Rebuilding the image isn’t always enough

The obvious fix is to rebuild the image, and that is the right instinct, but it comes with a trap. Rebuilding only helps if the base image you rebuild on actually carries a newer libvips, and Debian bullseye does not. Checking the bullseye base while writing this, apt still installed libvips 8.10.5, the same version the demo hit. bullseye is an older Debian release, and its package repositories, security updates included, are effectively frozen at libvips 8.10, so a rebuild faithfully reinstalls exactly what is there.

The version of libvips you get is really a property of the base image’s distribution, not of how recently you rebuilt. To get a patched version of libvips, you have to move to a base whose repositories carry it. Moving from bullseye to bookworm is the simplest path, since bookworm ships libvips 8.14. If you are pinned to an older distribution for another reason, compiling a newer libvips yourself is the alternative, though moving the base image to bookworm is usually less work and less to maintain afterward.

A rebuild that stays on the same old base is not a fix; it just reproduces the vulnerable environment with a fresh timestamp.

The image that quietly stays vulnerable

There is a worse case than the app that refuses to boot, and it is the quiet one. The image that raises on boot at least tells you something is wrong, because the app is down and you notice right away. The dangerous image is the one that was never touched at all. It still runs the old, unpatched activestorage on the old libvips, it boots perfectly, and it keeps serving traffic while remaining fully exploitable. Nobody gets an exception, and nothing looks broken.

The instinct is to reach for image age to find these, but the age of a tag does not tell you what you need to know. An image tagged last week can still be built on a base that is two years old, and an image built months ago might be sitting on a perfectly current base. What you actually care about is whether the image was rebuilt since the base it depends on last changed. An image that has fallen behind its own base has missed whatever security updates that base shipped, libvips among them, even if its tag looks recent.

This is the same kind of blind spot we write about on the gem side. A tool like bundler-audit scans your Gemfile.lock for known-vulnerable gems, but it reads the lockfile, so it has no way of knowing which version of libvips your base image installed.

In our experience auditing client deployments, stale base images are the rule rather than the exception. CVE-2026-66066 is a good reason to check whether your own images have drifted, and to make rebuilding them a habit rather than a one-time scramble.

Conclusion

The fix for CVE-2026-66066 requires two things: the patched gem and a base image that ships libvips 8.13 or newer. Patching the gem without rebuilding the image leaves you in one of two bad states. Image drift is not a problem you fix once because base images drift the same way gems do, and the only thing that keeps them current is a rebuild cadence you actually stick to.

We can help you audit what your deployed images are actually running and find the gaps your Gemfile cannot see. Send us a message!

Migrating from sass-rails to Dart Sass

2026-07-30T15:21:39-04:00

For those who have been coding CSS since the Internet Explorer 6 era, when aligning divs on the web was an art, and there was no way to use partials or variables, the arrival of SCSS was a gift to life. At that moment, creating partials and reusing variables for your primary colors was a delightful experience.

Now in 2026, for the real fans, it’s possible you’re still using sass-rails and you’re full of these files around your project. So if you still want to keep using it like me, I recommend migrating to Dart Sass, which is, in fact, a simple migration, to avoid headaches in the future and, most importantly, to start using the latest features.

Historical context

To give a bit of context, you may remember that sass-rails has been the default SCSS library since Rails 3.1 (2011). Some engineers like me were using Sass before that, but that’s when it became a Rails standard.

Behind it, sass-rails originally used the Ruby implementation of Sass (the original sass gem). That implementation reached its end-of-life in 2019, so starting with Rails 6 the default moved to sassc-rails, which used LibSass, the C/C++ port of the Sass compiler. LibSass was built to be a faster and more portable alternative to the original Ruby-based compiler.

However, LibSass reached its official end-of-life (EOL) in October 2025 too. So now the recommendation is to migrate to Dart Sass, which includes more features and better CSS compatibility. As the name says, it’s built in the Dart language, and the wrapper tool uses the standalone Dart Sass executable, meaning you don’t even need Node.js installed to use it.

Why keep using Dart Sass?

A fair question in 2026 is why bother with Sass at all when modern CSS already has native variables, nesting, and more. The honest answer: if your project already runs on SCSS, a full rewrite to plain CSS is a big effort with little payoff.

Dart Sass is also the only Sass implementation still maintained. It’s the reference now, it gets all the new features first, and it keeps the same partials, mixins, and functions you already use. So instead of throwing away years of styles, you keep them and stay on a tool that’s still alive.

What Changes in Dart Sass

These are the most important changes.

`/` division operator deprecated (biggest breaking change)

Maybe you never noticed, but the slash / operator has two behaviors: on one hand, it works as division, but in another context, it works as a separator. You can imagine the migraine for the devs maintaining that.

$container-width: 1200px;
$grid-columns: 12;

.sidebar {
  // as divisor
  width: $container-width / $grid-columns;

  // as separator
  font: 16px / 1.5 sans-serif;
}

For division, you now use math.div():

@use 'sass:math';

.sidebar {
  width: math.div($container-width, $grid-columns);
}

And when you actually want a slash separated list with variables, you use list.slash():

.sidebar {
  font: list.slash($font-size, $line-height) sans-serif;
}

`@import` deprecated in favor of `@use` and `@forward`

You probably also didn’t notice that when you do an @import foo on a file, all the imported values are loaded into the global namespace. That means, for example, that all the functions become available globally. If you’re experienced enough (and if not, just trust us), having everything available, especially on medium or big projects, can soon become a mess of cascading rules overwriting each other. It makes compilation slow as a consequence of importing the same file multiple times, and it increases the complexity of knowing where a variable or function came from.

The good news is that for you it just means starting to replace @import foo with @use foo.

Imagine you have one file where you define the variables:

// _variables.scss
$brand-color: #ff0000;

On the other side, you have a file with a few functions, but it also uses the variables:

// _mixins.scss
@import "variables";

@mixin brand-border {
  border: 2px solid $brand-color;
}

Here, brand-border is available globally. In your file you’d use it by doing:

@import "variables";
@import "mixins"; // Works because everything is globally leaked

.button {
  color: $brand-color;
  @include brand-border;
}

Now, with the latest version, the code looks similar:

@use "variables"; // Load variables for main.scss
@use "mixins";    // Load mixins for main.scss

.button {
  color: variables.$brand-color; // Uses variables namespace
  @include mixins.brand-border;   // Uses mixins namespace
}

Now it’s using namespaces and nothing is globally available.

Other breaking changes

Finally, there’s a list of more breaking changes here, but if you’re working on a Rails project, the most typical ones are:

Math functions now require an explicit module import:

// Before
$value: round(1.5);
$half: floor(10px / 2);

// After
@use 'sass:math';

$value: math.round(1.5);
$half: math.floor(math.div(10px, 2));

Color functions are deprecated in favor of the sass:color module:

// Before
$dark: darken(#036, 10%);
$light: lighten(#036, 10%);

// After
@use 'sass:color';

$dark: color.adjust(#036, $lightness: -10%);
$light: color.adjust(#036, $lightness: 10%);

Other modules like sass:string, sass:list, and sass:map follow the same pattern. Also, global functions like str-length(), map-get(), and map-keys() now require an explicit @use declaration.

Using the Migrator

Luckily there’s a Sass Migrator that automatically updates your files to make it easier to migrate your project.

You can install it with npm install -g sass-migrator. After that, if your base file is application.scss, you can run it like this:

sass-migrator module --migrate-deps app/assets/stylesheets/application.scss

There are a few options there. The first useful one is --migrate-deps, which tells the migrator to update both the explicitly specified stylesheets and any dependencies linked via @use, @forward, or @import rules.

A few Rails tips

Once you switch to the dartsass-rails gem, a couple of things saved us headaches.

First, register any extra SCSS entry point in config/initializers/dartsass.rb. The gem builds application.scss by default, but any other entry point you have (an admin stylesheet, a separate theme, etc.) won’t be compiled by Dart Sass unless you add it here. If you forget, those files won’t be compiled into CSS at all, or Sprockets will throw an error since it no longer has a Sass compiler to process them:

Rails.application.config.dartsass.builds.merge!(
  "admin.scss" => "admin.css",
  "theme.scss" => "theme.css"
)

Second, third-party files you don’t control will still throw deprecation warnings. Use --quiet-deps to silence the noise from those while keeping warnings for your own code:

Rails.application.config.dartsass.build_options << "--quiet-deps"

And once your own code is clean, turn the deprecations you already fixed into build errors so they don’t creep back in:

Rails.application.config.dartsass.build_options << "--fatal-deprecation=import"
Rails.application.config.dartsass.build_options << "--fatal-deprecation=mixed-decls"

Conclusion

Migrating from Sass Rails to Dart Sass isn’t as scary as it sounds. The Migrator does most of the heavy lifting, and the rest is mostly swapping @import for @use and adding a few module imports. Do it now while it’s still a small migration, and you get to keep your SCSS files and stay on a tool that’s actually maintained.

Planning a bigger Rails upgrade and want a hand? We can help you get there!

Tracking LLM Latency & Cost with Rails Events

2026-07-28T08:47:50-04:00

Wiring an LLM into a Rails app takes a handful of lines. Understanding what it actually costs you (feature by feature, user by user) is harder. Most providers and SDKs already report tokens, latency, and even cost, but that data lives in their dashboard. It’s disconnected from your requests, your users, and the feature that made the call. And it sits apart from the APM and logs where you already watch the rest of your app.

In a previous post, we introduced Rails.event.notify(...), the tool-agnostic Event Reporter shipping in Rails 8.1. In this post, we’ll put it to work on a real problem: instrumenting every LLM call in your app so token usage, latency, and cost become structured events you can log, graph, and forward to any APM or data warehouse.

Why instrument LLM calls?

Before writing any code, it helps to be specific about what we’re after. Four things, really. Cost, from the raw token counts up to the dollar figure on the invoice. Latency, so a slow model or a bloated prompt shows up before your users feel it. Failures, because a timeout or a rate limit shouldn’t just vanish. And, most of all, attribution: not just that a call happened, but which feature, user, and request set it off.

ActiveSupport::Notifications could get us there, but we’d be writing custom glue code for every APM vendor. The Event Reporter gives us one structured emission point instead, and lets each subscriber decide what to do with it.

Prerequisites: This tutorial assumes Rails 8.1 (for Rails.event) and any LLM client that reports token usage. The examples use the ruby_llm gem, but the pattern works with the official anthropic/openai SDKs or a raw Net::HTTP call just as well.

The starting point: an uninstrumented service

Here’s a typical, uninstrumented service that summarizes some text:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    chat = RubyLLM.chat(model: MODEL)
    response = chat.ask("Summarize the following text:\n\n#{@text}")
    response.content
  end
end

It works, but it’s a black box. We have no idea how many tokens that summary consumed, what it cost, or how long the LLM took to respond. Let’s improve that.

Emitting a structured event around the call

The Event Reporter’s core method is Rails.event.notify(name, payload). We wrap the call, measure the duration with a monotonic clock, and emit everything we care about:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

    chat = RubyLLM.chat(model: MODEL)
    response = chat.ask("Summarize the following text:\n\n#{@text}")

    duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

    Rails.event.notify(
      "llm.completion",
      model: MODEL,
      input_tokens: response.input_tokens,
      output_tokens: response.output_tokens,
      total_tokens: response.input_tokens + response.output_tokens,
      duration_ms: duration_ms
    )

    response.content
  end
end

Every summary now publishes a single llm.completion event. Notice what we don’t put in the payload: no prompt text, no user content. Keep payloads small and free of PII, just IDs, token counts, and durations.

Listening with a subscriber

An event that no one listens to does nothing. Subscribers are plain Ruby objects that implement an #emit(event) method, where event is a hash containing :name, :payload, :tags, :context, :timestamp, and :source_location.

Let’s start with a subscriber that writes a compact key=value log line and forwards metrics to an APM. It lives under app/subscribers/, so Rails autoloads it:

# app/subscribers/llm_event_subscriber.rb
class LlmEventSubscriber
  def emit(event)
    return unless event[:name] == "llm.completion"

    payload = event[:payload]

    Rails.logger.info(
      "[llm.completion] model=#{payload[:model]} " \
      "tokens=#{payload[:total_tokens]} " \
      "duration_ms=#{payload[:duration_ms]}"
    )

    # Forward to your APM of choice (Datadog, AppSignal, New Relic, etc.):
    MyAPM.distribution(
      "llm.duration_ms",
      payload[:duration_ms],
      model: payload[:model]
    )
    MyAPM.counter(
      "llm.total_tokens",
      payload[:total_tokens],
      model: payload[:model]
    )
  end
end

Then register an instance once, at boot:

# config/initializers/llm_events.rb
Rails.event.subscribe(LlmEventSubscriber.new)

The same event now lands in your logs and your dashboards, without the service object knowing anything about AppSignal, Datadog, or New Relic. Swap the subscriber’s body and you’ve swapped vendors.

From tokens to dollars

Tokens are only half the story. The number your finance team cares about is cost. Providers charge different rates for input and output tokens: the prompt you send costs less, the text the model generates back costs more. The exact rates vary by model. So we keep a small lookup table that maps each model to its two rates, in the same units the pricing pages use: U.S. dollars per one million tokens.

There’s a catch, though: a hand-maintained table like this goes stale fast. Providers release new models and adjust prices regularly, and every change means another edit to keep in sync. If you’re using ruby_llm, you can skip the table entirely. The gem keeps its own pricing registry and calculates cost for you: a response exposes response.cost.total, and model.cost_for(response.tokens) returns a RubyLLM::Cost broken down by component, input, output, cache_read, cache_write, thinking and the total across all of them. When your client hands you cost directly, emit that value and let the gem take care of staying current.

Not every LLM client reports cost, though, so it’s worth knowing how to compute it yourself. In that case we keep the table and the math inside the subscriber, so cost is computed once and every consumer of the event gets it for free:

# app/subscribers/llm_event_subscriber.rb
class LlmEventSubscriber
  # Per-model pricing in USD per 1 million tokens.
  #   input  => rate for the tokens you send (the prompt)
  #   output => rate for the tokens the model generates back
  # Copy these numbers from your provider's pricing page and keep them in sync.
  PRICING = {
    "claude-haiku-4-5" => { input: 1.00, output: 5.00 },
    "claude-sonnet-5"  => { input: 3.00, output: 15.00 }
  }.freeze

  def emit(event)
    return unless event[:name] == "llm.completion"

    payload = event[:payload]
    cost = estimate_cost(payload)

    Rails.logger.info(
      "[llm.completion] model=#{payload[:model]} " \
      "tokens=#{payload[:total_tokens]} " \
      "duration_ms=#{payload[:duration_ms]} " \
      "cost_usd=#{cost.round(6)}"
    )

    # The duration_ms and total_tokens metrics are
    # omitted to keep the example focused on cost.

    MyAPM.distribution(
      "llm.cost_usd",
      cost,
      model: payload[:model]
    )
  end

  private

  def estimate_cost(payload)
    prices = PRICING[payload[:model]]
    return 0.0 unless prices

    input_cost = payload[:input_tokens] * prices[:input] / 1_000_000.0
    output_cost = payload[:output_tokens] * prices[:output] / 1_000_000.0
    input_cost + output_cost
  end
end

The registration in the initializer stays exactly the same. Now every completion carries a dollar figure you can sum, chart, and alert on.

Attributing calls to features and users

Aggregate token counts are useful, but “which feature is eating my budget?” and “how much did this user cost this month?” are the questions that actually drive decisions. The Event Reporter answers both with two mechanisms: tags and context.

Tags help identify which feature or operation triggered the call. Wrap the call in Rails.event.tagged, using a keyword so the tag carries a real value rather than just a label:

# app/services/summarizer.rb
def call
  Rails.event.tagged(feature: "summarization") do
    # ...measure and notify as before...
  end
end

Context describes the environment an event happens in, and it’s typically set once per request. A great place is a controller before_action or the base controller:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_llm_context

  private

  def set_llm_context
    Rails.event.set_context(
      request_id: request.request_id,
      user_id: current_user&.id
    )
  end
end

From now on, every llm.completion event automatically carries the tags and context, with no extra work in the service object. A full event handed to your subscriber now looks like this:

{
  name: "llm.completion",
  payload: {
    model: "claude-haiku-4-5",
    input_tokens: 2000,
    output_tokens: 500,
    total_tokens: 2500,
    duration_ms: 842
  },
  tags: { feature: "summarization" },
  context: { request_id: "abc123", user_id: 456 },
  timestamp: 1738964843208679035,
  source_location: { filepath: "app/services/summarizer.rb", lineno: 14, label: "Summarizer#call" }
}

Update the subscriber to read them:

def emit(event)
  return unless event[:name] == "llm.completion"

  payload = event[:payload]
  # `tags` is a hash. Because we tagged with `feature:`, we can read the value
  # straight from the :feature key, with no assumptions about ordering.
  feature = event[:tags][:feature]
  user_id = event[:context][:user_id]

  Rails.logger.info(
    "[llm.completion] feature=#{feature} user_id=#{user_id} " \
    "model=#{payload[:model]} cost_usd=#{estimate_cost(payload).round(6)}"
  )
end

A reusable instrumentation helper

By now we’ll want this measure-and-notify block around every LLM call, not just the summarizer. Let’s extract it into a helper so every call site stays consistent:

# app/services/llm_instrumentation.rb
module LlmInstrumentation
  # Wraps any block that returns an object responding to
  # #input_tokens and #output_tokens, and emits an llm.completion event.
  def self.instrument(model:, feature:)
    Rails.event.tagged(feature: feature) do
      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

      response = yield

      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

      Rails.event.notify(
        "llm.completion",
        model: model,
        input_tokens: response.input_tokens,
        output_tokens: response.output_tokens,
        total_tokens: response.input_tokens + response.output_tokens,
        duration_ms: duration_ms
      )

      response
    end
  end
end

The service object shrinks back to almost what we started with, now fully instrumented:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    response = LlmInstrumentation.instrument(model: MODEL, feature: "summarization") do
      RubyLLM.chat(model: MODEL).ask("Summarize the following text:\n\n#{@text}")
    end

    response.content
  end
end

Capturing the failures

Surfacing failed calls is just as important as tracking successful ones. Emit a separate event on error so timeouts and rate limits don’t disappear silently:

# app/services/llm_instrumentation.rb
def self.instrument(model:, feature:)
  Rails.event.tagged(feature: feature) do
    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

    begin
      response = yield
    rescue => error
      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
      Rails.event.notify(
        "llm.error",
        model: model,
        error_class: error.class.name,
        duration_ms: duration_ms
      )
      raise
    end

    duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

    Rails.event.notify(
      "llm.completion",
      model: model,
      input_tokens: response.input_tokens,
      output_tokens: response.output_tokens,
      total_tokens: response.input_tokens + response.output_tokens,
      duration_ms: duration_ms
    )

    response
  end
end

Add a branch to your subscriber for "llm.error", and now your dashboards show a failure rate alongside cost and latency, three basic signals that you need to observe on every LLM-powered feature.

Feeding a data warehouse

Because the payloads are already structured, a warehouse-oriented subscriber is just another #emit implementation. Buffer the events and ship them to your analytics pipeline:

# app/subscribers/warehouse_subscriber.rb
class WarehouseSubscriber
  def emit(event)
    return unless event[:name].start_with?("llm.")

    LlmEventBufferJob.perform_later(
      name: event[:name],
      payload: event[:payload],
      tags: event[:tags],
      context: event[:context],
      timestamp: event[:timestamp]
    )
  end
end

# config/initializers/llm_events.rb
Rails.event.subscribe(LlmEventSubscriber.new)
Rails.event.subscribe(WarehouseSubscriber.new)

Once the data lands, per-user cost reports, per-feature budgets, and model A/B comparisons are all just queries.

Best practices for LLM events

A few habits keep this instrumentation clean as it grows. Stick to a clear resource.action namespace, like llm.completion and llm.error, so related events group together. Keep payloads free of PII. Compute cost in the subscriber rather than at the call site, so pricing lives in one place and your service objects don’t need to know about it. Instrument once through a shared helper, so every call site emits consistent events. And always instrument failures, because an error rate is as important as a cost figure.

Conclusion

LLM features don’t have to be black boxes. One Rails.event.notify call in the right spot turns an opaque API request into an event you can log, cost out, graph, or ship to a warehouse, and none of your service objects have to know where it ends up. As AI keeps creeping into your latency budget and your monthly bill, that visibility is what stops it from getting away from you.

Building AI features into your Rails app, or getting to Rails 8.1 so you can use the Event Reporter? Let’s talk.

Rake Beyond Rails: A Build Tool You Know

2026-07-23T00:00:00-04:00

Most Rails developers have crossed paths with Rake (usually to run a migration, seed a database, or clear out test data). If you’re like me, you may have quietly filed Rake away under “that place where Rails keeps database tasks.” But Rake is far more powerful than that.

It isn’t just a Rails helper: it’s a full-blown, general-purpose build system, sitting quietly in your project, ready to automate almost anything. And the best part? It speaks Ruby. That means, as a Rails developer, you’re already fluent in the language your build tool understands. In this post, I want to open your eyes to the wider world of Rake, beyond migrations and seeds, into using it as a central hub for building, scripting, and orchestrating your entire workflow.

What Makes Rake a (great) Build Tool?

What makes Rake such a useful build tool is its simplicity paired with real structure. At its core, Rake lets you define tasks along with their dependencies—so if one task relies on another, Rake automatically figures out the correct order to run everything.

You don’t have to micro-manage the sequence; you simply declare the relationships, and Rake takes care of the orchestration. Tasks can be completely standalone or chained together into full workflows.

To keep things tidy, you can group related tasks using namespaces, which means your Rakefile doesn’t devolve into a long, messy script. And because Rake is Ruby, you get all the flexibility of a real programming language: conditions, loops, helper methods, constants and whatever you need. It’s code, not configuration.

Plus, discovery is built-in: a quick rake --tasks gives you a clear overview of available commands (as long as you’ve added desc blocks), making your automation self-documenting and easy for your team to adopt.

Rails and Rake: Clearing Up the Overlap

Since Rails 5.0, the rails command has quietly wrapped many Rake tasks under the hood. That means rails db:migrate and rake db:migrate usually do the same thing and Rails simply delegates to Rake behind the scenes. You can verify this yourself: running rake --tasks and rails --tasks in a Rails app will show significant overlap.

So why reach for rake directly? Because the Rails command only exposes tasks that Rails itself knows about. The moment you define your own custom tasks (like the Docker and setup workflows we’ll see later) rake is how you run them. It’s also what you’ll use outside of a Rails environment: in standalone Ruby scripts, non-Rails projects, or CI pipelines where loading the full Rails stack would be overkill. Knowing both are available, and when to use each, gives you the full picture.

Types of Tasks You Can Automate in a Rails Project Using Rake

One of the biggest strengths of Rake is how easily it adapts to all parts of your project (not just database chores). Once you start seeing it as a build tool, entire areas of your workflow become fair game for automation.

Setup & Bootstrapping

Rake is perfect for onboarding tasks like app:setup, where you might chain actions such as creating the database, installing JavaScript dependencies, seeding default config files, or preparing environment variables. Instead of documenting these steps in a README, you can package them into a single, reliable command.

Database Maintenance

Most Rails developers already use Rake here (seeding data, cleaning test tables, or resetting everything with a fresh database). But Rake can go beyond the basics: think sample data generators, anonymizers, or maintenance routines that run before a deploy.

Development Workflow

Rake can also replace shell scripts for everyday dev tasks like running the test suite, linting code, precompiling assets, or bundling front-end builds. Instead of remembering long commands, you get tidy shortcuts like rake test:all or rake lint.

Operations & DevOps

Need to deploy? Back up the database? Sync files to S3 or clear caches? Rake can orchestrate these too. It’s especially useful when you want the same task to run locally or in CI, making deployments repeatable and version-controlled.

File & Content Automation

Rake shines when generating or processing files: reports, CSV exports, documentation, static site assets, or scheduled data imports. With full access to Rails models and Ruby’s standard library, you can automate business workflows directly from your codebase.

Advanced Rake Techniques

Once you’re comfortable defining simple tasks, Rake opens the door to more advanced features that elevate it from a utility script into a true build system. These features allow you to build smarter workflows, generate files efficiently, pass dynamic input, and interact with the rest of your tooling.

Passing Arguments to Tasks

Rake supports inline arguments, which is perfect for tasks that need parameters. For example, generating a report for a specific year might look like this:

rake report:generate[2024]

Accessing that argument inside the task lets you build flexible, reusable commands without hardcoding values.

namespace :report do
  desc "Generate report for a given year"
  task :generate, [:year] do |_, args|
    year = args[:year] || Time.now.year
    puts "Generating report for #{year}"
    # Report generation logic here
  end
end

File Tasks with Dependency Awareness

Rake is capable of file-based tasks, which only run if an input file has changed, similar to Make. This is ideal for generating compiled assets, documentation, or exports without doing unnecessary work.

Setting Default Tasks

You can define a default task so that running plain rake triggers something useful, like linting and testing:

task default: [:lint, :test]

This is a neat productivity boost, especially on CI or during local development.

Shelling Out to External Commands

Need to interact with the system? Rake can easily call tools like yarn, bundle, or docker using the sh helper:

sh 'docker-compose up -d'

This allows you to centralize multi-step builds or deployment scripts directly in Ruby.

Managing Environment Variables in Rake

Sometimes tasks require configuration: API keys, modes, targets, or flags. The simplest way is to pass environment variables inline:

MY_VALUE=value rake deploy

Inside Rake, you can access it with:

value = ENV['MY_VALUE'] || 'default_value'

This works well for one-off overrides, but it becomes cumbersome when you’re juggling multiple variables.

In a Rails application, a cleaner approach is to use dotenv-rails and a .env file. Rails automatically loads these variables before running your Rake tasks, making them available through ENV without cluttering your command line. This keeps secrets organized and reusable across tasks, consoles, and even development scripts.

Real Examples (Code Snippets!)

A Rakefile is more than just a list of commands, it’s a fully valid Ruby program. That means you can leverage Ruby’s syntax, methods, and control structures to define tasks that are flexible, chainable, and reusable.

One particularly powerful approach is to replace much of your bin/setup script with Rake tasks. By doing this, you turn a one-off shell script into a structured, discoverable build process. You already have a build tool sitting in your Rails app, it’s called Rake, so there’s no need to hide important automation in shell scripts. In the example below, we’ll see how a typical bin/setup script can be refactored into clear, namespaced Rake tasks that are easy to run, extend, and maintain.

For convenience, and to keep things familiar, we can still keep a thin bin/setup script that simply calls our Rake task. Your bin/setup could be as simple as:

#!/usr/bin/env ruby

system("bin/rake app:setup")

A corresponding Rakefile could define the app:setup task like this:

namespace :app do
  desc "Setup application for development"
  task :setup, [:reset] => ["app:dependencies", "db:prepare", "app:cleanup"] do |_, args|
    if args[:reset] == "reset"
      Rake::Task["db:reset"].invoke
    end
    puts "Application setup complete."
  end

  desc "Install dependencies"
  task :dependencies do
    sh "bundle check || bundle install"
  end

  desc "Cleanup logs and tmp"
  task :cleanup do
    sh "bin/rails log:clear tmp:clear"
  end
end

If your project runs in Docker locally, you’ve probably spent more time than you’d like typing long docker-compose commands. Rake can simplify this by letting you define tasks that wrap common Docker operations. You can organize these tasks into namespaces that match your mental model, like docker:up, docker:down, or docker:logs, so they’re easy to remember and chain together. And with desc blocks, these tasks become self-documenting: running rake --tasks will give you a clear list of available commands along with helpful descriptions. In the example below, we’ll see how Rake can turn a set of verbose Docker commands into a simple, maintainable, and discoverable workflow.

CORE_SERVICES = 'web db'.freeze

namespace :docker do
  desc "Stop Docker containers"
  task :down do
    sh "docker-compose down"
  end

  desc "Start core Docker containers, optionally specifying additional services (e.g. rake docker:up[redis])"
  task :up, [:more_services] do |_, args|
    more_services = args[:more_services] || ""
    sh "docker-compose up -d #{CORE_SERVICES} #{more_services}"
  end

  desc "Start all Docker containers in detached mode"
  task :"up:all" do
    sh "docker-compose up -d"
  end

  desc "Restart Docker containers"
  task restart: [:down, :up]

  desc "View logs for all services or a specific service (e.g. rake docker:logs[web])"
  task :logs, [:service] do |_, args|
    service = args[:service] || ""
    sh "docker-compose logs -f #{service}"
  end

  desc "Build Docker image"
  task :build do
    sh "docker-compose build"
  end

  desc "Rebuild image and restart app dev services"
  task :rebuild => [:down, :build, :up, :'db:prepare'] do
    puts "Rebuild complete"
  end

  desc "Stop containers and remove volumes. Use task docker:clobber to remove volumes"
  task clean: [:down] do
    sh "docker-compose rm -f"
  end

  desc "Stop containers and remove volumes. Use task docker:clean to keep volumes"
  task :clobber do
    sh "docker-compose down -v --remove-orphans"
    sh "docker-compose rm -f"
  end

  desc "Open a shell in the web service"
  task :shell do
    sh "docker-compose run --rm web /bin/bash"
  end

  desc "Open a Rails console in the web service"
  task :"shell:app" => [:up] do
    sh "docker-compose run --rm web bin/rails c"
  end

  desc "Open a database console in the web service"
  task :"shell:db" => [:up] do
    sh "docker-compose run --rm web bin/rails dbconsole"
  end

  desc "Run a command in the web service (e.g. rake docker:run['bin/rails db:migrate']), defaults to opening a bash shell"
  task :run, [:cmd] => [:up] do |_, args|
    cmd = args[:cmd] || "bin/bash"
    sh "docker-compose run --rm web #{cmd}"
  end

  desc "Run linting and formatting (requires web service to be running)"
  task :lint => [:up] do
    sh "docker-compose run --rm web bin/rake rubocop"
  end
end

We defined a set of Docker-related tasks with desc blocks for documentation. This means that we can easily see what commands are available by running rake -T docker, and each task encapsulates common Docker operations in a clear, maintainable way.

❯ rake -T docker
rake docker:build              # Build Docker image
rake docker:clean              # Stop containers
rake docker:clobber            # Stop containers and remove volumes
rake docker:down               # Stop Docker containers
rake docker:lint               # Run linting and formatting (requires web service to be running)
rake docker:logs[service]      # View logs for all services or a specific service (e.g
rake docker:rebuild            # Rebuild image and restart app dev services
rake docker:restart            # Restart Docker containers
rake docker:run[cmd]           # Run a command in the web service (e.g
rake docker:shell              # Open a shell in the web service
rake docker:shell:app          # Open a Rails console in the web service
rake docker:shell:db           # Open a database console in the web service
rake docker:up[more_services]  # Start core Docker containers, optionally specifying additional services (e.g
rake docker:up:all             # Start all Docker containers in detached mode

Conclusion – Rediscover Rake

Rake is a powerful automation tool that you already have at your fingertips, yet many developers limit it to simple Rails tasks. In reality, Rake is Ruby-native, readable, version-controlled, and versatile enough to run in any project where Ruby is available.

It can replace Makefiles, Bash scripts, and even parts of your CI workflow, centralizing automation in one maintainable place. By moving scattered scripts and repetitive commands into Rake tasks, you unlock a single, discoverable system that your team can understand and extend. As a Rails developer, you already know the language, now it’s time to rediscover Rake and unleash its full potential. Looking for staff augmentation for your next project? We can help!

Automate Tech Debt Audits with Claude Code

2026-07-21T06:00:00-04:00

Today I’m excited to share a new open source project: A Claude Code skill to assess technical debt in a Ruby on Rails application. It leverages some of the libraries that we have open sourced and maintained for a long time.

Over the years, we’ve written about many of the tools we use: Skunk for combining code quality and code coverage data, bundler-audit for security vulnerabilities in your dependencies, libyear-bundler for measuring dependency freshness in a Ruby application, and RubyCritic for churn vs. complexity analysis.

The challenge? Running all these tools manually takes time and interpreting the results across multiple reports can be tedious.

What if we could automate the entire audit process and generate a comprehensive report with a single command?

In this article, I’ll show you how we built a Claude Code skill that does exactly that, in minutes!

What is Claude Code?

Claude Code is Anthropic’s official CLI tool for Claude. It allows you to interact with Claude directly from your terminal, and it can read files, run commands, and make changes to your codebase.

One of its most powerful features is skills. Skills are reusable instructions that teach Claude how to perform specific tasks.

Skills are stored as markdown files in your project’s .claude/skills/ directory and can be invoked with slash commands like /tech-debt-audit.

The Problem We’re Solving

When we onboard a new client project, we need to quickly assess the health of their Rails application. This means running multiple tools:

Security: bundler-audit, Brakeman, bundler-leak
Dependencies: next_rails, libyear-bundler
Code Coverage: SimpleCov
Churn vs. Complexity: RubyCritic
Churn vs. Complexity vs. Code Coverage: Skunk

Each tool has its own installation requirements, command-line interface, and output format. A typical audit might involve:

gem install bundler-audit && bundle-audit check --update
gem install brakeman && brakeman --no-pager -q
gem install bundler-leak && bundle-leak check --update
gem install next_rails && bundle_report outdated
gem install libyear-bundler && libyear-bundler --all
COVERAGE=true bundle exec rspec
gem install rubycritic && rubycritic app lib --no-browser --format console
gem install skunk && skunk app lib
gem install rails_stats && rails-stats

That’s a lot of commands to remember and run. And then you need to interpret all the output and compile it into a coherent report.

Some of these steps are more involved than they look.

Getting fresh coverage data, for example, means re-running the whole test suite, and in CI that can also mean downloading and merging resultsets across parallel jobs before Skunk can read them.

The more the audit grows, the more time consuming it becomes.

The Solution: A Tech Debt Audit Skill

We created a Claude Code skill that automates this entire process. Here’s how you could set up your own:

Step 1: Create the Skill Directory

mkdir -p .claude/skills/tech-debt-audit

Step 2: Create the SKILL.md File

A skill is a single SKILL.md file at .claude/skills/tech-debt-audit/SKILL.md. It has two parts: a YAML front matter block at the top that configures the skill, followed by the plain-English instructions Claude follows when you run it.

Here’s what a minimal frontmatter block looks like:

---
name: tech-debt-audit
description: Generate a comprehensive technical debt audit for a codebase.
allowed-tools:
  - Bash(gem install*)
  - Bash(bundle*)
  - Bash(brakeman*)
  - Bash(skunk*)
  - Bash(rubycritic*)
  - Bash(COVERAGE=true*)
  - Read
  - Glob
  - Grep
---

The three keys that matter:

name: the slash command used to invoke the skill (/tech-debt-audit)
description: a one-line summary Claude uses to decide when the skill is relevant
allowed-tools: the commands the skill is permitted to run without prompting, so the audit can install and run each tool unattended

Below the frontmatter code, the instructions tell Claude how to run the audit. There might be key insights you need to tell Claude. For example: You must run your test suite with coverage enabled before running Skunk.

Skunk reads SimpleCov’s coverage data from the coverage/ directory, so without fresh data your SkunkScores will be inaccurate.

You don’t have to write all of this from scratch. The full SKILL.md, including the complete allowed-tools list and a report template, is in the fastruby/tech-debt-skill repository.

Step 3: Run the Audit

Once the skill is set up, you can run it with:

claude /tech-debt-audit

Claude will automatically:

Detect your project type (Ruby/Rails, JavaScript, or both)
Install all required tools
Run the test suite with coverage enabled
Execute each audit tool
Generate a comprehensive report

What the Report Looks Like

The skill produces a single, self-contained HTML report. The screenshots below come from running it against a sample Rails app.

Executive Summary with Health Score

At the top, an executive summary rolls everything up into a single health score and a per-category breakdown:

Security Vulnerabilities

The report lists known advisories from bundler-audit and Trivy, grouped by severity, alongside Brakeman’s static analysis and bundler-leak’s memory-leak check:

Dependency Freshness

It also reports how far behind your dependencies are, using next_rails for the outdated list and libyear-bundler for the freshness metric:

Skunk Score Analysis

The Skunk analysis ranks files by churn-weighted risk, so the ones with high complexity and low coverage rise to the top:

Files with high Skunk scores, high churn, and low coverage by your automated test suite are prime candidates for refactoring or adding tests.

Prioritized Recommendations

Finally, the report distills everything above into a short list of the highest-impact actions:

Why Fresh Coverage Data Matters

During development of this skill, we discovered an important gotcha.

When we first ran Skunk, it reported that newsletter_service.rb had 0% coverage and a SkunkScore of 440.

But after running the test suite with COVERAGE=true bundle exec rspec, the same file showed 67% coverage and a SkunkScore of 145.

The difference?

Skunk reads coverage data from SimpleCov’s .resultset.json file. If that file is stale (or missing), Skunk assumes 0% coverage and penalizes files heavily.

That’s why our skill always runs the test suite first:

# For RSpec projects
COVERAGE=true bundle exec rspec

# For Minitest projects
COVERAGE=true bundle exec rake test

Scoring Guidelines

The skill uses a 100-point scoring system across five categories:

Security (20 points)

20: No vulnerabilities
15: Low severity only
10: Some medium severity
5: High severity issues
0: Critical vulnerabilities

Dependencies (20 points)

20: <10% outdated, <5 libyears
15: <20% outdated, <15 libyears
10: <40% outdated, <30 libyears
5: <60% outdated, <50 libyears
0: >60% outdated or >50 libyears

Coverage (20 points)

20: >90% coverage
15: 70-90% coverage
10: 50-70% coverage
5: 30-50% coverage
0: <30% coverage

Complexity (20 points)

20: No files with complexity >10
15: Few files with complexity 11-20
10: Some files with complexity 21-50
5: Many files with high complexity
0: Files with complexity >50

Maintainability (20 points)

20: Excellent setup, CI, documentation
15: Good setup with minor gaps
10: Adequate but needs improvement
5: Significant maintainability issues
0: Major maintainability problems

Extending the Skill

The beauty of Claude Code skills is that they’re just markdown files. You can easily extend the skill to:

Add JavaScript analysis with npm audit and/or upjs-plato
Include performance metrics from your APM
- If you’re using Sentry, you could integrate this skill with Sentry’s MCP server.
Check for EOL Ruby/Rails versions
Integrate with your CI/CD pipeline

Final Thoughts

Technical debt is inevitable, but it doesn’t have to be invisible. Considering we are all using AI to generate a lot of the code that we ship to production, setting up proper guardrails for humans and robots is crucial.

By automating our tech debt audits with Claude Code, we can:

Get a baseline: Know exactly where you stand before starting any upgrade or refactoring work
Track progress: Run the audit regularly to see if your SkunkScore average is going up or down
Prioritize effectively: Focus on files with high churn, high complexity, and low coverage
Communicate clearly: Share the report with stakeholders to justify technical investments

The skill we built combines the power of tools like Skunk, bundler-audit, Brakeman, and RubyCritic into a single, automated workflow. No more running commands manually or piecing together reports from multiple sources.

Want to try it yourself? The skill is open source at fastruby/tech-debt-skill. Install it into any Rails project with:

mkdir -p .claude/skills
git clone https://github.com/fastruby/tech-debt-skill.git .claude/skills/tech-debt-audit

What tools or metrics would you like to include in your application’s tech debt audit? Send us a comment on social media or open an issue in GitHub!

Need help assessing and paying down technical debt in your Rails application? Contact us for a tech debt assessment!

The Rails Tech Debt Blog

Why To Use A Multi-Stage Dockerfile

What is a Multi-Stage Dockerfile?

Why Use a Multi-Stage Dockerfile?

Performance

Security

Tips and Common Pitfalls

Conclusion

Measuring Test Code Coverage For Non-Ruby Runners

Sample Application

Approach Summary

The Details

Minitest Code Coverage

Coverband Standalone Server

Running Cypress Tests

Extracting the Code Coverage from Coverband

Merging Results

Conclusion

Opening a Repo Is Now an Execution Event

Why opening a repo now executes code

Already weaponized: the keyv worm

Why your usual instincts miss it

Why this lands on Rails teams

What to check before you open a repo

Conclusion

Why Your Yarn App Suddenly Looks for Bun

The Short Version

How We Ran Into It

What’s Actually Happening

Where the Regression Came From

Merged Is Not Yet Released

Conclusion

Running a Ruby MCP Server in Production

From subprocess to service

Two shapes for a server

Sessions, and the trap in the Ruby SDK

Host and Origin are not optional

From a shared token to OAuth

Limiting what a caller can reach

Testing

Conclusion

Why Patching the Gem Didn’t Fix CVE-2026-66066

The CVE, and why the gem bump isn’t the whole fix

The proof: same gem, two images

Rebuilding the image isn’t always enough

The image that quietly stays vulnerable

Conclusion

Migrating from sass-rails to Dart Sass

Historical context

Why keep using Dart Sass?

What Changes in Dart Sass

/ division operator deprecated (biggest breaking change)

@import deprecated in favor of @use and @forward

Other breaking changes

Using the Migrator

A few Rails tips

Conclusion

Tracking LLM Latency & Cost with Rails Events

Why instrument LLM calls?

The starting point: an uninstrumented service

Emitting a structured event around the call

Listening with a subscriber

From tokens to dollars

Attributing calls to features and users

A reusable instrumentation helper

Capturing the failures

Feeding a data warehouse

Best practices for LLM events

Conclusion

Rake Beyond Rails: A Build Tool You Know

What Makes Rake a (great) Build Tool?

Rails and Rake: Clearing Up the Overlap

Types of Tasks You Can Automate in a Rails Project Using Rake

Setup & Bootstrapping

Database Maintenance

Development Workflow

Operations & DevOps

File & Content Automation

Advanced Rake Techniques

Passing Arguments to Tasks

`/` division operator deprecated (biggest breaking change)

`@import` deprecated in favor of `@use` and `@forward`