Builds Docker image, runs it, and kills

This small Ruby library helps to build temporary Docker images, run Docker containers, and clean up afterwards — it may be convenient for automated tests (for example, with Minitest):

class MyTest < Minitest::Test
  def test_prints_hello_world
    stdout = donce(
      dockerfile: '
        FROM ubuntu
        CMD echo "Hello, world!"
      '
    )
    assert_equal("Hello, world!\n", stdout)
  end
end

It's possible to run a Docker image in background mode too:

stdout = donce(image: 'ubuntu', command: 'sleep 9999') do |id|
  # The "id" is the container id
  # The "donce_host()" is the hostname of it
end

If you set DONCE_SUDO environment variable to true, docker will be executed via sudo.

Host group/user IDs are passed to the build, as GID and UID args. You can use them, when you copy resources into the image, for example:

FROM ubuntu
ARG UID
ARG GID
RUN groupadd -g ${GID} foo || true
RUN useradd -m -u ${UID} -g ${GID} foo
USER foo',
WORKDIR /foo
COPY --chown=${UID}:${GID} bar.txt .

The bar.txt file is not ready to be modified inside the container.

Here's a list of the available parameters for donce:

• dockerfile: Content of the Dockerfile (string or array of strings)
• home: Directory with Dockerfile and all other necessary files
• image: Name of a Docker image to use (e.g. "ubuntu:22.04")
• log: Logging destination (defaults to $stdout)
• args: Extra arguments for the docker command
• env: Environment variables mapping for the container
• volumes: Local to container volumes mapping
• ports: Local to container port mapping
• build_args: Arguments for docker build (--build-arg)
• root: Let user inside the container be "root" (default: false)
• command: The command to execute in the container
• timeout: Maximum seconds to spend on each docker call (default: 10)

The function donce_host() returns the hostname of the host machine that can be used from within the container.

Read these guidelines. Make sure your build is green before you contribute your pull request. You will need to have Ruby 3.0+ and Bundler installed. Then:

bundle update
bundle exec rake

If it's clean and you don't see any error messages, submit your pull request.