So you've got a content-oriented website, maybe your own blog or something, and maybe you've (like me) decided to ignore the advice about using static site generators. You build your Rails site, and it is wonderful and beautiful and dynamic, and every page it replies with delights readers with your artisanally-crafted HTML. Maybe you've got some internal caching (Rails has you covered here), maybe it's all roundtrips to the database. But who cares! Your site is up and receiving traffic!

Then, suddenly, a storm hits. Congratulations! You've made it to the top of Reddit/Slashdot/Hacker News! You now have thousands, if not millions, of people beating down your door to read your content. But now your site is down! The link's comment thread is filling up with complaints about being hugged to death, and a few helpful souls are posting the archive.org equivalent of your link and siphoning away your traffic.

How do we fix this?

You could throw more compute resources at it -- think "scaling vertically/horizontally" -- which I'm sure your server/application host would ab$olutely love.

Or, you could install some sort of proxy cache in front of it. The traditional answer here is to use nginx or Varnish as a caching proxy, but if you use a content delivery network (such as Cloudflare) it may be better to use that CDN's caching features instead. (Some might recommend using both your own cache and your CDN's cache, but I wouldn't advise this because troubleshooting cache issues is already difficult enough, and having multiple layers only makes debugging even more confusing. If you do this, you should understand your web application thoroughly.)

Since this site is fronted by Cloudflare, I want to make use of its page cache: it's free and comes with the service!

However, setting this up is not as simple as it may first appear: in a default configuration, Rails doesn't permit caching (the Cache-Control headers it sends don't allow for it), and as a result, nearly every request you receive bypasses the cache and gets passed directly to the app server. This is a screenshot of my Cloudflare dashboard showing the percentage of page requests cached before I applied the fixes I describe here (those peaks top out at ~10%):

Now, you can set up rules in the Cloudflare dashboard to override Rails' requested caching behavior, but this does not solve the underlying root cause: Rails is requesting no caching, because the Cache-Control request header it sets explicitly forbids it:

Setting the Correct Cache-Control Headers with Rails

NOTE: The directions given here apply to Ruby on Rails version 7, though expires_in and fresh_when have existed since at least version 2, and concerns have been available since version 4.

expires_in 1.hour, public: true
# or
fresh_when(@article, public: true)

# app/controllers/concerns/cacheable.rb
module Cacheable
  extend ActiveSupport::Concern

  included do
    before_action :set_cache_headers, unless: current_user
  end

  def set_cache_headers
    expires_in 1.hour, public: true
  end

end

# app/controllers/static_controller.rb
class StaticController < ApplicationController
  include Cacheable
  def about
    @page_title = "About"
  end
end

Once this is done you will see that Cache-Control is indeed being set correctly:

But! You are not finished yet! You may notice that while your 'cached' stats are going up, they aren't going up as much as one might think. This is because there is another component to page caching that we have not yet discussed: etags.

Setting the Correct Etag Headers with Rails

This is where things get a bit more tricky: Rails generates another header, called an Etag, that, in theory, is supposed to be unique for each page.  (For the more technically inclined, you can think of an Etag as like a SHA256 hash for your page.) But Rails, by default, makes this tag unique per request. Both your browser cache and your CDN cache read this header to determine whether a given request is a cache hit or cache miss, and so we will need to configure Rails' to set it correctly, based on our rendered page content (or other context).

Enter fresh_when, which provides further direction to Rails on how to render the correct etag header. You provide it with an object that describes what the page renders -- generally the model instance for the given page (the Rails docs use @article in their examples) -- and it generates a hash that is used for the Etag header.

Using fresh_when with Dynamic Pages

For dynamic pages, such as the example described above and in the Rails docs, simply call fresh_when and pass the it your model instance as its first parameter, inside the controller route. Like so:

# app/controllers/articles_controller.rb
def show_article
  fresh_when @article
end

# app/controllers/concerns/static_cacheable.rb
module StaticCacheable
  extend ActiveSupport::Concern

  included do
    include Cacheable
    before_action :set_static_cache_headers
  end

  def set_static_cache_headers
    etag =  "#{params[:static]}#{params[:about]}#{current_user}"
    fresh_when etag: etag
  end
end

from pathlib import Path
from PySide6.QtGui import QPixmap, QIcon #substitute the equivalent pyQT line if you're using pyQT

# load window icon
path_to_icon = 'res/icon.png' #the path to your icon file, relative to the project root
pixmap = QPixmap()
pixmap.loadFromData( Path( path_to_icon ).read_bytes() )
appIcon = QIcon(pixmap)
self.setWindowIcon(appIcon)

If you use Bulma CSS, Turbo, and Stimulus in your web project, you may have noticed that the hamburger menu in the navbar doesn't work, and that you need to supply your own Javascript to make it work. While this is explained in the docs -- Bulma doesn't include any Javascript, after all -- the plain JS example provided doesn't work on websites using Turbo.

This occurs because, on a new page load, Turbo replaces the click handler's DOM element with new elements, even if that aspect of the page hasn't changed, without calling DOMContentLoaded (or any other startup event). Meaning, we cannot use DOMContentLoaded to set our click handlers!

So we need something else: instead of DOMContentLoaded we can use Stimulus to add a little "hamburger helper" to the project and get that menu working!

First, we want to create a new Stimulus controller, which we will call navbar_controller.js. In it, we will create one action, toggleMenu(), which will handle the click event and control the hamburger menu by toggling the is-active class on the hamburger HTML elements. In that file, add the following code:

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

// Navbar toggle
// Adapted from https://bulma.io/documentation/components/navbar/#navbar-menu

export default class extends Controller {

    toggleMenu() {

        // Get all "navbar-burger" elements
        const $navbarBurgers = Array.prototype.slice.call(document.querySelectorAll('.navbar-burger'), 0);

        // Get the target from the "data-target" attribute
        const target = this.element.dataset.target;
        const $target = document.getElementById(target);

        // Toggle the "is-active" class on both the "navbar-burger" and the "navbar-menu"
        this.element.classList.toggle('is-active');
        $target.classList.toggle('is-active');

    }

}

• data-controller: set this to the name of your Navbar controller: "navbar"
• data-action: use this to bind the click event to toggleMenu(): "click->navbar#toggleMenu"
• data-target: set this to the id of your navbar <div> element, which should have a class of navbar-menu. On this site, the element's id is "ze-navbar", so that would be the value for this data attribute.

<a role="button" class="navbar-burger" aria-label="menu" aria-expanded="false" data-controller="navbar" data-action="click->navbar#toggleMenu" data-target="[your navbar id here]">
  <span aria-hidden="true"></span>
  <span aria-hidden="true"></span>
  <span aria-hidden="true"></span>
</a>