tool-containers
Search docs…Ctrl K
Menu
GitHub (opens in new tab)

Run devbox with Docker

run.sh opens a devbox shell on the current directory, or runs one command there. It can also give the shell access to the host's Docker daemon.

Images
  • GHCRghcr.io/hambn/devbox
  • Docker Hubdocker.io/hambn/devbox
Use case
Interactive development shell on a checkout
Source
tools/base/devbox/docs/docker (opens in new tab)
On this page

Prerequisites

  • Docker Engine 23 or later.

Open a shell

Shell
./run.sh                                          # Zsh login shell in /workspace
./run.sh zsh -lc 'go version && node --version'   # one command

To build and run containers from inside the shell, mount the host's Docker socket. This works on the full and browser tiers, which include the Docker CLI:

Shell
DEVBOX_DOCKER_SOCKET=/var/run/docker.sock ./run.sh

The script adds the socket's group to the container so sysadmin can use it. Anyone with the socket has root-equivalent access to the host.

Variables

Variable Required Purpose
DEVBOX_IMAGE no Image to run. Defaults to ghcr.io/hambn/devbox:ubuntu-full; use any variant, or a digest reference to pin one build.
DEVBOX_DOCKER_SOCKET no Host Docker socket to mount at /var/run/docker.sock.

Workspace

The current directory is mounted at /workspace. The shell runs as sysadmin (UID 1000), so new files belong to UID 1000 on the host. --rm deletes the container, and everything outside /workspace, when you exit.

Files

  • run.sh runs the image with a 1 GB /dev/shm for the browser tier and the optional Docker socket.

File contents

run.sh24 lines
#!/usr/bin/env bash
# Open a devbox shell, or run one command, with the current directory at /workspace.
set -euo pipefail

image=${DEVBOX_IMAGE:-ghcr.io/hambn/devbox:ubuntu-full}
docker_options=()
if [[ -n "${DEVBOX_DOCKER_SOCKET:-}" ]]; then
    [[ -S "$DEVBOX_DOCKER_SOCKET" ]] || {
        echo "not a Docker socket: $DEVBOX_DOCKER_SOCKET" >&2
        exit 1
    }
    docker_options+=(
        --volume "$DEVBOX_DOCKER_SOCKET:/var/run/docker.sock"
        --group-add "$(stat -c %g "$DEVBOX_DOCKER_SOCKET")"
    )
fi

# Headless Chromium in the browser tier needs more than the 64 MB default /dev/shm.
docker run -it --rm \
    "${docker_options[@]}" \
    --shm-size=1g \
    --volume "$PWD:/workspace" \
    --workdir /workspace \
    "$image" "$@"

Topics