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

Run devbox with Docker Compose

The devbox service runs devbox with your workspace mounted and a named volume for /home/sysadmin, so shell history, tool caches, and ~/.kube survive between runs. compose.sh checks that WORKSPACE is an absolute path, because Compose would resolve a relative one against this directory, then runs docker compose here.

Images
  • GHCRghcr.io/hambn/devbox
  • Docker Hubdocker.io/hambn/devbox
Use case
Reusable shell with a persistent home
Source
tools/base/devbox/docs/docker-compose (opens in new tab)
On this page

Prerequisites

  • Docker Engine with the Compose v2 plugin.

Open a shell

Shell
WORKSPACE="$PWD" ./compose.sh run --rm devbox

The shell starts in /workspace.

Variables

Variable Required Purpose
WORKSPACE yes Absolute host path mounted at /workspace.
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.

Workspace

WORKSPACE is mounted at /workspace. Docker fills the home volume from the image the first time, and keeps it afterwards. Later images do not update it, so remove the volume to pick up new shell defaults.

Files

  • compose.sh validates WORKSPACE and passes its arguments to docker compose.
  • docker-compose.yml defines the devbox service and the home volume.

Cleanup

Remove the containers and the home volume:

Shell
WORKSPACE="$PWD" ./compose.sh down --volumes

File contents

compose.sh18 lines
#!/usr/bin/env bash
# Compose resolves relative paths against this directory, so require an absolute WORKSPACE.
set -euo pipefail

case "${WORKSPACE:-}" in
/*) ;;
"")
    echo "Set WORKSPACE to an absolute host path." >&2
    exit 2
    ;;
*)
    echo "WORKSPACE must be an absolute host path: $WORKSPACE" >&2
    exit 2
    ;;
esac

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
exec docker compose "$@"
docker-compose.yml16 lines
# WORKSPACE="$PWD" ./compose.sh run --rm devbox
name: devbox

services:
  devbox:
    image: ${DEVBOX_IMAGE:-ghcr.io/hambn/devbox:ubuntu-full}
    working_dir: /workspace
    volumes:
      - ${WORKSPACE:?Set WORKSPACE to an absolute host path}:/workspace
      - home:/home/sysadmin
    shm_size: 1g
    stdin_open: true
    tty: true

volumes:
  home:

Topics