Skip to content

Docker on OpenWrt: install, storage, networking and reboot recovery

Status: E2 for the Docker platform on a VM. AdGuard Home, Home Assistant, NAS, USB/SSD storage and real-router reboot behavior are E1. Do not run Docker on a 16 MB/128 MB router just because the package exists.

Docker needs:

  • RAM: the VM had 512 MB; containers plus daemon are tight;
  • storage: images and layers grow quickly; the root filesystem was expanded to 2 GB in this lab;
  • a writable data root (/opt/docker by default);
  • a firewall plan for published ports;
  • a recovery plan for docker0/veth failures after reboot.

If the router has 16 MB flash or 128 MB RAM, use a separate x86/N1 host instead.

Terminal window
apk update
apk add dockerd docker
/etc/init.d/dockerd enable
/etc/init.d/dockerd start
docker info

The lab installed Docker 29.6.1 on OpenWrt 25.12.6. The package pulls containerd, runc, kmods and a large dockerd binary; check free space first.

Docker Hub timed out from this lab. A mirror made pulls work:

Terminal window
uci add_list dockerd.globals.registry_mirrors='https://docker.m.daocloud.io'
uci commit dockerd
/etc/init.d/dockerd restart

This is not a universal recommendation. Use a mirror you trust and verify image digests. A mirror can be stale or unavailable.

The default data root is /opt/docker/:

Terminal window
uci show dockerd
docker info | grep -E 'Docker Root Dir|Storage Driver'
df -h /opt
  • Keep /opt/docker on a real disk, USB SSD or NVMe, not a tiny overlay;
  • mount storage before Docker starts; otherwise Docker recreates data on the root filesystem;
  • check docker system df and prune unused images/containers;
  • do not put Docker data on a filesystem that disappears on reboot.

This lab used the VM root filesystem (2 GB), not USB/SSD. That part is E1.

Terminal window
ip link show docker0
docker run --rm hello-world
docker run --rm -v /tmp/docker-test:/data alpine \
sh -c 'echo hello > /data/hello && cat /data/hello'
docker run -d --name rh-test-http -p 8082:80 nginx:alpine
curl -sS http://127.0.0.1:8082

In the lab:

  • hello-world pulled and ran;
  • the Alpine volume wrote /tmp/docker-test/hello on the host;
  • nginx published 8082:80 and returned the default page.

For a real router:

  • do not publish Docker ports to WAN by default;
  • open only the required port in the firewall zone;
  • beware port 53 conflicts with dnsmasq/AdGuard;
  • host networking bypasses Docker’s port mapping; understand the exposure;
  • do not expose the Docker socket or API to the LAN.

After reboot, Docker started but docker0 was missing:

Terminal window
ip link show docker0
# Device "docker0" does not exist
docker ps -a
# rh-test-http Exited (255)
docker start rh-test-http
# failed to create endpoint ... adding interface veth... to bridge docker0 failed:
# Device does not exist

A new container also failed the same way. The recovery was:

Terminal window
/etc/init.d/dockerd restart
ip link show docker0
docker run -d --name rh-test-http3 -p 8082:80 nginx:alpine
curl -sS http://127.0.0.1:8082

After dockerd restart, docker0 existed and the new container worked. This lab did not prove that a container with --restart unless-stopped survives a reboot without intervention; it did not.

Implications:

  • --restart is not a substitute for checking docker0 after boot;
  • a boot hook/service ordering fix is device-specific and must be tested;
  • if Docker must be reliable after power loss, test a real reboot and add monitoring;
  • do not claim “Docker auto-starts” from a running container alone.

These are not tested in this lab:

App Extra concern
AdGuard Home port 53 conflict, host vs bridge, DNS upstream
Home Assistant storage, USB Zigbee/Z-Wave, host networking
NAS/file server disk mount, permissions, SMB/NFS, power loss
Download tools disk I/O, VPN namespace, legal content

Run one app at a time; check RAM, storage and firewall before adding the next.

Symptom Check first Common cause
docker: not found package installed, PATH only dockerd installed; install docker
dockerd won’t start logread, disk space, config bad data root; missing kmod; port conflict
Pull timeout registry/mirror, DNS, proxy Docker Hub blocked; mirror down
docker0 missing after reboot ip link, service order dockerd started before network/bridge setup
veth “Device does not exist” docker0, restart dockerd stale bridge/network namespace
Published port unreachable docker ps, firewall, bind address port not published; WAN blocked; wrong zone
Container OOM/killed free, docker stats too little RAM for app
Disk full df, docker system df images/layers/logs on small root
  1. Stop the app/container; keep the router reachable.
  2. Check ip link show docker0; restart dockerd if missing.
  3. Check docker ps -a and the container error.
  4. If storage is gone, fix the mount before starting Docker.
  5. Remove stale containers/networks only when you understand them; do not prune blindly on a production host.
  6. If Docker is not essential, disable it: /etc/init.d/dockerd stop; /etc/init.d/dockerd disable.
  • OpenWrt 25.12.6 x86 VM 200; Docker 29.6.1; containerd/runc installed via apk.
  • Registry mirror https://docker.m.daocloud.io; hello-world pulled/ran.
  • Alpine volume wrote /tmp/docker-test/hello; nginx published 8082:80 and served HTTP.
  • Reboot: docker0 missing; existing and new containers failed with veth ... Device does not exist.
  • /etc/init.d/dockerd restart recreated docker0; new nginx container worked on 8082.
  • Not tested: USB/SSD data root, AGH/HA/NAS, real-router power loss, firewall exposure, container auto-start after reboot.
  • E2 platform evidence only; applications and storage are E1.
  • No independent reviewer.
  • Docker is a large attack surface; do not expose the daemon or unnecessary ports.

Sources

Router.Homes

Independent OpenWrt notes. Every page states the firmware, device, package manager and way back.

Icons: Solar by 480 Design, CC BY 4.0