DEV Community: Hans Schnedlitz

One Version to Rule Them All

Hans Schnedlitz — Sun, 11 Jan 2026 12:58:00 +0000

Managing different tools in your modern Ruby on Rails application can be a pain. You definitely use Ruby. You probably use Node, and some package manager - npm, pnpm or whatever - to go along with it. Locally, managing versions for all these tools is made easy by tools like Mise or ASDF.

# Your local tool versions via Mise
[tools]
ruby = "4.0.0"
node = "25.2.1"
pnpm = "10.18.3"

Unfortunately, managing those versions locally is only part of the equation. You do use CI, right? Your Continuous Integration environments - for example, GitHub Actions - should obviously use the same tool versions.

test:
  runs-on: ubuntu-latest
  steps:
    - name: Checkout code
      uses: actions/checkout@v6

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: '4.0' 
        bundler-cache: true

    - name: Install pnpm
      uses: pnpm/action-setup@v4
      with:
          version: "10.18.3"

    - name: Set up Node
      uses: actions/setup-node@v4
      with:
        node-version: '25.2.1'
        cache: pnpm

The same is true for your deployments. If you use Kamal that usually means updating your Dockerfile.

ARG RUBY_VERSION=4.0.0
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

# Base image setup goes here...

FROM base AS build

ARG NODE_VERSION=25.2.1
ARG PNPM_VERSION=10.13.1

# ...

ENV PATH=/usr/local/node/bin:$PATH
RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \
  /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \
  npm install -g pnpm@${PNPM_VERSION} && \
  rm -rf /tmp/node-build-master

# ...

That’s a bunch of versions to update across a number of places. Like I said, a bit of a pain to maintain.

Let’s Fix This Mess

Obviously, there are ways to improve this situation. Some GitHub actions support reading from a central file. setup-ruby can read mise.toml - but setup-node can not, at least for now. You can read pnpm versions directly from your package.json file - but that doesn’t really help us, does it now? There just isn’t one standard that allows us to specify each version once, in a single place.

I’m aware of jdx/mise-action. It’s a fix in theory - at least for GitHub actions, but I’ve found it lacking in practice. For one, it supports caching the tool setup itself - but not caching dependencies installed by those tools. The specialized actions do to that quite well. Also, different steps or workflows only need some tools. It is rare that I need to install all the tools defined in mise.toml for every workflow and step.

Now, there’s also Docker and Kamal, and matching versions there is a different story altogether. You can use Kamal build arguments to centralize versions for Docker - but for now that just moves the versions to manage to deploy.yml instead of our Dockerfile.

builder:
  arch: amd64
  cache:
    type: gha
  args:
    RUBY_VERSION: "4.0"
    NODE_VERSION: "25.2.1"
    PNPM_VERSION: "10.18.3"

So what gives? Here’s what I ended up with. We go back to good, old, individual version files for each tool.

# .ruby-version
4.0.0


# .node-version
25.2.1


# package.json
{
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.18.3",
  "devDependencies": { ... },
  "dependencies": { ... }
}

Now, hear me out. Here’s why this works.

Let’s talk about GitHub actions first. Obviously, every specialized setup tool supports reading each specialized version file out of the box. Easy.

  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      # Reads from .ruby-version automatically
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      # Reads from package.json automatically
      - name: Install pnpm
        uses: pnpm/action-setup@v4

      - name: Set up Node
        uses: actions/setup-node@v6
        with:
          node-version-file: .node-version
          cache: pnpm

      - name: Install JavaScript dependencies
        run: pnpm install

Mise is a beast and can work with almost anything you throw at it. Including package.json and specialized version files - the latter out of the box. By using a configuration like this your local setup is now also covered.

[tools]
# Picked up from .ruby-version and .node-version

[settings]
experimental = true

[hooks]
# Enabling corepack will install the `pnpm` package manager specified in your package.json
postinstall = 'npx corepack enable'

[env]
_.path = ['/node_modules/.bin']

That leaves Kamal. And here we can do something fun. Because our version files are simple, we can read from them directly without much of a hassle. And because Kamal supports ERB templating, we can do this.

# Just read the versions from the version files, easy
builder:
  arch: amd64
  cache:
    type: gha
  args:
    RUBY_VERSION: <%= File.read('.ruby-version').strip %>
    NODE_VERSION: <%= File.read('.node-version').strip %>
    PNPM_VERSION: <%= JSON.parse(File.read('package.json'))['packageManager'].split('@').last %>

Want to upgrade Ruby? Change .ruby-version. Want to upgrade Node? Change .node-version. Update pnpm? Change the version in your package.json. Any change will be picked up across all your environments. It’s simple, and it works beautifully.

Ruby on Rails, Claude Code and Worktrees

Hans Schnedlitz — Thu, 10 Jul 2025 11:26:00 +0000

Here’s how I use Claude Code to develop Ruby on Rails applications. Mostly medium sized ones that have been around for a while. No green-field, everything-is-possible, agents-go-wild vibe coding for me. I’ll leave that to others.

I don’t know what I’m doing. Wait, that’s not entirely right. I know what I’m doing when it comes to Rails. I don’t know what I’m doing when it comes to Agentic Coding. But that’s okay, nobody does.

What We’re Working With

The apps I work on are as stock-standard Ruby on Rails as it gets. Some use Bootstrap, some use Tailwind. Some use Postgres, some SQLite. Some have trace amounts of Javascript in them. However, they all follow the default Rails architectural patterns: models, views, and controllers. There are no service objects and no event-based systems.

In this context, Claude works great. It eliminates drudgery. I’ve used it to update a bunch of views after extensive model changes. I’ve used it to make significant updates to models and their validations. I’ve added a lot of translations with Claude. I disable all permission checks, and I’m not alone.

It’s nice. While Claude works on boring stuff, you’re free to do other things. You could grab a coffee. You could play with your kids. Or you could work on the hard stuff that Claude sucks at. You could also start more instances of Claude Code to work on even _more things.

However, that requires some measure of isolation. You certainly don’t want to work on the same code as Claude while it’s doing its thing - that way lies pain.

Isolation with Worktrees

Using git-worktrees you create a new branch that is contained within a specific folder. Then, you start an instance of Claude Code in that folder, and it won’t interfere with the rest of your codebase. Voila, you’ve achieved perfect isolation. I didn’t figure this one out myself, by the way. I just read the manual.

I like to keep the /worktrees directory within my project folder. I found that I can make my life a lot easier by doing some scripting and by using Tmux. Here’s a simplified version of a script I’m using to start a new Claude Code instance with a new prompt, on a new branch, in it’s own worktree.

WORKTREES_DIR="./worktrees"

create_worktree() {
  local feature_description="$1"
  local prompt="$2"

  local text=${feature_description// /-}
  text=$(echo "$text" | tr '[:upper:]' '[:lower:]')
  local date
  date=$(date +"%y-%m")
  local branch_name="$date-$text"

  local worktree_path="$WORKTREES_DIR/$branch_name"

  tmux split-window -t "worktrees" -c "$worktree_path" "echo '$prompt' | claude --dangerously-skip-permissions"
}

create_worktree "$@"

So here’s what I usually do. I have a Tmux session running for my Rails project. When I want to offload some work to Claude I start a new Tmux Window/Pane using this little helper script and let it go wild. I might check in periodically, while I keep working on a different branch in my main window. Mostly I rely on hooks, though, to notify me when Claude is done.

Now, what to do with the code that our friendly AI spit out?

Review Time

With Rails, I found that automated checks only go so far. I like to test things - especially if there’s view changes involved. I could have Claude open a PR and review that, but that doesn’t do it for me. I want to switch to the branch, run a diff, and start Rails on the branch to verify the results.

Once again, we can leverage Tmux - and it’s good friend Tmuxinator. I create a new local .tmuxinator file in each of my projects. This gives me the flexibility I need. Every project is different.

name: worktree
root: <%= @args[0] %>
on_project_start: yarn install

windows:
  - editor:
      panes:
        - vim: nvim
  - background:
      layout: tiled
      panes:
        - server: PORT=$(nextport 3000) bundle exec foreman start -f Procfile.dev

To avoid port conflicts with already running Rails servers, I use a simple script to get the next open port. Then, we can start reviewing by running tmuxinator start --append worktree <path-to-worktree>.

Now I can make manual changes if necessary using the new editor instance, or tell Claude to open a PR.

What’s next?

I don’t know. Nobody knows; the landscape changes quickly. For Rails apps, within the constraints I’ve outlined, this works wonderfully for now. I’ve run up to three instances of Claude code in parallel. Now, those are rookie numbers, and I gotta get those up - I’m working on it. There are limits on how much you can parallelize in any given code base.

You can find the full script I use to manage worktrees and Claude Code in this repository. Have fun!

Multi Select with Hotwire Combobox

Hans Schnedlitz — Sat, 05 Jul 2025 10:50:00 +0000

Recently, I put some work into lowering the barrier to contributing talks to RubyEvents. Not entirely out of the kindness of my heart, I might add. As the organizer of the Vienna.rb Ruby Meetup, I contribute talk recordings every couple of months.

Previously, that meant updating a bunch of YAML files, and who enjoys manually updating a bunch of YAML? I certainly don’t.

Less YAML, More Forms

RubyEvents now provides a simple form where you can fill in event and talk details and automatically generate the needed YAML. Then you just copy paste and open a PR.

Part of that form is the selection of speakers. In the initial implementation, you would simply enter a comma-separated list of names.

Now, wouldn’t it be nice if you could search and get speakers auto-suggested? Yes, it would, and yes, indeed it is! Following Adrian Poly’s suggestion, I used Hotwire Combobox. This is what the final result looks like.

I’m not going to lie, implementation wasn’t as straightforward as I would have hoped. Hotwire Combobox isn’t huge on documentation - “just read the source code” is the motto here. If you’re as stumped as I was, this post may help.

Basics First

To simplify the input of speaker names and provide a pleasant user experience, we have a couple of requirements.

We want to search for speakers by name
We want to be able to select multiple speakers
We must be able to add new speakers by entering arbitrary text
Speaker names should be used in the final YAML

Let’s tackle these one by one. We start simple. By following the instructions in the README or Justin Searl’s excellent tutorial, we can get up and running quickly. Let’s add basic auto-completion for speaker names first.

# app/controllers/templates_controller.rb
def speakers_search
  @speakers = Speaker.canonical
  @speakers = @speakers.ft_search(search_query) if search_query
  @speakers = @speakers.limit(100)
end


# app/views/templates/speakers_search.turbo_stream.erb
<%= async_combobox_options @speakers %>


# app/views/templates/new.html.erb -->
<%= form.combobox :speakers, speakers_search_templates_path %>


# app/models/speaker.rb
def to_combobox_display
  name
end

This works great. We can search for and auto-complete speaker names.

Multi Selection with Hotwire Combobox

Now, let’s tackle multi-selection. Sadly, there are no pointers on how to implement this on the Hotwire Combobox Homepage. Time to go spelunking in the source code. Thankfully, there are tons of examples in the test/dummy app. One of them shows us how to add multi-selection.

We need to pass multiselect_chip_src and use the combobox_selection_for_chips helper to render selected items.

# app/views/templates/new.html.erb -->
<%= form.combobox :speakers,
    speakers_search_templates_path,
    multiselect_chip_src: speakers_search_chips_templates_path %>


# app/controllers/templates_controller.rb
def speakers_search_chips
  @speakers = Speaker.find(params[:combobox_values].split(","))
  render turbo_stream: helpers.combobox_selection_chips_for(@speakers)
end

Hotwire Combobox does the heavy lifting for us. We get a nice looking result without much of a fuss.

Free Text and Combobox Value

This solution already works wonderfully for existing speakers. However, remember that we also want to be able to add new speakers. To do so, we’ll need to add free_text and name_when_new.

We also need to make some modifications to the controller. A free-text name isn’t an actual speaker model - Hotwire Combobox can’t work with that. So we’ll need to do some manual mapping. This is based on these helpful examples in the source code.

# app/views/templates/new.html.erb 
<%= form.combobox :speakers,
    speakers_search_templates_path,
    multiselect_chip_src: speakers_search_chips_templates_path,
    name_when_new: "template[speakers]",
    free_text: true %>


# app/controllers/templates_controller.rb
def speakers_search_chips
  @speakers = params[:combobox_values].split(",").map do |value|
    Speaker.find_by(id: value) || OpenStruct.new(to_combobox_display: value, id: value)
  end
  render turbo_stream: helpers.combobox_selection_chips_for(@speakers)
end

Now, the last missing piece is the ability to control the checkbox’s value. By default, Hotwire Combobox uses the ID of records. We allow free_text, so our combobox values may be a mix of IDs and Strings.

<input 
  type="hidden"
  name="template[speakers]" 
  value="4,2887,784,Your Name?"
  id=...
>

To generate a YAML with speaker names, we are only interested in their names. Now, we could do some mapping in the controller, but there is a more straightforward way. We can provide a proc to the combobox helper to map the value from IDs to whatever we need.

# app/views/templates/speakers_search.turbo_stream.erb
<%= async_combobox_options @speakers, value: proc { |element| element.name } %>

If you are curious about more details, check out the PR to RubyEvents.

Using Jekyll with Esbuild

Hans Schnedlitz — Fri, 09 Feb 2024 09:00:00 +0000

I know. What an unholy union. Why would anyone do this? Why would anyone want that?

Well, first for science. Obviously.

Second, believe it or not, there are actual good reasons for combining Esbuild with Jekyll. I like Jekyll. It’s mature, has many plugins, and a vibrant ecosystem. Also, it’s built on Ruby, and Ruby is fantastic. Most importantly, it’s simple.

But.

Sometimes, you want that extra bit of visual oomph. Sometimes, you want to do weird or cool things, and a bundler might be necessary under those circumstances. Esbuild is modern and efficient. If you’re working with Ruby on Rails, you might already be used to it. Coincidentally, it’s also simple. Relatively speaking.

If you look at it like that, maybe Jekyll and Esbuild are meant to work together after all?

Why not Hugo? Or Bridgetown? Or any other static site generator that’s not Jekyll? Look, I don’t know what else to say. For science. I like Jekyll. It works for me 🙃

What we’ll do

The idea is this. We want to use Esbuild for bundling JS and CSS and let Jekyll take care of the rest. We’ll also add some plugins to Esbuild (autoprefixer, build-sass-plugin, postcss). First, so we can keep using the SCSS that Jekyll already provides, second for demonstration purposes.

We’ll also make sure we end up with a pleasant developer experience. Jekyll and Esbuild might not want to play nice, but we’ll make them 😈

Getting set up

Heads up! This guide assumes you have Ruby, Bundler, and Node set up on your machine. Also, Jekyll should already be installed. If that’s not the case, take care of that before you continue.

We’ll forego any plugins and start with an empty Jekyll scaffold to keep things simple.

jekyll new jekyll-esbuild --blank && cd jekyll-esbuild

Let’s create an empty Javascript file for demonstration purposes. Let’s also install Esbuild and the plugins we are going to use.

mkdir assets/javascript && touch assets/javascript/main.js
npm i -D --save-exact esbuild
npm i -D autoprefixer esbuild-sass-plugin postcss

When we run jekyll serve --watch we should see something on localhost:4000.

Bundling Assets with Esbuild

To use Esbuild with our CSS plugins, using the command line won’t do. We’ll have to create a small build script.

// scripts/build.mjs

import esbuild from "esbuild";
import { sassPlugin } from "esbuild-sass-plugin";
import postcss from "postcss";
import autoprefixer from "autoprefixer";

await esbuild.build({
  entryPoints: ["assets/css/main.scss", "assets/javascript/main.js"],
  outdir: "_site/assets",
  bundle: true,
  plugins: [
    sassPlugin({
      async transform(source) {
        const { css } = await postcss([autoprefixer]).process(source, {
          from: undefined,
        });
        return css;
      },
      loadPaths: ["_sass"],
    }),
  ],
});

Once we update our package.json, we can build our assets.

{
  "devDependencies": {
    ...
  },
  "scripts": {
    "build": "node scripts/build.mjs",
  }
}

If we were to run npm run build now, we’d get an error. Our assets/main.scss still contains YML markup that we need to remove.

--- <<< DELETE ME
--- <<<

@import "base";

After that, we should be able to build assets without any issues.

Configuring Jekyll

Now, if you keep a close eye on the _site folder and make some changes to any watched files, you’ll notice that your built files will be changed. Makes sense because, as things stand, Jekyll still feels responsible for assets, thus overwriting or deleting the files created by Esbuild.

Let’s fix that. The simplest way to tell Jekyll to not worry about CSS and JS assets is to exclude the respective folders by updating _config.yml.

exclude:
  - _sass # Let build handle CSS
  - assets/css # Let build handle CSS
  - assets/javascript # Let esuild handle JS
  - scripts
  - package.json
  - package-lock.json
keep_files:
  - assets/css # Let build handle CSS
  - assets/javascript # Let esuild handle JS

Notice that we also told Jekyll to not delete CSS and JS assets when rebuilding. We also excluded some additional files that our Jekyll site doesn’t need. See configuration options if you need more details.

This won’t do if you’re using a theme. By excluding asset folders, theme styles won’t be processed appropriately. There are ways to fix that, but it’s a bit much for this blog post.

Let’s bundle and serve again to make sure everything is still working.

npm run build
jekyll serve --watch

Changing anything (e.g. CSS) will no longer overwrite files created by Esbuild. Success! Unfortunately, our changes won’t be reflected on your site. Let’s change that by adding watch mode to Esbuild.

Improving Developer Experience

Until the beginning of 2023, adding watch mode was a simple matter of adding watch: true to the arguments of Esbuild. Now, it’s a bit different. I opted to change the script behavior based on input arguments, but you can also create a separate script.

The updated scripts/build.mjs looks something like this:

const args = process.argv.slice(2);
const watch = args.includes("--watch");

const context = await esbuild.context({
  // ...
});

if (watch) {
  context.watch();
  console.log("Watching!");
} else {
  context.rebuild();
  context.dispose();
  console.log("Build done!");
}

After updating package.json once again, we can start watching our file changes by running npm run watch.

{
  "devDependencies": {
    ...
  },
  "scripts": {
    "watch": "node scripts/build.mjs --watch"
  }
}

We’re already using Ruby anyway, so we might as well use Foreman to run everything we need with a simple command. Note that I also added browser-sync for live reloading to the Procfile.

jekyll: jekyll serve --watch
build: npm run watch
browser: browser-sync start --proxy localhost:4000 --files "**/*"

Run foreman start and your site should reload whenever you change your CSS, JS, or content. Mission accomplished!

The Simplest Static Site Generator

Hans Schnedlitz — Sun, 07 Jan 2024 17:42:16 +0000

Sometimes, you want to build a simple HTML page and populate it with some data. You may have some JSON lying around and want to make a simple website to visualize its contents. Or perhaps you want to show off how many books you read in the last few years.

In any case, we’re talking about a small set of data and a single HTML page here. Would you use a static site generator for that? Which one? Jekyll? Hugo, Gatsby? Isn’t that overkill for what we’re trying to do?

I was pondering questions like this when I came across Pandoc Templates. Turns out there is a way to generate static sites that is much simpler than most other options out there.

Alright, this might not be the absolutely simplest way to generate a static site. You got me. I bet someone, somewhere builds their static sites using a one-line Perl script. Jokes aside, let me know if you find an even simpler approach to building static sites.

Enter The Template

A Pandoc template is not much to look at. It’s just an HTML file filled with some special syntax sprinkled in. Syntax that allows you to write conditionals or loops as well as do some other stuff. Let’s say we want to list authors and their respective books to simplify things. To do so, let’s create template.html:

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="date" content="$date-meta$" />
    <title>$title$</title>
  </head>
  <body>
    <section>
      $for(authors)$
      <h2 class="author">$authors.name$</h2>
      <ul>
        $for(authors.books)$
        <li class="book">
          <a href="$authors.books.link$">$authors.books.name$</a>
        </li>
        $endfor$
      </ul>
      $endfor$
    </section>
  </body>
</html>

Now that we have a template, we must populate it with some data. I’ve found the most uncomplicated way to do so is to create a markdown file that contains the data as metadata. We keep our data in authors.md.

---
title: "Authors and their Books"
authors:
  - name: James S.A. Corey
    books:
      - name: Leviathan Wakes
        link: https://www.goodreads.com/book/show/8855321-leviathan-wakes
      - name: Leviathan Falls
        link: https://www.goodreads.com/book/show/28335699-leviathan-falls
  - name: Margaret Atwood
    books:
      - name: The Handmaid's Tale
        link: https://www.goodreads.com/book/show/38447.The_Handmaid_s_Tale

---

I found Markdown documents with embedded metadata easy enough to work with. If you prefer specific JSON or YML files, you can use the --metadata-file flag to pass them to your template. See also the other reader options.

Then, run Pandoc to generate your static site. And that’s it.

pandoc --standalone --template template.html authors.md -o index.html

I’ll take Pandoc over other options every day of the week for this particular use case. What about you?

I Don’t Want to Install Pandoc!

I know, right? I don’t want to either. Let’s use Docker instead. Put this into your .aliases and use pandock rather than pandoc.

alias pandock='docker run --rm -v "$(pwd):/data" -u $(id -u):$(id -g) pandoc/latex'

Continuous Deployment with GitHub Actions and Kamal

Hans Schnedlitz — Sun, 07 Jan 2024 17:27:03 +0000

Kamal is a wonderfully simple way to deploy your applications anywhere. It will also be included by default in Rails 8. Kamal is trivial, but I don’t recommend using it on your development machine.

From experience working on an oldish laptop, I can tell you that building Docker images locally is not fun. Also, why would you, when GitHub Actions are for free!

In this post, I’ll show you how to build a simple CI pipeline with Kamal. We’ll create an application image and deploy it on every push. We’ll also add some simple image caching to speed up the workflow.

The Complete Workflow

This is what we’ll end up with at the end of this post.

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  Deploy:
    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest

    env:
      DOCKER_BUILDKIT: 1
      RAILS_ENV: production

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: hschne
          password: ${{ secrets.DOCKER_REGISTRY_KEY }}

      - name: Set Tag
        id: tag
        run: |
          echo "tag=$(git rev-parse "$GITHUB_SHA")" >> $GITHUB_OUTPUT

      - name: Build image
        uses: docker/build-push-action@v5
        with:
          context: .
          builder: ${{ steps.buildx.outputs.name }}
          push: true
          labels: |
            "service=anonymous-location"
          tags: |
            "hschne/anonymous-location:latest"
            "hschne/anonymous-location:${{ steps.tag.outputs.tag }}"
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - uses: webfactory/ssh-agent@v0.7.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - name: Deploy command
        run: bundle exec kamal deploy --skip-push
        env:
          RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
          KAMAL_REGISTRY_PASSWORD: ${{ secrets.DOCKER_REGISTRY_KEY }}

That’s something. Well, nobody ever said GitHub actions are succinct. Let’s look at what’s going on here step by step.

Step By Step

The workflow above is based on the one in this post. Unfortunately, that post is so old that it still refers to Kamal as Mrsk. I had to make some adjustments to how the image built and deployed.

I won’t go into details on GitHub Actions specifics. If you’re new to GitHub Actions or unfamiliar with one particular piece of syntax, I recommend you check out the documentation.

To build and deploy our Rails application, we need to provide GitHub actions with three secrets:

RAILS_MASTER_KEY: The master key to your Rails application credentials.
DOCKER_REGISTRY_KEY: The API token for pushing and pulling from your container registry.
SSH_PRVIATE_KEY: The SSH key for accessing the server where your app is deployed.

We’ll also need to set some environment variables. We are building a production image. We’ll also need to instruct the Docker build step to use Docker Buildkit, as that is one of the requirements of Kamal.

env:
  DOCKER_BUILDKIT: 1
  RAILS_ENV: production

Our deployment workflow needs to do a couple of things. First, we need to check out the application source code. Next, we’ll log into Docker Hub to push our image.

- name: Checkout code
  uses: actions/checkout@v3

- name: Set up Docker Buildx
  id: buildx
  uses: docker/setup-buildx-action@v2

- name: Login to Docker Hub
  uses: docker/login-action@v3
  with:
    username: hschne
    password: ${{ secrets.DOCKER_REGISTRY_KEY }}

Kamal uses the git hash of the latest commit to determine which image to deploy, so image tags must match git commit hashes. We define this tag with a separate workflow step.

We use the docker/build-push-action to build the application image. In addition to setting the correct tag, the image build step must also provide a label matching your service name. Because the image should be pushed to your container registry, we set push: true, and because we want ludicrous build speed we instruct the build step to utilize the GitHub Actions cache.

- name: Set Tag
  id: tag
  run: |
    echo "tag=$(git rev-parse "$GITHUB_SHA")" >> $GITHUB_OUTPUT

- name: Build image
  uses: docker/build-push-action@v5
  with:
    context: .
    builder: ${{ steps.buildx.outputs.name }}
    push: true
    labels: |
      "service=service-name"
    tags: |
      "user/image-name:latest"
      "user/image-name:${{ steps.tag.outputs.tag }}"
    cache-from: type=gha
    cache-to: type=gha,mode=max

Once the image has been built and pushed, you only need to trigger the deployment using Kamal. We use the webfactory/ssh-agent to establish a connection to our production server. After installing the required Ruby dependencies, it’s only a matter of running Kamal. As the image is already built and pushed, we use the --skip-push flag.

- uses: webfactory/ssh-agent@v0.7.0
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
- name: Set up Ruby
  uses: ruby/setup-ruby@v1
  with:
    bundler-cache: true
- name: Deploy command
  run: bundle exec kamal deploy --skip-push

And that’s it! If you’ve enjoyed this post or have any other tips on how to use Kamal together with GitHub Actions, let me know! 🙂

Making the Most of Your Logs in Rails

Hans Schnedlitz — Wed, 15 Mar 2023 12:06:34 +0000

Most people only realize the necessity of logs when they need them the most. But when your application breaks, user complaints start flooding in, and you have no clue how to fix it, it's too late to add some log messages that might have helped.

Good logs pay for themselves tenfold. They make it a breeze to diagnose those tricky bugs, and if you do logs right, they can alert you of issues even before your users notice. But what does it mean to 'do logging right'?

Logging is easy to start with but hard to master. In this post, we'll dive into how you can use your Rails application's logs to their full potential.

Logging in Rails

Let's talk about the basics first. When you start a new Rails application, logging is already set up for you. Rails will initialize a new instance of ActiveSupport::Logger that you can use anywhere within your application.

Rails.logger.debug('Hello logs!')

I, [2019-01-04 05:14:33 #123] INFO -- Main: Hello Logs!

The Rails logger writes to the standard output or log/<environment>.log and will automatically log incoming requests or executed queries in addition to any log messages you write explicitly.

There are numerous ways in which you can configure Rails logs, as outlined excellently in the documentation for Rails.

To make the most of our logs, we are especially interested in setting log levels as well as log formatting.

But before tackling that, let's talk about why we should write logs.

Good Logging, Bad Logging

The purpose of logs is to inform you about system events so you can react to them. For example, when an error happens, a log message should tell you about it in a way you can understand.

How well you understand a log message depends on how descriptive and contextual it is. A descriptive log message provides relevant information about what happened. A contextual log message includes information about a system's state when the system wrote it.

Let's consider a simple example to see why we need both. Here is some code that calls an external API and returns its response when a user performs a request.

def call_external_api(user_id, payload)
  Rails.logger.info('Method entered')
  client = Client.new(user_id)
  response = client.request(payload)
  if response.ok?
    Rails.logger.info('Response success')
    return response
  else
    Rails.logger.info('Response failure')
    return response
  end
  rescue ClientError => e
    logger.debug('An error occurred)
end

Now let's imagine a situation where a customer reports an issue, and you look into the logs for help. This is what you might see:

I, [2022-07-10T10:40:34.827604 #100038]  INFO -- : [42f2e074-d53f-41e4-adca-13f59c6383ec] Processing by UserController#action as HTML
I, [2022-07-10T10:40:34.828084 #100038]  INFO -- : [42f2e074-d53f-41e4-adca-13f59c6383ec] Method entered
I, [2022-07-10T10:40:34.933263 #100038]  INFO -- : [42f2e074-d53f-41e4-adca-13f59c6383ec] Response success
I, [2022-07-10T10:40:34.933803 #100038]  INFO -- : [42f2e074-d53f-41e4-adca-13f59c6383ec] Completed 200 OK in 106ms (Views: 0.2ms | Allocations: 2135)
I, [2022-07-10T10:40:35.959454 #100038]  INFO -- : [458a209f-6b0e-4d29-a9b0-449d6ff3d29a] Started GET "/action" for 127.0.0.1 at 2022-07-10 10:40:35 +0200
I, [2022-07-10T10:40:35.959975 #100038]  INFO -- : [458a209f-6b0e-4d29-a9b0-449d6ff3d29a] Processing by UserController#action as HTML
I, [2022-07-10T10:40:35.960081 #100038]  INFO -- : [458a209f-6b0e-4d29-a9b0-449d6ff3d29a] Method entered
I, [2022-07-10T10:40:36.043971 #100038]  INFO -- : [458a209f-6b0e-4d29-a9b0-449d6ff3d29a] Response failure
I, [2022-07-10T10:40:36.044316 #100038]  INFO -- : [458a209f-6b0e-4d29-a9b0-449d6ff3d29a] Completed 200 OK in 84ms (Views: 0.1ms | Allocations: 1297)
I, [2022-07-10T10:42:49.701879 #103892]  INFO -- : [e02c3a8f-c081-40aa-90fb-9d1474126403] Started GET "/action" for 127.0.0.1 at 2022-07-10 10:42:49 +0200
I, [2022-07-10T10:42:49.703400 #103892]  INFO -- : [e02c3a8f-c081-40aa-90fb-9d1474126403] Processing by UserController#action as HTML
I, [2022-07-10T10:42:49.703745 #103892]  INFO -- : [e02c3a8f-c081-40aa-90fb-9d1474126403] Method entered
I, [2022-07-10T10:42:49.775846 #103892]  INFO -- : [e02c3a8f-c081-40aa-90fb-9d1474126403] An error occurred

These log messages provide some information, but not nearly enough. We are no closer to finding out what's responsible for the error the customer has reported. These log messages lack descriptiveness and context. They are noise. How can we improve them?

Log Levels in Rails

The default Rails logger provides the log levels DEBUG, INFO, WARN, and ERROR. Using them, you can group log messages into different categories of relevance. This not only helps you filter log messages, but also provides some context.

It can be challenging to decide when to use which log level. Here are some rules of thumb:

DEBUG: Use this log level for detailed information about actions happening within the system. You may use debug statements when methods are entered or exited, or anywhere you think it may add value during debugging.
INFO: Whenever your system changes its state, or some relevant event occurs, reach for the INFO level. Examples of common info messages in the context of Rails applications are received requests, requests sent to external APIs, or jobs starting and finishing.
WARN: Use this log to signify that something unexpected has happened. It's not a problem yet (because your application can handle it), but if it keeps happening, it might warrant your attention.
ERROR: Use this log level when an error happens. Errors are invalid application states that you must resolve as soon as possible.

You can change the kinds of log messages your application writes by modifying the respective environment file. Normally, Rails will discard DEBUG messages in production, but you can change that.

# config/production.rb
Rails.logger.level = :debug

Let's apply the log-level suggestions above to our code sample.

def call_external_api(user_id, payload)
  Rails.logger.debug('Method entered')
  client = Client.new(user_id)
  response = client.request(payload)
  if response.ok?
    Rails.logger.info('Response success')
    return response
  else
    Rails.logger.warn('Response failure')
    return response
  end
  rescue ClientError => e
    logger.error('An error occurred')
end

When debugging, we can now identify root causes for issues by looking into WARN and ERROR messages. Sadly, our log messages haven't gotten any more descriptive.

Descriptive Log Messages

Descriptive log messages leave no room for interpretation. They provide the details necessary to give the reader instant knowledge about what happened.

When you read messages such as 'An error occurred', you are left wondering what the error is. You want to avoid such confusion when writing your log messages. The most important thing when writing descriptive log messages is to put yourself in the shoes of the log reader. Will they get all the information they need when reading your logs?

Let's change the message 'An error occurred' to the error itself, including its message.

logger.error { "#{e}: #{e.message}" }

That's an improvement. Let's check the other log messages in our example. 'Method entered' doesn't tell us which method was called, 'Response success' leaves out the actual response, and 'Response failure' provides no information about the nature of the failure. Let's change that.

def call_external_api(user_id, payload)
  Rails.logger.debug('Calling external api')
  client = Client.new(user_id)
  response = client.request(payload)
  if response.ok?
    Rails.logger.info { "Request success, received #{response.body}" }
    return response
  else
    Rails.logger.warn { "Request returned #{response.code}, #{response.body}" }
    return response
  end
  rescue ClientError => e
    logger.error { "#{e}: #{e.message}" }
end

Note: You might have noticed we use the block syntax when performing string interpolation with our logs. Using it avoids unnecessary computation when the application's log level is higher than the log messages' level. For example, log.debug("Some #{concatenation}") will always perform the string concatenation, but log.debug { "Some #{concatenation}" } will only do so when the log level is set to debug.

I, [2022-07-30T11:19:13.742108 #122944]  INFO -- : [29d1ced1-3d05-4fbf-8b75-2a50e87ad749] Started GET "/users" for 127.0.0.1 at 2022-07-30 11:19:13 +0200
I, [2022-07-30T11:19:13.743058 #122944]  INFO -- : [29d1ced1-3d05-4fbf-8b75-2a50e87ad749] Processing by UsersController#index as HTML
D, [2022-07-30T11:19:13.743248 #122944] DEBUG -- : [29d1ced1-3d05-4fbf-8b75-2a50e87ad749] Calling external api, user 1, payload {:search=>"name"}
I, [2022-07-30T11:19:13.844355 #122944]  INFO -- : [29d1ced1-3d05-4fbf-8b75-2a50e87ad749] Request completed. Received {"userId"=>1, "id"=>1, "title"=>"title", "completed"=>false}
I, [2022-07-30T11:19:13.844836 #122944]  INFO -- : [29d1ced1-3d05-4fbf-8b75-2a50e87ad749] Completed 200 OK in 102ms (Views: 0.2ms | Allocations: 2195)
I, [2022-07-30T11:20:09.501016 #123422]  INFO -- : [598eb218-d3c9-4e92-9236-13281cc660af] Started GET "/users" for 127.0.0.1 at 2022-07-30 11:20:09 +0200
I, [2022-07-30T11:20:09.502518 #123422]  INFO -- : [598eb218-d3c9-4e92-9236-13281cc660af] Processing by UsersController#index as HTML
D, [2022-07-30T11:20:09.502848 #123422] DEBUG -- : [598eb218-d3c9-4e92-9236-13281cc660af] Calling external api, user 1, payload {:search=>""}
W, [2022-07-30T11:20:09.574884 #123422]  WARN -- : [598eb218-d3c9-4e92-9236-13281cc660af] Request failed with 400: Empty search
I, [2022-07-30T11:20:09.575415 #123422]  INFO -- : [598eb218-d3c9-4e92-9236-13281cc660af] Completed 200 OK in 73ms (Views: 0.2ms | Allocations: 2106)
I, [2022-07-30T11:20:41.229494 #125518]  INFO -- : [77b70a25-268c-43ea-a3da-8788086165f2] Started GET "/users" for 127.0.0.1 at 2022-07-30 11:20:41 +0200
I, [2022-07-30T11:20:41.230735 #125518]  INFO -- : [77b70a25-268c-43ea-a3da-8788086165f2] Processing by UsersController#index as HTML
D, [2022-07-30T11:20:41.231039 #125518] DEBUG -- : [77b70a25-268c-43ea-a3da-8788086165f2] Calling external api, user 1, payload {:search=>"long name"}
E, [2022-07-30T11:20:41.301237 #125518] ERROR -- : [77b70a25-268c-43ea-a3da-8788086165f2] Request timeout exceeded
I, [2022-07-30T11:20:41.301878 #125518]  INFO -- : [77b70a25-268c-43ea-a3da-8788086165f2] Completed 200 OK in 71ms (Views: 0.3ms | Allocations: 2085)

Our logs read much better now. There is little doubt about what each log message signifies.

Further Context for Log Messages

Our new log messages provide a clear picture of what happened. Because this is a simple example, we also have a good understanding of why certain things happened. In reality, it's usually not that easy.

Providing additional information about the context in which the system wrote each message can significantly help with debugging.

For example, when logging requests or responses, it may be helpful to know who performed the request. Attaching a stack trace for errors might be useful so we can gather additional information about why the error occurred.

def call_external_api(user_id, payload)
  Rails.logger.debug { "Calling external API. user_id: #{user_id}, payload: #{payload}" }
  client = Client.new(user_id)
  response = client.request(payload)
  if response.ok?
    Rails.logger.info { "Request completed. Received #{response.parsed_response}. user_id: #{user_id}, payload: #{payload}" }
    return response
  else
    Rails.logger.warn { "Request failed with #{response.code}: #{response.parsed_response}. user_id: #{user_id}, payload: #{payload}" }
    return response
  end
  rescue ClientError => e
  logger.error("#{e.message} (#{e.class}), #{ e.backtrace.drop(1).map { |s| "\t#{s}" } }")
end

Note: You have likely noticed that creating log messages with contextual information can be cumbersome when you use Rails' default logger. Luckily, custom loggers such as Ougai or MrLogaLoga make this a lot easier.

Structured Logging

Once you've made your logs readable for humans, you are ready to take things to the next level. You now need to make your logs readable by machines so you can use them for monitoring and data analysis.

My go-to format is JSON, but depending on which tools you use, you may prefer other log formats such as Logstash. You can change the format of your log messages by creating a custom log formatter.

# lib/json_log_formatter.rb
class JsonLogFormatter < ::Logger::Formatter
  def call(severity, time, progname, msg)
    json = { time: time, progname: progname, severity: severity, message: msg2str(msg) }
      .compact_blank
      .to_json
    "#{json}\n"
  end
end

# application.rb
config.log_formatter = JsonLogFormatter.new

{"time":"2022-08-07T18:57:20.261+02:00","severity":"INFO","message":"Request completed" }

Rather than writing custom formatters yourself, you can use one of the many gems that provide custom log formatters. I recommend Lograge, which not only offers out-of-the-box formatting but also cleans up Rails' somewhat verbose request formatting so it's much easier to read.

Rails Logging with AppSignal

Now that your logs are nice and readable, it would be nice to make them more accessible. After all, you don't want to SSH into some machine and tail or grep the logs there, right?

Luckily, AppSignal has recently launched a logging feature in beta! This allows you to inspect and analyze Rails logs directly in the AppSignal web interface.

You can access our logging beta through the 'Logging' tab in the left-hand side menu:

If you follow the steps in our Ruby logging docs, you can configure the Rails Logger to use the AppSignal::Logger class by placing the code below in the config/environment.rb file before initialization:

# Use AppSignal's logger
Rails.logger = Appsignal::Logger.new("rails")

# Initialize the Rails application.
Rails.application.initialize!

You can also ingest structured logs in JSON format or with Lograge.

Once you've set everything up, you should see your Rails logs show up on AppSignal!

Logging and Error Reporting

You're reading this on the AppSignal blog, so you might wonder: why should I care about logging if I'm already using a nice error reporting platform?

It's a good question. Error tracking tools provide detailed information about application errors. They capture the full stack trace of any application error and provide lots of contextual information out of the box.

However, while most tools allow you to capture events other than errors, sending these tools an arbitrary amount of messages is generally infeasible. You won't be able to replace the detailed, historical information that well-written logs provide.

In reality, well-written logs augment and support error tracking tools. You should likely use both.

Wrap Up

In this post, we looked into how you can get the most out of your logs. We saw that getting started with logging in Rails is easy, but writing useful
logs can be challenging.

Logs that lack descriptiveness or context will end up just filling up your disk while providing little value. However, logs that use the correct log levels and provide readers with the information they need are a great asset.

Once you've mastered writing great log messages, you can take things further and format them in a way that allows for log analysis and easy filtering.

We also explored how you can use AppSignal's new logging feature to access your logs easily. Finally, we touched on how logs should augment error tracking tools rather than replace them.

Happy logging!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Add Feature Flags in Ruby on Rails with Flipper

Hans Schnedlitz — Thu, 16 Jun 2022 11:18:58 +0000

Picture this scenario: you are a Rails developer and have spent the last couple of days developing that awesome feature that everyone is waiting for. It's big and complex, but it went through rigorous testing, so you are confident everything works as it should. There are deadlines to meet, so you deploy. Immediately, all hell breaks loose.

Your feature straight up breaks the entire app for some of your users. It's hard to say why. No bugs showed up during testing. You revert your change, but the damage has been done. Your customers aren't happy, and you will spend the foreseeable future doing damage control and investigating what went wrong.

The problem is that releasing complex changes is inherently risky, no matter how much testing you do. It would have been nice if you had rolled this feature out gradually, maybe only to a handful of users first. It would have been even better if you could have switched the feature off as soon as the first problem showed up.

This is precisely where feature flags come in. In this post, we'll dive into the ins and outs of feature flags in Rails, including how to set them up using the Flipper gem. But first: what are they?

What Are Feature Flags in Ruby on Rails?

Feature flags are a way to enable or disable a feature in your application while it is running. If a flag is enabled, the feature is used. Otherwise, it is not. Imagine something like this in pseudocode.

if feature_enabled?(:my_awesome_feature)
  # Run awesome feature code
else
  # Not so awesome code
end

The name 'feature flag' is somewhat misleading. Controlling application behavior at runtime is not limited to features,
but applies to any function within your program. You can use feature flags to try out performance tweaks and run A/B tests, for example.

A significant difference between a feature flag and any other old conditional is you can modify feature flags at runtime.

For illustration purposes, let's imagine a simple feature flagging mechanism using environment variables.

def feature_enabled(feature_name)
  ENV[feature_name.to_s.upcase]
end

By modifying the value of the environment variable, we can switch parts of our application on or off at will. Which part of an application? Anything you want!

You could hide parts of the UI if a feature is disabled. You could switch out parts of your code, which is very useful if you aren't confident in your latest refactor. One of my favorite uses of feature flags is to hide entire routes using routing constraints:

# lib/constraint/feature_constraint.rb
class FeatureConstraint
  def initialize(feature)
    @feature = feature
  end

  def matches?(_request)
    feature_enabled?(@feature)
  end
end

# config/routes.rb
Rails.application.routes.draw do
  get 'statistics', to: 'statistics#index', constraints: FeatureConstraint.new(:statistics)
end

We can already see that there are lots of applications for feature flags. Our naive implementation has one significant weakness, though. A feature is either on or off for every user.

What if we want the ability to enable features only for specific users or groups of users, or only for some of the time? Let's take a look at Flipper.

Using the Flipper Gem for Feature Flags

Flipper is a gem that makes feature flags and different ways to toggle them
available in Rails. It is highly modular. Apart from the main gem, you'll also have to pick a storage adapter — but more on that later. Let's use the ActiveRecord adapter for now.

Add the following lines to your Gemfile and run bundle install:

gem 'flipper'
gem 'flipper-active_record'

When we use the ActiveRecord adapter, Flipper will store your feature flag in the database and thus requires setting up new database tables. Flipper comes with a handy generator that will create the necessary migrations.

rails g flipper:active_record
rails db:migrate

You can use Flipper in the same way as the naive implementation we used previously.

if Flipper.enabled?(:my_awesome_feature)
  # Run awesome feature code but with Flipper!
else
  # Not so awesome code
end

The big difference is that instead of modifying environment variables, you now get to toggle features using Flipper's user interface. Add the Flipper UI gem and install it.

gem 'flipper-ui'

Modify your routes file to mount Flipper UI.

Rails.application.routes.draw do
  mount Flipper::UI.app(Flipper) => '/flipper'
end

If you start your application and navigate to the Flipper UI, you will see an overview of all available features and their status. Go ahead and create a my_awesome_feature feature.

Feature Toggles in Flipper

You've probably noticed that you can do much more than simply enable or disable a feature in Flipper UI. Flipper allows us to enable features for a subset of users or even for a percentage of the time. You can configure your feature flags using one of five different mechanisms.

One of them is the boolean toggle, a global on-off switch. The other four are a lot more interesting than that: groups, actors, percentage of actors, and percentage of time.

Groups

To enable a feature only for a particular group of users, use the group toggle. If it doesn't exist, create the file config/initializers/flipper.rb and add the following code to register a new group — for example, paid users.

# config/initializers/flipper.rb
Flipper.register(:paid_users) do |actor, _context|
  actor.respond_to?(:paid_users?) && actor.paid?
end

To use this new toggle, modify the Flipper invocation to pass the user — or actor, as the documentation likes to call them — and the feature name.

if Flipper.enabled?(:my_awesome_feature, user)
  # Run awesome feature only if the user is paid
else
  # Not so awesome code
end

Flipper will use the block you defined in the initializer to decide if the feature is enabled for this user. In this case, it will invoke the paid? method. You can now use this group in Flipper UI. Click the 'Add a Group' button and select your group.

Your group doesn't have to be paid users. It could be members of your team or users who have signed up for a beta program. Using the group toggle is helpful if you want to release something to a subset of users. Imagine beta releases or internal releases.

Actors

Sometimes, you might want to release something to a single individual. In this case, the actor toggle is something to consider.

You don't have to change anything in your initializer to use this mechanism. However, you'll need to ensure that your actor model — which will be your user model most of the time — implements flipper_id. Including Flipper::Identifier takes care of that.

# models/user.rb
class User < ApplicationModel
  include Flipper::Identifier
end

User.create.flipper_id # User;1

You can then use this ID to enable a feature for individual users.

This feature toggle is handy if you want to preview functionality for particular individuals. Think about enabling specific test accounts for partners who need access to a feature before it's released to a broader audience.

Percentage of Actors

If you want to ramp up feature usage slowly, the percentage of actors toggle is for you. Imagine you've implemented some performance optimization, and you're not quite sure how it will behave in production. You would roll this out to a small percentage of users first and then slowly ramp up the usage while monitoring your application.

If things go sideways, you can always reset the percentage to zero.

Percentage of Time

Last but not least, you may enable a feature for a percentage of requests. You do not need to provide an actor when using this toggle.

if Flipper.enabled?(:my_awesome_feature)
  # Run awesome feature code only for a percentage of requests
else
  # Not so awesome code
end

I like to use this to compare the performance of two different implementations. Note that this feature toggle is random.
The same user will experience different behavior on each request.

Advanced Configuration in Flipper

We've already seen that we can use the ActiveRecord adapter to store feature flag information in our database. But depending on your specific needs, you might want to use a different adapter.

For the most part, all you need to do when swapping out storage adapters is to install the respective gem and configure Flipper accordingly. For example, if you want to use the Redis adapter, you add the flipper-redis gem to your
Gemfile and update the Flipper initializer.

gem 'flipper-redis'

# config/initializers/flipper.rb
Flipper.configure do |config|
  config.adapter { Flipper::Adapters::Redis.new(Redis.new) }
end

Apart from configuring storage adapters, there are a lot of other aspects of Flipper that you can tweak.

Adding feature flags incurs a slight performance penalty, so you usually want to add memoization and caching. You'll likely also want to restrict access to the Flipper UI to authorized users. These topics are out of scope for this post, but I recommend you check out the Flipper documentation if you want to dive deeper.

Caveats to Feature Flags in Rails

Feature flags are great. But as with so many things, there are tradeoffs to consider.

Adding feature flags and maintaining them adds organizational overhead. Releasing and rolling out hidden features using flags is not as simple as deploying 'regular' code — you'll have to remember to turn it on, of course! That usually isn't too hard, but cleaning up feature flags that you don't need anymore might be.

Every time you add a feature flag to your code, you add a conditional, and if you don't watch out, your code quickly becomes littered with them. Keeping track of when and why you created certain feature flags could be challenging. Sadly, Flipper UI itself does not offer much to manage feature flags.

You should also be aware that using feature flags will incur a minor performance penalty. There are ways to mitigate this, but it can have a noticeable impact if you misconfigure or misuse Flipper.

Wrap Up: Get Started with Feature Flags in Ruby on Rails

We looked at how feature flags can help you release with more confidence, learned how they function in principle, and saw how you can get started with feature flags using the Flipper gem.

There are many situations where feature flags are handy. Depending on your use case, you might reach for one of the five different toggles — boolean, group, actor, percentage of actors, or percentage of requests.

Although working with feature flags has its caveats and might take some getting used to, they are nevertheless a great tool to have at your disposal.

Until next time, happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Bootstrapping with Ruby on Rails Generators and Templates

Hans Schnedlitz — Wed, 11 May 2022 12:00:46 +0000

Rails' batteries-included approach is one of its greatest assets. No other framework makes it so effortless to get your application off the ground quickly, at least partially due to Rails' generators.

If you've used Rails for any amount of time, you have come across generators. Need to create a new application? Run rails new. Need to scaffold a bunch of new models and views? Run rails generate scaffold. There are dozens more available to help you get started rapidly or streamline your workflow.

But sometimes, using generators is just not enough. You might want to customize the behavior of these commands or even create your own. In this article, we'll take a closer look at generators - in particular, how to create your own custom Rails application using templates.

Let's get started!

What Are Rails Generators?

Not to be confused with generator functions (which you might be familiar with from Python or Javascript), Rails generators are custom Thor commands that focus on, well, generating things.

There are lots of examples. You'll likely be familiar with the model generator (rails generate model) for creating new ActiveRecord models or the migration generator (rails generate migration) for generating new migrations. There is also rails generate generator which — you guessed it — creates a new generator!

Generators can call each other — for example, rails scaffold will call numerous other generators — and provide methods to create or modify files, install gems, run specific rake tasks, and much more. Let's create a simple model spec generator to understand how this works.

Creating Your Own Generator in Ruby on Rails

Run the following:

rails generate generator model_spec

This will create several new files in /lib/generators/model_spec. We can modify model_spec_generator.rb in folder lib/generators/model_spec/ to create a model spec file in the correct directory:

class ModelSpecGenerator < Rails::Generators::NamedBase
  source_root File.expand_path('templates', __dir__)

  def create_model_spec
    template_file = File.join('spec/models', class_path, "#{file_name}_spec.rb")
    template 'model_spec.rb.erb', template_file
  end
end

The template command will look for a template file in the lib/generators/model_spec/templates directory and render it to the specified location — the spec/models directory. The command will replace ERB-style variables found in the template file.

By setting the source_root, we let our generator know where it can find referenced template files. Template model_spec.rb in folder lib/generators/model_spec/templates/ could look like this:

require 'rails_helper'

RSpec.describe <%= class_name %>, :model
  pending "add some examples to (or delete) #{__FILE__}"
end

Once you have created that file, you can run the generator to create a new spec file.

rails generate model_spec mymodel

Many gems ship with generators such as this one. In fact, we created a simplified version of the generator Rspec ships with. FactoryBot has a generator for factories. There are many more examples.

The generators in various gems are more sophisticated than the one we created. We could make our generator take arguments or even hook it into existing generators such as rails scaffold. Refer to the Rails generators documentation if you want to learn more.

So generators have the potential to simplify your workflow in an existing application. But can we also use generators to customize setting up a new application?

Enter templates!

Templates in Ruby on Rails

As the name suggests, templates are files for customizing your application setup. Don't confuse these with the template files that we previously discussed!

Under the hood, they are just generators with a specific purpose, as evidenced by the template API. While not exactly identical to generators, they are very similar.

If you have an existing template file, you can use it like so:

rails new myapp -m mytemplate.rb

Rather than specifying a local file, you may also specify a URL. This is especially useful as it allows you to share application templates.

rails new myapp -m https://gist.github.com/appsignal/12345/raw/

You are not limited to using templates when running rails new either. If you've already set up an app, you can apply templates afterward by executing:

rails app:template LOCATION=http://example.com/template.rb

Templates can be extremely useful. Who doesn't want to automate adding the same couple of gems and making the same configuration changes every time they create a new app? Creating your own application template is great fun — even if it doesn't save a lot of time in the long run.

Creating Your Own Template in Rails

We now know about generators and how to use templates. Let's create a simple application template to automate some setup steps.

How you set up your Rails app is very much down to personal preference, but here's an example:

Install the dotenv gem.
Create a .env.development file for the development environment.
Adapt the database configuration file to use environment variables.
Optionally install and set up Rspec.

Let's create a local file — mytemplate.rb — and add dotenv using the gem command.

gem 'dotenv-rails', groups: [:development, :test]

As we've just added the dotenv gem, let's also create a .env.development file to contain our database configuration.

You can create a new file with specific content by using create_file. You won't find this in the template or generator documentation, as the method is supplied by Thor. You might also come across the alias file. Application templates are evaluated in the context of Rails::Generators::AppGenerator, and that's exactly where the file alias is defined.

create_file '.env.development', <<~TXT
  DATABASE_HOST=localhost
  DATABASE_USERNAME=#{app_name}
  DATABASE_PASSWORD=#{app_name}
TXT

The app_name variable contains the first argument of rails new. Using this variable, we can ensure our config file matches the generated application.

Next, let's use our environment variables to connect to the database. We could overwrite the entire config/database.yml using the create_file command, but let's modify it instead using inject_into_file.

inject_into_file 'config/database.yml', after: /database: #{app_name}_development\n/ do <<-RUBY
  host: <%= ENV['DATABASE_HOST'] %>
  username: <%= ENV['DATABASE_USERNAME'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>
  RUBY
end

We can use both strings or regex with the after argument to specify where to inject content.

Of course, using this kind of configuration only makes sense if a user isn't creating an application with SQLite. You can check for the presence of certain arguments by using the options variable. It's best you read the source code of Rails' app generator to see which options are available.

if options[:database] != 'sqlite3'
  # Set up env vars and db configuration
end

Last but not least, let's also allow users to install Rspec if they want to. There are various methods for taking user input and creating interactive templates. The yes? method asks a user for confirmation:

if yes?('Would you like to install Rspec?')
  gem 'rspec-rails', group: :test
  after_bundle { generate 'rspec:install' }
end

We already know the gem method, but generate and after_bundle are new.

As mentioned before, Rspec adds its own generators, and you can call these generators (or any other ones, for that matter) directly from your template. But there is a catch — gems specified with the gem method are only installed at the end of the template. Calling generate with a generator supplied by such a gem would fail — which is why you should register the command as a callback with after_bundle.

Note: Before we wrap up, a quick word about creating or modifying files. We used create_file and inject_into_file, but there are many other options. You may come across copy_file or template when reading different templates. I did not mention them here to keep things simple. If you want to create more advanced templates, you should know that these other methods for dealing with files exist.

The Result: The Final Template in Rails

The final template should look like this:

# Install dotenv
gem 'dotenv-rails', groups: [:development, :test]

if options[:database] != 'sqlite3'
  # Set up .env.development
  create_file '.env.development', <<~TXT
    DATABASE_HOST=localhost
    DATABASE_USERNAME=#{app_name}
    DATABASE_PASSWORD=#{app_name}
  TXT

  # Modify database.yml
  inject_into_file 'config/database.yml', after: /database: #{app_name}_development\n/ do <<-RUBY
  host: <%= ENV['DATABASE_HOST'] %>
  username: <%= ENV['DATABASE_USERNAME'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>
  RUBY
  end
end

# Optionally install Rspec
if yes?('Would you like to install Rspec?')
  gem 'rspec-rails', group: :test
  after_bundle { generate 'rspec:install' }
end

You can test this particular template by running:

rails new myapp -m mytemplate.rb

Or:

rails new myapp --database=postgresql mytemplate.rb

To take advantage of the custom database configuration.

As mentioned, this file is perfectly suited to share as a GitHub gist. Adapt it to suit your needs, upload it, and then share it with your colleagues, friends, and anyone else interested in your custom app template 😉.

Learn More About Rails Generators and Templates

Needless to say, we've just scratched the surface here.

Everyone has different preferences for writing and developing Rails apps, so there are numerous generators and application templates out there. You can learn a lot about doing specific customizations by reading about them. I recommend Chris Oliver's Jumpstart and RailsBytes, the latter of which is a community-curated collection of templates.

There is also Thoughtbot's Suspenders, which inspired me to dig deeper into Rails generators and templates. I even wrote my own application template — Schienenzeppelin — which, while not up-to-date, might still provide some inspiration.

Wrap Up: Get Started with Ruby on Rails Generators and Templates

In this post, we looked into the basics of Rails generators and how they are used. We created our own generators to simplify writing new model specs.

We then delved into templates and learned how you could create a simple template to customize your application setup. This can be a bit of work, but also quite rewarding. If writing your own templates is not for you, there are many existing ones online to choose from!

Happy templating!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

The Perils of Parallel Testing in Ruby on Rails

Hans Schnedlitz — Wed, 30 Mar 2022 10:42:03 +0000

Have you ever heard someone complain about their tests being too fast? Me neither.

Fast tests mean fast feedback. Whether you run them locally or in a continuous integration pipeline, the earlier your tests finish, the earlier you can react to failures and improve your code. Besides the productivity gains, it is well known that slow tests make developers grumpy. Nobody likes their developers grumpy.

With all that said, creating a lightning-fast test suite isn't always as easy as you'd hope. Luckily, Rails 6 introduced an exciting feature called parallel testing. It is effortless to get started with and can speed up your tests by a lot. However, there are some pitfalls to watch out for.

What Is Parallel Testing?

What does parallel testing even mean?

When you run a test suite, your test runner will typically spawn a single process to execute your tests one after the other — or serially. A single test process uses a single CPU core.

As you can probably imagine, this approach doesn't take full advantage of modern hardware, which often sports dozens of CPU cores.

You may have a fancy MacBook with 10 CPU cores, but sadly, that won't make your tests go any faster!

We can change this by distributing individual tests to multiple worker processes. Tests will no longer run after each other, but next to each other — in parallel. Running your test suite on two workers is twice as fast as running the same test suite on a single worker.

The more cores your machine has, the more worker processes are feasible, and thus, the faster your test suite will finish. Say your tests usually take eight minutes to run. Running those same tests using four worker processes will take the runtime down to around two minutes!

Imagine doing the same on a nice, fat 16 core machine, where we can spawn sixteen workers. Very nice indeed!

Configuring Parallel Testing in Rails

So how do we get there? Until recently, you could use third-party gems to parallelize your test suite, but starting from
Rails 6, parallel tests come standard. It's as easy as adding parallelize to your tests:

class ActiveSupport::TestCase
  parallelize(workers: :number_of_processors)
end

Using this configuration, Rails will automatically spawn worker processes based on the number of processors in your machine. Rails will also create namespaced databases (e.g. database-test-0, database-test-1, etc.) to run your tests against.

That's all it takes to get started! Of course, there are some additional configuration options if you need them.

Sometimes, you may have to perform a specific setup or cleanup for parallel tests. Rails provides two hooks for you to use — parallelize_setup and parallelize_teardown. These are called before and after new worker processes spawn:

class ActiveSupport::TestCase
  parallelize_setup do |worker|
    # setup
  end

  parallelize_teardown do |worker|
    # cleanup
  end

You can also manually set the number of workers:

class ActiveSupport::TestCase
  parallelize(workers: 4) # Use 4 worker processes
end

Alternatively, use the PARALLEL_WORKERS environment variable to override an existing configuration:

PARALLEL_WORKERS=4 rails test

There is also the option to use threads instead of workers to parallelize your test suite.

class ActiveSupport::TestCase
  parallelize(workers: :number_of_processors, with: :threads)
end

with: :threads is the default option when using JRuby or TruffleRuby. Using threads, in theory, provides slightly better performance. Threads require less overhead than processes, after all. In practice, however, I never found using threads all too useful, and you should be fine just sticking to process-based parallelization for the most part.

Beware the Pitfalls

So all you need to do is add parallelize to your existing tests to experience incredible speedup? It's that easy!

If you are lucky, that really is true. It's more likely that you will hit some unexpected snags when first adding parallelization to your existing test suite. This certainly was the case for me!

Let's get one thing out of the way. If you use RSpec rather than Minitest, you are out of luck. RSpec does not support Rails 6 built-in parallel testing. There is an ongoing discussion about changing that, but there hasn't been any significant progress for a while. If you want parallel tests with RSpec, your best bet is still using third-party gems such as grosser/parallel_tests.

Another unexpected issue that you might face is that running a small number of tests in parallel ends up being slower then running them serially. Setting up parallel tests comes with a significant overhead — such as creating multiple databases — which can eliminate any gains you might get from parallelization.

You might be better off disabling parallel tests for a small number of tests. You can do so by using the PARALLEL_WORKERS environment variable:

PARALLEL_WORKERS=0 rails test test/controllers/my_controller_test.rb

Rails 7 addressed this by enabling parallel execution only when you execute many tests. So if you've already upgraded, you won't experience this problem. Per default, the parallelization threshold is set to 50, but you can override it:

config.active_support.test_parallelization_threshold = 123

The last problem I want to highlight is the one you are most likely to face, and it is also the most insidious and hardest to deal with. You may start seeing random failures when enabling parallel tests for your test suite. To understand how parallelization can cause this, let's look at a simple test case:

class FileTest
  def teardown
    File.delete('test.txt')
  end

  test 'create file' do
    file = File.write('test.txt', 'created')

    assert_path_exists('test.txt')
  end

  test 'delete file' do
    file = File.write('test.txt', 'deleted')

    File.delete('test.txt')

    assert_not(File.exist?('test.txt'))
  end
end

Besides being a bit useless, this test is perfectly fine. It will pass 100% of the time as long as it's run serially. Each test is isolated, and executing these tests in random order does not cause them to fail. That changes when you add multiple processes or threads to the mix.

When running tests in parallel, the execution order of individual statements in your tests can get changed up due to CPU scheduling. Looking at the example, you'll sometimes see execution orders such as this one:

# Worker 1 executes
file = File.write('test.txt', 'created')

# Worker 2 executes
file = File.write('test.txt', 'deleted')
File.delete('test.txt')
assert_not(File.exist?('test.txt'))

# Worker 1 executes
assert_path_exists('test.txt')

Since Worker 2 deleted the file before Worker 1's assertion was executed, the first test will fail — sometimes. To add insult to injury, a different execution order would sometimes make the second test fail and the first one pass.

This simple example illustrates an issue that extends not only to files but to any singleton resource that your tests access in a non-thread-safe way. Suppose you write to a Redis database or an Elasticsearch index. In that case, you'll likely experience similar complications. What's worse, it may take you a while to uncover all tests that cause random failures — and even more time to fix all of them.

There is no silver bullet to address flaky parallel tests. In general, you will need to ensure that multiple test processes do not share resources. For files, use Tempfiles. Use parallelize_setup to create namespaced resources (e.g. Redis databases). And so on.

Adding Parallel Testing to Existing Rails Tests

Let's say you struggle with random test failures due to parallelization and don't have the time to fix them. However, you still want to reap the benefits of parallel testing. You may prefer to enable it only for a subset of your tests.

Only tests that call parallelize will be parallelized after all, and by using concerns or parent classes, you can add parallel testing to your test suite one test class at a time. You could create a module like this:

module Parallelize
  def self.included(base)
   base.class_eval do
      parallelize(workers: :number_of_processors)

      # ...
    end
  end
end

Any test class that includes this module will now run in parallel:

class MyTest < ActiveSupport::TestCase
  include Parallelize
end

Alternatively, you could create a new test class like ParallelTest:

class ParallelTest < ActiveSupport::TestCase
  parallelize(workers: :number_of_processors)
end

Then, inherit from that for tests that should run in parallel — and leave out those that prove problematic.

Parallel Testing as a Bandaid

Parallel testing provides impressive speed gains for little effort. Don't be fooled, though: it is no substitute for other approaches to improve your test suites' speed, but rather an addition.

If you find your test suite is slow and can spare the effort, spend some time profiling it and addressing the root cause/s for the slowness. A slow test suite with parallel testing added to it will get faster, but never as fast as an already fast test suite that also runs in parallel!

Wrap Up

In this post, we looked at what parallel testing is, how you can set it up and how to configure it. If you need a way to make your tests go faster, parallel testing provides just that.

You might face some obstacles when adding parallel testing to your test suite. Don't be surprised when tests that ran stable for years suddenly start failing. You can work around them by parallelizing only a subset of your test suite.

No matter which approach you choose, parallel testing is a fantastic tool to speed up your tests!

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!