Primcloud
Docs menu

Runtime versions

Which Ruby versions Primcloud supports, how to pin one via the Gemfile and Gemfile.lock, and how to upgrade.

On this page

Primcloud installs the Ruby version your Gemfile.lock pins. Pin nothing and you get Primcloud's default, which is 3.3.9 today.

Supported versions#

The Ruby versions you can install are part of the Primcloud Runtime and move as the Runtime is updated. The build log for each deployment, in the Deployments tab, shows the version that build installed. Treat the table below as an illustrative snapshot rather than a fixed contract:

Ruby line Support status
3.3 Supported (default)
3.4 Supported

Each line installs the patch you pin in Gemfile.lock, and new patches land in the Primcloud Runtime as Ruby core ships them. Newer lines join as they mature upstream. Support tracks Ruby core's own branch policy: once a branch reaches end-of-life upstream, no further security patches ship for it, and the Primcloud Runtime eventually drops it. Your build log names the exact version it resolved.

An older patch that predates the versions the Runtime currently ships may still install from its archive, but it stops receiving updates once its branch ages out. Move to a maintained patch.

JRuby. JRuby runs on Primcloud when your Gemfile.lock declares it. A JDK is installed alongside. Your build log names the JRuby version it resolves.

Pinning a version#

Two files together control the version that gets installed:

1. Gemfile: declare the version:

Gemfile 
source "https://rubygems.org"

ruby "3.4.10"

# ...

2. Gemfile.lock: commit the lockfile with a matching RUBY VERSION block:

Gemfile.lock 
RUBY VERSION
   ruby 3.4.10p0

Regenerate the lockfile after changing the Gemfile:

Terminal 
bundle update --ruby
git add Gemfile.lock
git commit -m "Pin Ruby 3.4.10"

The Ruby version Primcloud installs is read from Gemfile.lock's RUBY VERSION. The Gemfile line alone isn't consulted at build time. Committing a lockfile without a RUBY VERSION block means you get Primcloud's default Ruby.

No configuration. With no RUBY VERSION block in the lockfile, Primcloud installs its default (currently 3.3.9). A build-log line indicates whether the version was sourced from the lockfile or the default:

Ruby version `3.4.10` from `Gemfile.lock`

vs.

Ruby version `3.3.9` from `default`

Pinning explicitly avoids the second case entirely.

Upgrading#

Bump the pin and redeploy:

  1. Edit the ruby line in Gemfile.
  2. Run bundle update --ruby locally to regenerate Gemfile.lock.
  3. Commit both and push.

The next build installs the newer Ruby. Because the Ruby version is part of the gem-cache invalidation key, changing Ruby also rebuilds your gem cache from scratch. Expect one longer build after the bump, then normal speed on subsequent deploys.

Review Ruby's news pages for the release notes between the version you're on and the version you're going to. Native gems (nokogiri, pg, sqlite3, bcrypt) that ship precompiled binaries per Ruby minor version will reinstall on the first build after the upgrade.

When a version drops out of support#

Ruby core drops a minor branch at a scheduled date. When that happens on Primcloud:

  • Builds targeting a supported version continue to work.
  • Builds pinned to a version that's been removed from the Primcloud Runtime fail with an "Error installing Ruby" build error.
  • Builds without a RUBY VERSION block continue with whatever Primcloud's default is at that time, which may or may not be compatible with your app.

Bump to a supported patch before the EOL date to avoid a forced upgrade under pressure.