Runner (Experimental)

The Clipper Runner is a container image that pulls and runs a Clipper image on demand. This allows using clipper images in contexts that only accept Docker, such as GHA workflows and cloud services.

Usage (general)

Set the docker image to clipperregistry/runner:latest. Set CLIPPER_MAGIC_IMAGE to the clipper image you want to run, and CLIPPER_CREDENTIALS to your token. See Authentication for details.

When clipperregistry/runner starts, it pulls the specified clipper image, extracts it into the running container, and execs into its entrypoint. The image’s USER, ENV, WORKDIR, ENTRYPOINT, and CMD are applied. Environment variables set at runtime (e.g. via docker run -e) take precedence over the image’s ENV.

For long-running services, the runner extracts once on startup. It will not pull/extract again on container restart.

Experimental. The runner works, but isn’t considered stable, yet. See Limitations below. The Clipper Runner is mainly intended to easily run CI/CD tests and not yet recommended for cloud workflows.

GitHub Actions

Use the runner as a job container to run CI steps inside a Clipper image:

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: clipperregistry/runner:latest
      env:
        CLIPPER_MAGIC_IMAGE: clipper.dev/myorg/myapp:latest
        CLIPPER_CREDENTIALS: ${{ secrets.CLIPPER_CREDENTIALS }}
    steps:
      - name: Download and unpack clipper image
        run: /.clipper-runner/github-init
      - run: myapp --version
      - run: make test

The github-init script extracts the image and writes environment variables to $GITHUB_ENV so subsequent steps see the image’s ENV directives.

Docker

Run any Clipper image directly:

docker run --rm \
  -e CLIPPER_MAGIC_IMAGE=clipper.dev/myorg/myapp:latest \
  -e CLIPPER_CREDENTIALS=clp_your_token \
  clipperregistry/runner:latest

Pass a command to override the image’s CMD:

docker run --rm \
  -e CLIPPER_MAGIC_IMAGE=clipper.dev/myorg/ubuntu:22.04 \
  -e CLIPPER_CREDENTIALS=clp_your_token \
  clipperregistry/runner:latest \
  cat /etc/os-release

Persistent chunk cache

Mount a volume at /.clipper-runner/store to cache chunks across runs. The second run pulls zero bytes:

docker volume create clipper-cache
 
# First run: downloads all chunks
docker run --rm \
  -v clipper-cache:/.clipper-runner/store \
  -e CLIPPER_MAGIC_IMAGE=clipper.dev/myorg/myapp:latest \
  -e CLIPPER_CREDENTIALS=clp_your_token \
  clipperregistry/runner:latest
 
# Second run: cached, near-instant startup
docker run --rm \
  -v clipper-cache:/.clipper-runner/store \
  -e CLIPPER_MAGIC_IMAGE=clipper.dev/myorg/myapp:latest \
  -e CLIPPER_CREDENTIALS=clp_your_token \
  clipperregistry/runner:latest

AWS ECS

Define a task with the runner image and set environment variables. This works with both Fargate and EC2 launch types:

{
  "containerDefinitions": [{
    "name": "app",
    "image": "clipperregistry/runner:latest",
    "secrets": [
      { "name": "CLIPPER_CREDENTIALS", "valueFrom": "arn:aws:ssm:REGION:ACCOUNT:parameter/clipper-token" }
    ],
    "environment": [
      { "name": "CLIPPER_MAGIC_IMAGE", "value": "clipper.dev/myorg/myapp:latest" }
    ],
    "command": ["myapp", "serve", "--port", "8080"]
  }]
}

Limitations

The runner is experimental. Known limitations:

• No --user flag. The runner container must start as root to extract the rootfs. Docker’s --user flag and GHA’s container.options: --user will cause extraction to fail. The image’s USER directive is supported and applied automatically when exec’ing into the entrypoint.

• Non-Linux support. The runner requires a Linux container runtime where the root filesystem is a single mount (overlay2, ext4, etc.). Other platforms may not work properly.

• Avoid restarting during pull/extraction. If the container is killed during the initial image pull or extraction, the runner will re-extract on the next start. Best effort is made to support resumable extraction, but this is not yet guaranteed for all failure modes.

• Startup time. The image is pulled and extracted on first start, which adds to container startup time. Configure health check grace periods and startup timeouts accordingly.

• Mount restrictions. Directory mounts (volumes) work and shadow the image content at that path. File bind mounts into directories that also exist in the image may not work in all cases.