← Bosun

Changing an app's Ruby version

The install/deploy sequence, and how old-version cleanup stays safe when several apps share one RVM install.

Bumping RUBY_VERSION in deploy.conf and re-running bosun install does more than just install the new version — it also cleans up the old one, safely, on a host where several apps share the same RVM install. This doc covers the full sequence and exactly what gets removed and when.

The sequence

vi /var/www/myapp/shared/deploy.conf   # bump RUBY_VERSION (and RUBY_GEMSET if you want a new gemset name too)
  bosun install myapp                    # installs the new ruby, and removes the old one if it's safe to (see below)
  bosun deploy myapp main                # next deploy runs `bundle install` under the NEW gemset, then symlinks + restarts
  bosun setup myapp                      # optional — refreshes shared/.ruby-version/.ruby-gemset for RVM's cd-hook

install alone does not finish the job. It only gets the new Ruby version and bundler ready — gemsets are scoped per Ruby version in RVM, so ruby-3.4.0@myapp starts out completely empty even if ruby-3.3.3@myapp already had the whole app's Gemfile installed. If you restarted Puma/Sidekiq right after install and before a fresh deploy, they'd crash on boot — the exec wrappers (shared/bin/{puma,sidekiq}-exec) correctly resolve RUBY_VERSION/RUBY_GEMSET from deploy.conf at run time, so they'd try to launch under the new Ruby, but find no gems installed there yet. deploy is what actually runs bundle install against the real Gemfile under the new gemset — see the main README's "Why a per-app .env file" section for how the exec wrappers resolve things at run time generally.

What install actually removes, and when

install compares two things every time it runs:

• deploy.conf's current RUBY_VERSION (just loaded).
• shared/.ruby-version — written by bosun setup, so it still holds whatever version this app was set up under last time, independent of whatever deploy.conf says right now.

If they differ, that's a version bump, and install tries to remove the old version — but only after checking every other app on the host:

for other_conf in /var/www/*/shared/deploy.conf; do
    grep -qx "RUBY_VERSION=<old-version>" "$other_conf" && echo "still needed by $other_conf"
  done

• Nothing else references it → rvm uninstall <old-version> runs, and the install logs exactly that.
• Something else still does → the old version is left installed, with a warning naming exactly which app's deploy.conf is still using it.

This check exists because rvm uninstall removes a Ruby version — and every gemset under it, for every app — not just the one you're upgrading. Bosun deliberately runs multiple apps on one shared host (see the main README); RVM rubies aren't scoped per app, so blindly uninstalling the old version the moment one app moves off it could silently break a completely different app that's still on it. Skipping removal (with a clear reason in the log) is always the safe default here — this is opportunistic cleanup, not something anything else depends on succeeding, so a skip or a failed rvm uninstall (logged as a warning, not a fatal error) never fails the rest of install.

First-ever install isn't affected

A brand-new app has no shared/.ruby-version yet (that file is only written by bosun setup, step 5 in the main walkthrough — AFTER install, step 4, on a first-time setup). With nothing to compare against, install just installs the requested version and skips the removal check entirely — no version is ever "assumed old" on a first run.

Checking what's actually installed

bosun version myapp     # this app's configured ruby/gemset, straight from deploy.conf
  rvm list                # every Ruby version actually installed on this host
  rvm gemset list_all     # every gemset under every installed ruby