Use Docker in Workspace

A version of Docker is available in all workspaces. The Docker daemon is launched automatically via socket activation when /run/docker.sock is first accessed.

Use a Custom Docker Version

A custom Docker version (version 25 or later) can be installed as follows:

curl -sSfL https://download.docker.com/linux/static/stable/x86_64/docker-28.5.2.tgz | sudo tar -C /usr/local -xz
sudo mv /usr/local/docker/docker /usr/local/bin/

After restarting the workspace, the installed version of Docker will be used.

Troubleshoot Docker Daemon

The Docker daemon logs can be found at /var/log/sandbox/dockerd. Most Docker daemon failures are caused by missing packages, such as bridged.

Install buildx

The docker buildx command is provided by the buildx Docker CLI plugin. To install it on a Crafting workspace (update the version in the URL as needed):

sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo wget -O /usr/local/lib/docker/cli-plugins/docker-buildx https://github.com/docker/buildx/releases/download/v0.30.1/buildx-v0.30.1.linux-amd64
sudo chmod a+rx /usr/local/lib/docker/cli-plugins/docker-buildx

After installation, docker buildx is available.

Install buildkit

buildkit provides extended capabilities for building container images, including multi-architecture builds. Installation is straightforward (update the version in the URL as needed):

curl -sSfL https://github.com/moby/buildkit/releases/download/v0.26.3/buildkit-v0.26.3.linux-amd64.tar.gz | sudo tar -C /usr/local -zx

Then run it as a daemon by creating the file /etc/sandbox.d/daemons/buildkit.yaml:

name: buildkit
run:
  cmd: |
    mkdir -p /run/buildkit
    chown -R owner:owner /run/buildkit
    buildkitd --rootless --group owner

After that, buildctl is available.

The buildkit.yaml daemon configuration can also be embedded directly in a Template:

workspaces:
- name: example
  system:
    daemons:
    - name: buildkit
      run:
        cmd: |
          mkdir -p /run/buildkit
          chown -R owner:owner /run/buildkit
          buildkitd --rootless --group owner

Example: buildkit as a Docker Builder

The buildkit socket can be registered as a remote Docker builder. Update the daemon configuration as follows:

name: buildkit
run:
  cmd: |
    docker buildx inspect buildkit >/dev/null 2>&1 || docker buildx create --name buildkit --platform linux/amd64,linux/arm64 --driver remote unix:///run/buildkit/buildkitd.sock
    mkdir -p /run/buildkit
    chown -R owner:owner /run/buildkit
    buildkitd --rootless --group owner

To build using this builder, run:

docker buildx build --builder=buildkit ...

Pull Images from a Private ECR

After setting up AWS Access, use the AWS ECR credential helper to enable private ECR access without storing credentials. If not already installed:

sudo curl -o /usr/local/bin/docker-credential-ecr-login \
          -sSfL https://amazon-ecr-credential-helper-releases.s3.us-east-2.amazonaws.com/0.8.0/linux-amd64/docker-credential-ecr-login
sudo chmod a+rx /usr/local/bin/docker-credential-ecr-login

Then add the following to ~/.docker/config.json:

{
  "credHelpers": {
    "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login"
  }
}

You can then pull images with:

docker pull <aws_account_id>.dkr.ecr.<region>.amazonaws.com/...