Product Docs
Open Source
Education
The Ruby images maintained by Chainguard are a mix of development and production distroless images that are suitable for building and running Ruby workloads.
Because Ruby applications typically require the installation of third-party dependencies via Rubygems, using a pure distroless image for building your application would not work. In cases like this, you’ll need to implement a multi-stage Docker build that uses one of the -dev images to set up the application.
-dev
In this guide, we’ll build two example applications that demonstrate how to use Ruby container images based on Wolfi as a runtime. In the first, we’ll use a minimal image containing just Ruby to execute a demo that doesn’t have any external dependencies. In the second example, we’ll set up a multi-stage Docker build to run a demo that requires the installation of Rubygems via bundler.
bundler
We’ll start by creating a small command-line Ruby application to serve as a demo. This application has no external dependencies; it will read from a text file containing facts about octopuses, and output a random line from that file. This demo is also available in our demos repository, if you want to review the source files before building it.
First, create a directory and then move into it for your app. Here we’ll use octo-facts:
octo-facts
mkdir ~/octo-facts && cd ~/octo-facts
Next, create a new file to serve as the application entry point. Here, we’ll use octo.rb. You can edit this file in whatever code editor you would like. We’ll use nano as an example.
octo.rb
nano
nano octo.rb
The following Ruby code will read a random line from the facts.txt file and print it out to the terminal:
facts.txt
#!/usr/bin/env ruby class OctoFact attr_accessor :source def initialize(source = "facts.txt") @source = source end def random_line puts File.readlines(@source).sample end end if __FILE__ == $0 fact = OctoFact.new fact.random_line end
Copy this code to your octo.rb script, then save and close the file.
Next, pull down the facts.txt file with curl. You can inspect the file’s contents before downloading it to ensure it is safe to do so. Make sure you are still in the same directory where your octo.rb script is.
curl
curl -O https://raw.githubusercontent.com/chainguard-dev/edu-images-demos/main/ruby/octo-facts/facts.txt
With all files in place, you can now run the demo using Docker. The following command will execute the demo code using the same base image we’ll use to build our Dockerfile in the next step. It will set up a volume sharing the files in the current directory with the location /work inside the container, then execute the octo.rb script:
/work
docker run --rm -v ${PWD}:/work cgr.dev/chainguard/ruby octo.rb
And you should get output like this, with a random fact about octopuses:
Octopuses have decentralized brains.
In the next step, we’ll create a Dockerfile to build and run the demo.
With the demo ready, you can now set up a Dockerfile to build a custom image for your Ruby application. Make sure you’re still on the same directory as the application files, then create a new Dockerfile using your text editor of choice:
nano Dockerfile
The following Dockerfile will:
cgr.dev/chainguard/ruby:latest
/app
ruby octo.rb
Copy the following content to your Dockerfile:
Dockerfile
FROM cgr.dev/chainguard/ruby:latest WORKDIR /app COPY octo.rb facts.txt ./ ENTRYPOINT [ "ruby", "octo.rb" ]
Save and close the file when you’re done. Next, build the image with:
docker build . -t octo-ruby-demo
Once the build is finished, you can execute the image with:
docker run --rm octo-ruby-demo
And you should get output similar to what you got before, with a random octopus fact.
To demonstrate how to containerize a more complex application that requires the installation of third party dependencies, we’ll create a second demo that uses a Docker multi-stage build, which will combine the cgr.dev/chainguard/ruby:latest-dev development image to build the application and the cgr.dev/chainguard/ruby:latest distroless image to run it.
cgr.dev/chainguard/ruby:latest-dev
This demo will use the rainbow Ruby gem to output to the command line interface a colorful quote, inspired by cowsay.
First, create a directory for your app. Here we’ll use inky-says:
inky-says
mkdir ~/inky-says && cd ~/inky-says
Then, set up your Gemfile:
nano Gemfile
Copy the following content into your Gemfile to require the Rainbow Gem:
source 'https://rubygems.org' gem 'rainbow'
Save and close the file.
Next, create a new Ruby script file called inky.rb:
inky.rb
nano inky.rb
The following code outputs a colorful quote provided at runtime, incorporating an ASCII representation of Inky that is pulled from an inky.txt file located at the same directory as the ruby script. The printed quote colors alternate randomly between purple and magenta.
inky.txt
#!/usr/bin/env ruby require 'rainbow' Rainbow.enabled = true class Inky def says(message = "Hello World") colors = [:purple, :magenta] words = message.split(" ") print "\n ".ljust(40, " ") words.each do |n| print Rainbow(n).color(colors.sample) + " " end print "\n" puts File.readlines('inky.txt') end end if __FILE__ == $0 inky = Inky.new inputArray = ARGV message = inputArray.length > 0 ? inputArray.join(' ') : "Hello Wolfi" inky.says(message) end
Copy this code to your inky.rb script, then save and close the file.
Next, pull down the ASCII inky.txt file with curl. You can inspect the file contents before downloading it to ensure it is safe to do so. Make sure you are still in the same directory where your inky.rb script is.
curl -O https://raw.githubusercontent.com/chainguard-dev/edu-images-demos/main/ruby/inky-says/inky.txt
With everything in place, you can now work on the Dockerfile that will install the application dependencies and execute your Ruby script.
To make sure our final image is distroless while still being able to install Rubygems, our build will consist of two stages: first, we’ll build the application using the dev image variant, a Wolfi-based image that includes the Gem executable, Bundler, and other useful tools for development. Then, we’ll create a separate stage for the final image. The resulting image will be based on the distroless Ruby Wolfi image, which means it doesn’t come with the Gem executable or even a shell.
dev
Create a new Dockerfile using your code editor of choice, for example nano:
builder
bundle install
ruby inky.rb
Copy this content to your own Dockerfile:
FROM cgr.dev/chainguard/ruby:latest-dev as builder ENV GEM_HOME=/work/vendor ENV GEM_PATH=${GEM_PATH}:/work/vendor COPY Gemfile /work/ RUN gem install bundler && bundle install FROM cgr.dev/chainguard/ruby:latest ENV GEM_HOME=/work/vendor ENV GEM_PATH=${GEM_PATH}:/work/vendor COPY --from=builder /work/ /work/ COPY inky.rb inky.txt /work/ ENTRYPOINT [ "ruby", "inky.rb" ]
Save the file when you’re finished.
You can now build the image with:
docker build . -t inky-says
Once the build is finished, run the image with:
docker run --rm inky-says Wolfi says hi
And you should get output like this:
Wolfi says hi @@@ @@@*******@@@ / @@%**@@@@*******@@@ / @@*@@***********///@@ / @*************///////&@ / @@*****%@@@**////@@@&//@@ / @*****@**##@////@//##@//@ / @@*****@@@@//////@@@@//@@ / ,@@@@***////////////////@@@@, @@@*******/////////////////////(((((@@@ @*******//////////////////////((((((((@ @@@/////////@///////@///(((((%@@@ #@///////@@@///////@@@((((((#@ @@@ /@@///@@, @@@
If you inspect the image with a docker image inspect inky-says, you’ll notice that it has only three layers, thanks to the use of a multi-stage Docker build.
docker image inspect inky-says
... "RootFS": { "Type": "layers", "Layers": [ "sha256:ec653fe8da922557dd1d78b47b2c0074a6e9257e5a15e596bc4e1fb1e325c3d8", "sha256:d9541a2e82274d8140ed7f4cc79ce92f295d13951585c4a433f1baa35015e1eb", "sha256:a44e5fee28e11702a63418bf76c009b1b4948f1b0426e0f199b83702ae187796" ] }, "Metadata": { "LastTagTime": "2023-05-09T19:53:16.060125796+02:00" } } ]
In such cases, the last FROM section from the Dockerfile is the one that composes the final image. That’s why in our case it only adds two layers on top of the base cgr.dev/chainguard/ruby:latest image, containing the two COPY commands we use to copy the application files and its dependencies to the final image.
FROM
COPY
It’s worth highlighting that no code or data is carried from one stage to the other unless you use a COPY command to explicitly copy it. This approach facilitates creating a slim final image with only what’s absolutely necessary to execute the application. Using a multi-stage build like this, without shell tools and interactive language interpreters built in also makes your final image more secure.
If your project requires a more specific set of packages that aren't included within the general-purpose Ruby Chainguard Image, you'll first need to check if the package you want is already available on the wolfi-os repository.
If the package is available, you can use the wolfi-base image in a Dockerfile and install what you need with apk, then use the resulting image as base for your app. Check the "Using the wolfi-base Image" section of our images quickstart guide for more information.
apk
If the packages you need are not available, you can build your own apks using melange. Please refer to this guide for more information.