Docker rootless installation and upgrade scripts
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Claude 7ae9bc4074 Remove wiki references from wiki.md - projects are standalone
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-10-16 10:31:26 +00:00
tests Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
.gitattributes Add git project essentials: .gitattributes, .gitignore, wiki.md 2026-10-16 10:30:40 +00:00
.gitignore Add git project essentials: .gitattributes, .gitignore, wiki.md 2026-10-16 10:30:40 +00:00
check-project.sh Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
docker-rootless Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
install-docker-rootless.sh Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
README.md Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
upgrade-docker-rootless-engine.sh Initial commit: docker-rootless setup 2026-10-16 10:27:55 +00:00
wiki.md Remove wiki references from wiki.md - projects are standalone 2026-10-16 10:31:26 +00:00

docker-rootless — independent user-owned Docker Engine

A separate, rootless Docker daemon for the existing Ubuntu login account. This project is independent of Chromium and of docker-isolated. It does not replace docker, modify /var/run/docker.sock, stop the host's system docker.service, change host iptables, create a host bridge, or touch the docker-isolated namespace.

Validated by offline/static checks only in this archive: the installer must be run and the service verified on the target Ubuntu 18.04 / cgroup v2 laptop.

Re-runnable Docker 29 installer (default behavior)

./install-docker-rootless.sh always applies the managed installation, including when docker-rootless.service already exists. No longer prints "Existing installation retained" and exits. Just like docker-isolated, it reconciles the base user unit, its pinned Docker 29.9.1 PATH/runtime launcher, wrapper CLI, and user service. It restarts ONLY the rootless daemon and then checks the actual server version, rootless identity, data root and image store.

# As normal user, without sudo, safe to run for an existing rootless service
./install-docker-rootless.sh

docker-rootless version
docker-rootless info

The installer retains ~/.local/share/docker-rootless, the existing ~/.config/docker-rootless/daemon.json, your RootlessKit MTU/network settings, and volume data. It also honors the current classic or containerd image-store choice rather than silently switching storage. It stages the official Docker 29.9.1 rootless-extras if not already available locally; fresh installs also get the same Docker 29 runtime on their first run. It requires the system's Docker 29 binaries at /opt/docker-static/29.9.1/bin (can be changed with DOCKER_ROOTLESS_ENGINE_DIR).

By default, a rerun refuses to interrupt running rootless containers. Stop them cleanly first, or explicitly run DOCKER_ROOTLESS_ALLOW_RUNNING=1 ./install-docker-rootless.sh if you accept the service restart interrupting them. A project-managed user unit is required before the installer will rewrite it; arbitrary third-party units are not silently replaced.

For read-only preflight you can still run --check-engine; the old --upgrade-engine flag remains available as an engine-only operation.

Switch docker-rootless and docker-host to containerd image store

The project ships a separate opt-in script to switch these two otherwise independent Docker 29 daemons. The installer does not enable the new image store implicitly for an established data root.

# Desktop user, NOT sudo. Uses sudo internally only for docker-host.
./enable-containerd-image-store.sh --both

# Or one daemon at a time
./enable-containerd-image-store.sh --rootless
./enable-containerd-image-store.sh --host

# Confirm
 docker-rootless info --format '{{json .DriverStatus}}'
 docker-host info --format '{{json .DriverStatus}}'

Look for io.containerd.snapshotter.v1 in each result. Switching hides the previous overlay2 image/container inventory, leaving it on disk; volumes and other daemon settings remain. The script confirms no containers are running, backs up each daemon.json alongside the original, keeps other JSON settings, and performs a daemon restart plus a BusyBox startup test. If the containerd store cannot start or fails the startup test, it restores the previous config and restarts the affected daemon. Registry failures are reported separately.

docker-isolated is never changed by this script. It remains on classic overlay2 until you separately plan its data migration. If your rootless application stack has blocked egress rules, rerun its firewall integration checks after changing storage to verify policy is still enforced.

Cgroup warnings

No memory limit support, No cpuset support, and I/O-controller warnings on Ubuntu 18.04/systemd 237 can persist after the Docker 29 upgrade. That is rootless systemd delegation, not evidence that the new image store failed.

Before installation

Prerequisites: docker, dockerd-rootless.sh, rootlesskit, slirp4netns, fuse-overlayfs, newuidmap, newgidmap, systemctl --user, and valid 65,536+ subuid/subgid ranges for your existing login. docker compose plugin is needed by Chromium but not by the daemon installer. Log into the actual Ubuntu desktop user session. Run the installer without sudo.

To check which cgroup setup is active: stat -fc %T /sys/fs/cgroup should print cgroup2fs for the current working nested-DinD configuration. This installer never edits cgroups, GRUB, kernel options, or the main Docker daemon.

Fresh install

bash install-docker-rootless.sh

Existing rootless engine (most relevant to your laptop)

You already installed a rootless user docker.service using the setup tool. The installer intentionally refuses to overwrite that running daemon on its first invocation. Inspect the existing daemon before migrating:

docker -H unix:///run/user/$(id -u)/docker.sock info --format '{{.SecurityOptions}} {{.DockerRootDir}}'
docker -H unix:///run/user/$(id -u)/docker.sock volume ls

Then perform the one-time adoption:

bash install-docker-rootless.sh --migrate-existing

This stops and disables only your user docker.service, moves ~/.local/share/docker to ~/.local/share/docker-rootless (preserving image, container, named-volume, firewall CA, and other state), creates a new user docker-rootless.service, and starts it on the same /run/user/<UID>/docker.sock so Chromium's firewall Compose continues to work. It refuses to proceed if it finds a conflicting data directory or a custom old data-root: resolve that manually instead of risking your volumes.

The installer does not remove the old user docker.service file. It remains disabled as a recovery reference. Do not enable both services simultaneously: they bind the same Unix socket.

Important: do not run docker compose down -v during migration, since that removes named volumes regardless of their directory.

Usage

The installer places a wrapper at ~/.local/bin/docker-rootless:

docker-rootless ps
docker-rootless images
docker-rootless volume ls
docker-rootless compose up -d --build
systemctl --user status docker-rootless
systemctl --user restart docker-rootless
journalctl --user -u docker-rootless -n 100 --no-pager

The wrapper pins the user daemon's Unix socket and ignores your existing Docker context / DOCKER_HOST. The ordinary docker and docker-host commands are left untouched. If ~/.local/bin isn't in the current shell's PATH, use its full path or put ~/.local/bin in PATH for your shell. Optional launch without an active login: sudo loginctl enable-linger "$(id -un)" (explicit user choice).

Files and networks

Purpose Path
Engine data, images, volumes ~/.local/share/docker-rootless/
Daemon settings ~/.config/docker-rootless/daemon.json
User systemd service ~/.config/systemd/user/docker-rootless.service
Runtime socket /run/user/<UID>/docker.sock
CLI wrapper ~/.local/bin/docker-rootless

Default address plan (override before installing via environment variables):

Network CIDR Explanation
Rootless default bridge 172.30.79.1/24 DOCKER_ROOTLESS_BRIDGE_CIDR
Rootless automatically allocated Compose networks 172.30.80.0/20, /24s DOCKER_ROOTLESS_POOL_CIDR
Chromium's explicit firewall network 172.30.77.0/24 Reserved separately in Chromium Compose
Existing docker-isolated networks 172.29.x / 172.31.x Not modified

RootlessKit's slirp4netns is used for user-mode network egress; its internal network is distinct from Docker's bridge/address-pool settings. On this installation the RootlessKit MTU is 1400 (change at install time using DOCKER_ROOTLESS_MTU). Fixed CIDRs avoid collisions within the rootless daemon and the known local Docker setups. Host/VPN routes are reported as warnings, not treated as proof of a conflict: a broad VPN route such as 128.0.0.0/2 also covers 172.30.x, but RootlessKit places Docker bridges in a separate network namespace. A narrow, overlapping host/VPN route can still affect access to services outside rootless, including cross-daemon access. Test the actual connectivity after installation. Rootless bridges do not create host docker0 routes. No VPN, host routing tables, or main Docker configuration is changed.

Existing Docker networks retain their old IPAM settings after adoption; new networks use the updated address pool. If changed later, restart the service only after reviewing consequences for running workloads.

Cross-daemon access (design note, not implemented)

Rootless and docker-isolated are different daemons and network namespaces. Containers cannot resolve each other's Compose service names or assume that 172.30.x container IPs are routable cross-daemon. Expose only deliberately selected services via host-bound TCP ports or purpose-built relays, with access control. For claude-cloud, a host-published endpoint or reverse proxy can be used; for isolated databases, a narrowly scoped relay can forward selected ports. The Chromium firewall boundary must be preserved: don't attach its untrusted DinD/Chromium directly to unrestricted networks or add arbitrary private-service destinations to a broad proxy allowlist.

Design rationale

The docker-isolated reference changes system-level socket and routing setup. This standalone user daemon intentionally does none of those system-level changes. It manages only the current user's service and state. Rootless mode provides a useful outer privilege boundary but does not itself enforce the Chromium URL firewall; that is a separate Compose/mitmproxy configuration.

Moving from docker-isolated

Do not attempt to move the inner DinD Docker data-root from docker-isolated as though it were a normal app volume. This installer does not migrate between daemons.