- Shell 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| tests | ||
| .gitattributes | ||
| .gitignore | ||
| check-project.sh | ||
| docker-rootless | ||
| install-docker-rootless.sh | ||
| README.md | ||
| upgrade-docker-rootless-engine.sh | ||
| wiki.md | ||
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.