bootstrap-docker

name

bootstrap-docker

description

Safely preview, install, configure, and verify Docker Engine CE on Ubuntu or Debian hosts through an apt repository. Use when Codex needs to initialize Docker on a new Ubuntu/Debian server, replace distro-provided Docker packages with Docker CE, choose an official or China-accessible mirror, install a pinned Docker version, enable the Docker service, or grant an existing user non-root Docker access.

Bootstrap Docker

Use the bundled installer for Ubuntu and Debian. Prefer the repository workflow over get.docker.com, especially on production systems.

Safety contract

• Run a preview first. Require --apply before changing packages, apt sources, services, or group membership.
• Do not replace an existing working Docker installation unless the user asks for it. Inspect docker version, installed packages, /etc/os-release, and the current Docker apt source first.
• Treat membership in the docker group as root-equivalent access. Add a user only when the user explicitly requests non-root Docker access.
• Do not remove conflicting packages unless the preview identifies them and the user approves --replace-conflicts.
• Default to Docker's official repository. Select a mirror only when required by the target network or requested by the user.
• Do not pipe a downloaded installation script directly into a shell. The bundled installer downloads only the repository signing key and installs packages through apt.
• Do not delete /var/lib/docker or /var/lib/containerd during initialization. Treat data removal and uninstallation as separate destructive work.
• On a remote host, transfer or inspect the script before execution and use the user's existing secure SSH access. Do not embed credentials or host identifiers in the skill.

Inspect the host

Collect the following without mutation:

cat /etc/os-release
dpkg --print-architecture
command -v docker || true
docker version 2>/dev/null || true
dpkg-query -W -f='${binary:Package}\t${Version}\n' \
  docker-ce docker-ce-cli containerd.io docker.io docker-compose docker-doc podman-docker containerd runc \
  2>/dev/null || true
test -f /etc/apt/sources.list.d/docker.list && \
  sed -n '1,20p' /etc/apt/sources.list.d/docker.list

Stop if the distribution is not Ubuntu or Debian. If Docker already works, clarify whether the goal is only verification, an upgrade, mirror migration, or user access.

Preview

Run the installer without --apply:

bash scripts/install_docker.sh

Useful options:

bash scripts/install_docker.sh --source ustc
bash scripts/install_docker.sh --version '5:28.3.2-1~ubuntu.24.04~noble'
bash scripts/install_docker.sh --user service-user
bash scripts/install_docker.sh --replace-conflicts

Supported sources are official, ustc, tencent, aliyun, and volcengine. Use --repo-base URL only for a trusted Docker-compatible mirror. A pinned --version must be the exact string returned by apt-cache madison docker-ce after the repository is configured.

Review the detected OS, codename, architecture, repository URL, conflicting packages, package versions, service action, and optional group change.

Apply

Repeat the reviewed command as root with --apply. Add --replace-conflicts only after approving the listed package removals.

sudo bash scripts/install_docker.sh --apply

To grant an existing user Docker access:

sudo bash scripts/install_docker.sh --user service-user --apply

Tell the user that new group membership normally requires logging out and back in, or starting a new login session. Do not claim that the current shell has acquired it.

Verify

Run checks proportional to the requested setup:

systemctl is-enabled docker
systemctl is-active docker
docker version
docker info
docker compose version
docker buildx version

Run sudo docker run --rm hello-world only when pulling a public test image is acceptable. For a configured non-root user, verify in a fresh login session:

id
docker info

Report the installed Docker version, active/enabled service state, configured repository source, and whether a fresh login is needed.

Failure handling

• If apt reports an unsupported codename or missing Release file, stop and choose a compatible repository; do not substitute another codename silently.
• If repository key download fails, verify network/DNS/proxy access and source selection. Do not disable signature verification.
• If conflicting packages are present, return to preview and obtain approval before using --replace-conflicts.
• If docker.service fails, inspect systemctl status docker --no-pager and journalctl -u docker --no-pager -n 100; do not repeatedly reinstall.
• If Docker works only with sudo, verify group membership and use a fresh login session. Do not loosen the Docker socket permissions.
• If an existing installation contains containers or images, preserve /var/lib/docker and /var/lib/containerd unless the user explicitly requests destructive cleanup.

Read references/design-notes.md when the user asks about installation approaches, mirror mapping, version pinning, or uninstallation.