Customise Ruby runtime environment

Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your Ruby application's requirements. This is an optional phase in the build and deploy pipeline.

Configuration

Default Ruby Runtime Environment

The default Ruby runtime environment contains:

• Alpine Linux
• Selected version of Ruby when the runtime service was created
• zCLI
• Git, RubyGems, Bundler and a full native-extension toolchain (gcc, make, libpq-dev, libyaml-dev, libffi-dev, etc.)

When You Need a Custom Runtime Image

If your Ruby application needs more than what's included in the default environment, you'll need to build a custom runtime image. Common scenarios include:

• System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apt-get install -y imagemagick on Ubuntu or sudo apk add --no-cache imagemagick on Alpine)
• Native gem dependencies: When a gem links against a system library that isn't included in the default environment
• Different base OS: When you need Alpine instead of Ubuntu (or vice versa) for specific compatibility requirements, selected via the base prefix (ubuntu/ruby@4.0 or alpine/ruby@4.0)

important

You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.

Here are Ruby-specific examples of configuring custom runtime images in your zerops.yml:

Basic Ruby Setup

run:
base: ubuntu/ruby@4.0
prepareCommands:
  - sudo apt-get update
  - sudo apt-get install -y imagemagick

Using Build Files in Runtime Preparation

build:
addToRunPrepare:
  - Gemfile
  - Gemfile.lock
run:
base: alpine/ruby@4.0
prepareCommands:
  - sudo apk add --no-cache imagemagick
  - bundle install

For complete configuration details, see the runtime prepare phase configuration guide.

Process and Caching

How Runtime Prepare Works

The runtime prepare process follows the same steps for all runtimes. See how runtime prepare works for the complete process details.

Caching Behavior

Zerops caches custom runtime images to optimize deployment times. Learn about custom runtime image caching including when images are cached and reused.

Build Management

For information about managing builds and deployments, see managing builds and deployments.

Warning

Shared storage mounts are not available during the runtime prepare phase.

Troubleshooting

If your prepareCommands fail, check the prepare runtime log for specific error messages.