Notes to self

devise-otp 2.0 released

2025-10-21T00:00:00+00:00

The OTP plugin for Devise I help to maintain goes 2.0 this week. Here is what’s new and how to upgrade.

What’s new

We tried to address a couple of things in this release, mainly support for lockable strategy, improving locale files, and fixing Hotwire and Remember me support. On top we refactored some code, cleaned up ERB views, and added Rubocop and linting.

Most of these things are self-descriptive but it might be important to note that the devise-otp shares failed login counter with lockable for now. In a way, a login failure is a login failure at the end of the day.

We also have some breaking changes that warrant the big version bump. Laney Stroup refactored browser persistance to be a dedicated controller and while standardizing browser persistance routes moved actions to be HTML buttons.

Upgrading

Regenerate the controller and views if you use custom ones:
```
 rails g devise_otp:controllers
 rails g devise_otp:views
```
Note that the browser persistence controls now use button_to, rather than link_to.
Update locales file

Move any *_persistence keys from devise.otp.otp_tokens to devise.otp.otp_persistence

And that should be it! Please file an issue if you found one.

InvoicePrinter 2.5 with QR images and Ruby 3.4 support

2025-10-20T00:00:00+00:00

Today I released a new version of InvoicePrinter, my Ruby library for generating PDF invoices. Here’s what’s new.

New features

I finally implemented last feature I had in mind, QR code images. I decided not to add dependencies and keep it as a simple image, although we could consider a built-in feature later on.

To add a QR code, simply point to your QR image path:

invoice = InvoicePrinter::Document.new(
  number: 'NO. 202500000001',
  provider_name: 'John White',
  provider_lines: provider_address,
  purchaser_name: 'Will Black',
  purchaser_lines: purchaser_address,
  issue_date: '10/20/2025',
  due_date: '11/03/2025',
  total: '$ 900',
  bank_account_number: '156546546465',
  description: "Invoice with QR image example.",
  items: [],
  note: "Scan the QR code for payment or details."
)

qr_path = File.expand_path('../qr.png', __FILE__)

InvoicePrinter.print(
  document: invoice,
  qr: qr_path,
  file_name: 'qr_invoice.pdf'
)

The QR code will always appear bottom right, above any notes if they exist.

Ruby support

InvoicePrinter got Ruby 3.4 support. It currently supports Rubies from 3.1 to 3.4. We are staying with current Prawn version due to a circular dependency.

New contributors

Simon Neutert was a new contributor in this release, thanks Simon!

Running JavaScript after a Turbo Stream renders

2025-03-24T00:00:00+00:00

Turbo comes with turbo:before-stream-render but unfortunately doesn’t ship with the equivalent turbo:after-stream-render. Here’s how to run JavaScript after the stream renders.

Why we need this

If you are building your application with Hotwire, your Turbo streams will likely add, remove, and replace some HTML nodes. This mostly works except when you want to add HTML that comes with some JavaScript. Like a file picker, Trix editor, and the like.

Turbo itself won’t do anything about this. It’s a rather simple tool with simple purpose. JavaScript initialization should come with the HTML Turbo is about to add. Hotwire solves this with Stimulus.

The Hotwire way

The Hotwire answer to the problem is Stimulus controllers. Stimulus is build on top of MutationObserver which is a browser API providing the ability to watch for changes being made to the DOM.

When a Stimulus controller appears on the page, its connect method is called automatically. If our HTML doesn’t come with a Stimulus controller, we should create a new controller and put our initialization code inside its connect method:

// app/javascript/controllers/my_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Code to initialize something
  }
}

Then we simply add the controller to an element inside our Turbo Stream:

<turbo-stream>
  <div data-controller="my-controller">
  	Something that needs to be initialize with JavaScript.
  </div>
</turbo-stream>

When Stimulus is not an option

Sometimes Stimulus might not be what we want and we would love to have a Turbo Stream event to hook into anyways.

Luckily, Steve shared his little implementation of turbo:after-stream-render in this thread:

// application.js
const afterRenderEvent = new Event("turbo:after-stream-render");
addEventListener("turbo:before-stream-render", (event) => {
  const originalRender = event.detail.render

  event.detail.render = function (streamElement) {
    originalRender(streamElement)
    document.dispatchEvent(afterRenderEvent);
  }
})

As you can see, the idea is quite simple. We create a new custom Event and add an event listener for turbo:before-stream-render which already exist. We then run our event after we are done with original rendering.

To use it we create an event listener and paste the JavaScript that needs to run after rendering:

document.addEventListener("turbo:after-stream-render", () => {
  console.log("I will run after stream render")
});

Running interactive sessions with Kamal

2025-03-21T00:00:00+00:00

How to connect to a container on a server managed by Kamal and run an interactive session?

Interactive server actions

Kamal comes with a kamal server exec to execute a single command on the server. If we pass the -i option, we’ll start the interactive session that doesn’t cancel the connection immediatelly.

Similarly, Docker comes with docker exec command with the -it options to run a container process interactively.

If we combine both of these we’ll get what we need. A single command to run something interactively out of a single container:

$ kamal server exec -i "docker exec -it [CONTAINER] [COMMAND]"

Example

Here’s an example with kamal-proxy:

$ kamal server exec -i "docker exec -it kamal-proxy bash"

After running the comment we’ll be dropped into the container running Kamal Proxy.

Then we can play with the proxy without running long commands:

$ kamal-proxy stop app-web --message=""
$ kamal-proxy resume app-web

Predownloading embedding models in Rails with Kamal

2025-03-10T00:00:00+00:00

If you are building AI-powered applications in Ruby on Rails, you might have come across Informers or Transformers.rb gems for transformer inference. Here’s how to improve the production deployment of their models in Kamal setups.

Informers & Transformers.rb

Informers and Transformers.rb are excellent gems for creating document embeddings. These embeddings can then be used to search your documents, build chatbots, and more.

Here’s an example from the README:

sentences = ["This is an example sentence", "Each sentence is converted"]

model = Informers.pipeline("embedding", "sentence-transformers/all-MiniLM-L6-v2")
embeddings = model.(sentences)

As you can see, you can directly pass a model name you want to the gem. However, these models are quite big and don’t ship with these gems. Conveniently, they will be downloaded on first use.

This auto-download works amazingly well for development but quickly become a major issue in production. If you are using Kamal or other Docker-based deployment you would be constantly downloading these models with every new release.

Production setup

For production, we need to download these models just once to a single location, then point the gems to read the models from there.

The first step is creating a location for them on the server:

# run on the server after logging in with SSH
# or ideally make it part of server configuration
mkdir -p /models;
chmod 700 /models;
chown 1000:1000 /models

Setting up the ownership for the user 1000 is important since we’ll be downloading them from the Rails containers.

The next step is figure out where they get saved. After a little bit of search on GitHub I found out that both gems construct the cache path using the XDG_CACHE_HOME environment variable.

So we’ll need to set this variable to our location and make sure there are downloaded before we run the application.

Kamal bits

To expose our /models location we’ll add a new volume definition:

# config/deploy.yml

service: [SERVICE_NAME]
image: [DOCKER_USERNAME]/[SERVICE_NAME]

volumes:
  - "/storage:/rails/storage"
  - "/models:/rails/models"

Now if we read and save from /rails/models inside the application image, we actually read from and save to a permanent location now.

So now we can set XDG_CACHE_HOME env to point to /rails/models:

# config/deploy.yml

env:
  clear:
    XDG_CACHE_HOME: "/rails/models"
    ...

This way we make sure the downloaded models will get reused, but we should make sure they are available before we run our embedding tasks.

Pre-download

We have a few options on populating the new /models cache.

We can grab the local models and scp them to the expected location (note the full paths with the subdirectory). We can also ‘one off’ a Rails console task with kamal console and make sure they are downloaded or create a Rake task.

We can also make this a firm part of deployment by moving this task into the bin/docker-entrypoint like this:

...

if [ "${@: -1:1}" == "solid_queue:start" ]; then
  echo "Caching models into $XDG_CACHE_HOME"

  bundle exec rails runner '
  begin
    model = Informers.pipeline("embedding", "thenlper/gte-base")
    puts "Successfully downloaded thenlper/gte-base model"
  end
  '
fi

echo "Running ${@}"
exec "${@}"

Since I run Solid Queue, I used the solid_queue:start as argument. You might need to adjust this to fit your background job processing system.

Note that you need call all of the models you’ll actually use.

Combining multiple sitemaps with a sitemap index

2025-02-17T00:00:00+00:00

What if we need to combine multiple sitemaps for a main domain or subdomain? Here’s how to do it by creating sitemap index.

Sitemap index

Let’s say our site has a regular sitemap.xml and a blog/sitemap.xml, but we want Google to crawl and index both. To combine them we need to rename the original to something else like main_sitemap.xml and then create an index of all sitemaps we have:

<?xml version="1.0" encoding="UTF-8"?>

<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
     <loc>https://deploymentfromscratch.com/main_sitemap.xml</loc>
     <lastmod>2004-10-01T18:23:17+00:00</lastmod>
   </sitemap>
   <sitemap>
      <loc>https://deploymentfromscratch.com/blog/sitemap.xml</loc>
   </sitemap>
</sitemapindex>

And that’s it, both sitemaps then stay exactly same as before. Optionally we can include <lastmod> tag for latest modification.

Setting up Cloudflare R2 buckets for Active Storage

2025-01-31T00:00:00+00:00

Rails comes with a built-in support for saving and uploading files to S3 and S3-compatible storage services in Active Storage. Here’s how to set up Cloudflare R2.

Cloudflare R2

To start using Cloudflare R2, select R2 Object Storage from the menu on the left navbar. If you are on free plan you’ll need to subscribe first.

Then you can click + Create bucket and give your bucket a name. Choose meaningful names for your buckets. I usually append the environment to the name.

Cloudflare will auto assign your bucket location based on your actual location and providing a hint might not work. Not great doing this on holidays.

TIP: If you are hosting in EU, you can at least choose Specify jurisdiction and force it to be within EU.

Then on the bucket page choose Settings and include the following CORS:

[
  {
    "AllowedOrigins": [
      "*"
    ],
    "AllowedMethods": [
      "PUT"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [
      "Origin", "Content-Type", "Content-MD5", "Content-Disposition"
    ],
    "MaxAgeSeconds": 3600
  }
]

Once done click on API next to the + Create Bucket button. Select Manage API tokens and create a new token.

Note all secrets and most importantly access key, access key secret and URL.

Rails configuration

Install Active Storage and configure config/storage.yml similarly to the following:

test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

cloudflare_dev:
  service: S3
  endpoint: https://[HASH].eu.r2.cloudflarestorage.com
  access_key_id: <%= ENV["R2_ACCESS_KEY"] %>
  secret_access_key: <%= ENV["R2_SECRET_ACCESS_KEY"] %>
  bucket: app-dev
  region: auto

cloudflare_production:
  endpoint: https://[HASH].eu.r2.cloudflarestorage.com
  access_key_id: <%= ENV["R2_ACCESS_KEY"] %>
  secret_access_key: <%= ENV["R2_SECRET_ACCESS_KEY"] %>
  bucket: app
  region: auto

To connect Cloudflare we’ll need an endpoint, access_key_id, secret_access_key, and region. You can use environment variables or Rails Credentials.

Note that unlike for Amazon S3 where we fill in the region and Digital Ocean Spaces where the region is unused, we set it to auto.

I usually set up two different backends, one for development and one for production:

# config/environments/development.rb
config.active_storage.service = :cloudflare_dev

# config/environments/production.rb
config.active_storage.service = :cloudflare_production

And that’s really it!

Adding button loader to Turbo-powered forms

2025-01-15T00:00:00+00:00

Turbo is a great way to build user interfaces, but most Turbo forms have to wait for the server response. Here’s how I am adding a small loading spinner to the submit buttons to improve the UX.

Submit feedback

Whenever we submit a Turbo form, we are waiting for a response from the server without any big visual changes. This is especially noticable inside modals and on slow connections.

To improve the situation we’ll create a small Stimulus controller that can be attached to any such form and suggests everything is working despite the wait:

Here’s the implementation of our small controller for lazy forms:

import { Controller } from "@hotwired/stimulus";

// Connects to data-controller="lazy-form"
export default class extends Controller {
  static targets = ["button"];

  submit(event) {
    const button = this.buttonTarget;

    // Preserve the button's current width and height
    const buttonWidth = button.offsetWidth + "px";
    const buttonHeight = button.offsetHeight + "px";
    button.style.width = buttonWidth;
    button.style.height = buttonHeight;

    // Change the button text and disable it
    button.innerHTML = '<span class="small-loader"></span>';
    button.disabled = true;
  }
}

The controller’s only job is to update the button without any interference to the submission process. I find it best when the button’s width doesn’t change, but you can change it to whatever’s needed.

You might also want to style the disabled state e.g. with cursor: wait; at least.

This can then be added to any form at hand:

<%= form_tag resource_path, method: :post, data: { turbo: true, controller: "lazy-form", action: "submit->lazy-form#submit" } do %>
  ...
  <%= button_tag "Submit", class: "button is-primary", data: { "lazy-form-target": "button" } %>
<% end %>

Alternatives

There is also data-turbo-submits-with which let’s you avoid writing Stimulus controller for simple cases.

Auto-saving Rails forms with Turbo Streams

2025-01-09T00:00:00+00:00

Here’s how to implement autosaving for inline input fields the Hotwire way.

Autosaved forms

What’s autosave? Autosaving is saving a user input automatically on changes, lost focus or after an interval of no interactivity without any specific user action. Typically in inline forms.

To make things straigtforward let’s say we want to save a post’s title while reusing an existing update action that can save the title or perhaps all the post’s attributes.

They are couple options to go around it, but here’s how I do it. You just need Turbo and Stimulus installed.

Stimulus autosave

Since we’ll remove the usual ‘Save’ button from the form, we’ll need an auto-submission done in a different way. We can create a small Stimulus autosave controller that will be able to autosave anything by submitting the model form:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["form"];

  submit(event) {
    event.preventDefault();
    this.formTarget.requestSubmit();
  }
}

The controller has one form target to determine which form to submit. You could even avoid a target and find the form element, but this makes it explicit.

We need to call requestSubmit instead of submit otherwise we wouldn’t get a Turbo request.

Tip: There is Auto Submit controller as a package.

The form

The form to submit the action is completely same, we keep our form_with, we keep the same url if we specified that. We just wrap it with data-controller set to our Stimulus controller name and provide data attributes on the form and the field in question:

<div data-controller="autosave">
  <%= form_with(model: post, url: post_path(post), data: { "block-target": "form" }) do |form| %>
    <%= form.label :title %>
    <%= form.text_field :title, class: "input", data: { action: "blur->autosave#submit" } %>
      
    <div id="title-status">
    </div>
  <% end %>
</div>

I used the blur event to autosave on lost focus but you could also use change to immediately save any progress (at the expense of many HTTP calls).

I also prepared a small <div> with an ID that will inform the user about the saving status. The type of the element is irrelevant, it can be a <turbo-frame> too. The important thing is the ID.

Note that Turbo could also replace the whole form or in a different approach you could even morph the whole screen.

Turbo stream

Given that our update action remains the same as with traditional forms, the form would already be submitted but we would get the usual redirection. Instead, we want to return a Turbo stream:

class PostsController < ApplicationController
...
  def update
    if @blog_post.update(post_params)
      respond_to do |format|
        format.turbo_stream
        format.html { redirect_to post_path(@post), notice: "Post was successfully updated." }
      end
    else
      respond_to do |format|
        format.turbo_stream
        format.html { render :edit, status: :unprocessable_entity }
      end
    end
  end

Now we have an autosave but without any feedback for the user. To add it we’ll instruct Turbo to replace our <turbo-frame> with either message Saved. or the error in the view:

<!-- app/views/posts/update.turbo_stream.erb -->
<%= turbo_stream.append "title-status", method: :morph, target: :current_step do %>
  <% if @blog_post.errors[:title].any? %>
    <%= @blog_post.errors[:title].first %>
  <% elsif @blog_post.title_previously_changed? %>
    Saved.
  <% end %>
<% end %>

Asking on title_previously_changed? will only output the message if any actual changes happened.

And that’s it! You have an inline form with autosaving.

Warning

I spent a considerable amount of time chasing an issue with wrong field focus. If that happens to you, go through all of your forms and make sure each input field has a unique ID. If you have two forms of the same model on the page they will have a different form ID but same input IDs.

Business Class 2.0 with Rails 8, Pay 8, Solid, Kamal 2, and fancy generator

2024-12-30T00:00:00+00:00

The Ruby on Rails template Business Class gets a whole new edition. Rails 8, new licencing, and improved CRUD generator.

Business Class 2.0

The new Business Class is built on top of Rails 8, Pay 8, Solid Trifecta libraries, and Kamal 2. Solid Trifecta is now the default and Redis dependency was removed, simplifyng everything. Also, Action Policy got added to finally refactor authorization. An overall update of dependencies but that’s not all!

CRUD Generator

The CRUD generator got much better. It will now give you bulk actions both for team views (as grid) and admin views (as table). All destructive actions load a confirmation HTML dialog view with Hotwire.

I was also able to fix the previous limitation of simple models and you can now generate models like my_shop/product or garage/fancy_car giving you a beautiful start for your well-architected domain model.

The refreshed generator now also generates policy files so you literally get a whole CRUD for a team-resource without much work.

Kamal 2

Kamal configuration got updated to its second major version and to handle the new Solid libraries. Business Class now also explicitely provides a custom production.conf for any necessary tuning and provisioning sets up unattended upgrades.

Note that you can use Business Class with managed database or even without Kamal. It’s just Kamal-ready if you need it to be.

Design and demo

The default design got improved in details and screens got much more coherent.

Here’s a demo.

Licencing

The new license gives you lifetime access to Business Class, no need for any kind of renewals. There is a more expensive version for agencies, but even that one is now with lifetime access.