Skip to main content

Build a Sandbox Template

A sandbox template is a Docker image that provides the tools inside a OneDev job's sandbox VM. Preinstalling compilers, runtimes, and dependencies in the template saves setup time on every job run.

This tutorial shows how to build templates with or without Docker support, publish them to Docker Hub, and use them in job definitions:

TemplateUse it for
BasicCommands that run directly in the sandbox VM
With DockerThe same commands, plus container steps, job services, image builds, and Docker Compose

Prerequisites​

First complete Working with Sandbox on every host that will run sandbox jobs. It covers Docker Sandboxes installation, virtualization requirements, service account login, registry access, and security settings.

You also need:

  • Docker on the machine used to build images, and a Docker Hub account.
  • A sandbox executor configured under Administration → Job Executors: use Server Sandbox Executor to run jobs on the OneDev server, or Remote Sandbox Executor to run them on agents. Remote execution requires Enterprise Edition.

Define the Templates​

Choose a Linux base image compatible with Docker Sandboxes that suits your project. The resulting template must include a shell, Git, and Python 3. The examples below use Ubuntu; for another base image, adapt the package names and installation commands to provide the same required tools.

Without Docker​

Create an empty directory and add a Dockerfile. For example:

FROM ubuntu:24.04
RUN apt-get update \
    && apt-get install -y git git-lfs python3 \
    && rm -rf /var/lib/apt/lists/*

Ubuntu includes a shell; this example adds Git, Git LFS, and Python 3. Add your project's build tools as needed.

With Docker​

For jobs that use containers or Docker Compose, extend your template with Docker support. Save this example as Dockerfile.docker in the same directory:

FROM ubuntu:24.04
RUN apt-get update \
    && apt-get install -y curl git git-lfs python3 docker.io docker-buildx docker-compose-v2 \
    && rm -rf /var/lib/apt/lists/*
LABEL com.docker.sandboxes.start-docker="true"

This adds Docker Engine, Buildx, Compose v2 (docker compose), and curl for Docker Sandboxes' daemon readiness check. The image label enables Docker support and starts the daemon. Containers and Docker's image storage stay inside the sandbox VM.

Both examples run as root. If your template uses a non-root user, grant it passwordless sudo access for OneDev's Docker operations and ensure your build commands can access Docker.

Build and Publish to Docker Hub​

Create a Docker Hub repository named onedev-sandbox under your account. Replace YOUR_DOCKER_ID with your Docker Hub username and sign in:

docker login --username YOUR_DOCKER_ID

From the directory containing the Dockerfiles, build and push the variant you need using the corresponding commands below. These commands use the build machine's architecture. If the sandbox host uses a different architecture, add the appropriate --platform, such as --platform linux/amd64, to each build command. For mixed architectures, publish a multi-architecture image.

docker build -t docker.io/YOUR_DOCKER_ID/onedev-sandbox:basic-v1 .
docker push docker.io/YOUR_DOCKER_ID/onedev-sandbox:basic-v1

docker build -f Dockerfile.docker -t docker.io/YOUR_DOCKER_ID/onedev-sandbox:docker-v1 .
docker push docker.io/YOUR_DOCKER_ID/onedev-sandbox:docker-v1

Docker Sandboxes has a separate image store from the host's Docker Engine. Publish the images before using them in OneDev, and include docker.io/ in template references as shown above. See Docker's template loading guide.

For a private repository, the sandbox host's sbx login account must have read access. OneDev's executor and step Registry Logins apply to containers inside the sandbox; template pulls use the host's sandbox registry credentials.

Use the Template in a Job​

Create or edit .onedev-buildspec.yml using OneDev's build specification editor:

  1. Add a job named test-sandbox.

  2. Enable Execute In Sandbox and set Sandbox Template to docker.io/YOUR_DOCKER_ID/onedev-sandbox:basic-v1.

  3. Select the sandbox executor configured earlier under Job Executor, or leave it empty to use the first applicable sandbox executor.

  4. Add a Checkout Code step, leaving the default clone credential selected.

  5. Add an Execute Commands step. Disable Run In Container, choose POSIX Compatible Shell with shell sh, and enter:

    set -e
    git --version
    git lfs version
    python3 --version
    git status --short

Commit the build specification and run the job. The log should show a successful checkout and the Git, Git LFS, and Python versions installed in your template. Replace the example commands with your project's build and tests.

Use Docker in the Job​

Change Sandbox Template to docker.io/YOUR_DOCKER_ID/onedev-sandbox:docker-v1. Keep Run In Container disabled to run Docker or Compose directly from the VM, and use these commands to verify the template:

set -e
docker info
docker buildx version
docker compose version
docker run --rm alpine:3.22 echo "Container running inside the sandbox"

Commit the changes and rerun the job. The log should show Docker server information, plugin versions, and Container running inside the sandbox. You can then replace these checks with docker build or docker compose commands for your project, or add OneDev's Docker-related steps and job services.

Another approach is to let OneDev manage the container for your Execute Commands step. Enable Run In Container and set Image to an image such as node:24 for Node.js and npm. OneDev starts a container inside the sandbox VM and runs the step's commands there. The job still needs a Docker-enabled Sandbox Template to provide the VM and Docker installation, while the step's Image provides the build tools.

When updating your template, publish a new tag such as docker-v2 and update Sandbox Template in the job definition.