Skip to content

Run core with Docker Compose

The shell service runs core with a read-only root filesystem, a tmpfs at /tmp, no capabilities, and no-new-privileges. 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/core
Docker Hubdocker.io/hambn/core
Use case: Locked-down read-only shell service
Source: tools/base/core/docs/docker-compose (opens in new tab)

On this page

Prerequisites
Open a shell
Variables
Workspace
Files
File contents
compose.sh
docker-compose.yml

Prerequisites

Docker Engine with the Compose v2 plugin.

Open a shell

Shell

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

The shell starts in /workspace. Only /workspace and /tmp are writable; remove read_only from docker-compose.yml if you need to write elsewhere.

Variables

Variable	Required	Purpose
`WORKSPACE`	yes	Absolute host path mounted at `/workspace`.
`CORE_IMAGE`	no	Image to run. Defaults to `ghcr.io/hambn/core:wolfi`; use the `alpine` or `ubuntu` tag, or a digest reference to pin one build.

Workspace

WORKSPACE is mounted at /workspace. The shell runs as UID and GID 65532, so that UID needs access to the directory.

Files

compose.sh validates WORKSPACE and passes its arguments to docker compose.
docker-compose.yml defines the shell service.

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.yml17 lines

# WORKSPACE="$PWD" ./compose.sh run --rm shell
name: core

services:
  shell:
    image: ${CORE_IMAGE:-ghcr.io/hambn/core:wolfi}
    working_dir: /workspace
    volumes:
      - ${WORKSPACE:?Set WORKSPACE to an absolute host path}:/workspace
    read_only: true
    tmpfs:
      - /tmp
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    stdin_open: true
    tty: true

Topics