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.
Is Docker the right tool here?
Section titled “Is Docker the right tool here?”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/dockerby 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.
Install
Section titled “Install”apk updateapk add dockerd docker/etc/init.d/dockerd enable/etc/init.d/dockerd startdocker infoThe 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.
Registry mirror (region-specific)
Section titled “Registry mirror (region-specific)”Docker Hub timed out from this lab. A mirror made pulls work:
uci add_list dockerd.globals.registry_mirrors='https://docker.m.daocloud.io'uci commit dockerd/etc/init.d/dockerd restartThis is not a universal recommendation. Use a mirror you trust and verify image digests. A mirror can be stale or unavailable.
Storage
Section titled “Storage”The default data root is /opt/docker/:
uci show dockerddocker info | grep -E 'Docker Root Dir|Storage Driver'df -h /opt- Keep
/opt/dockeron 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 dfand 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.
Networking and ports
Section titled “Networking and ports”ip link show docker0docker run --rm hello-worlddocker 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:alpinecurl -sS http://127.0.0.1:8082In the lab:
hello-worldpulled and ran;- the Alpine volume wrote
/tmp/docker-test/helloon the host; - nginx published
8082:80and 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;
hostnetworking bypasses Docker’s port mapping; understand the exposure;- do not expose the Docker socket or API to the LAN.
The reboot failure that matters
Section titled “The reboot failure that matters”After reboot, Docker started but docker0 was missing:
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 existA new container also failed the same way. The recovery was:
/etc/init.d/dockerd restartip link show docker0docker run -d --name rh-test-http3 -p 8082:80 nginx:alpinecurl -sS http://127.0.0.1:8082After 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:
--restartis not a substitute for checkingdocker0after 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.
Application examples (E1)
Section titled “Application examples (E1)”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.
Failure matrix
Section titled “Failure matrix”| 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 |
Recovery
Section titled “Recovery”- Stop the app/container; keep the router reachable.
- Check
ip link show docker0; restartdockerdif missing. - Check
docker ps -aand the container error. - If storage is gone, fix the mount before starting Docker.
- Remove stale containers/networks only when you understand them; do not prune blindly on a production host.
- If Docker is not essential, disable it:
/etc/init.d/dockerd stop; /etc/init.d/dockerd disable.
E2 lab run (2026-10-26)
Section titled “E2 lab run (2026-10-26)”- OpenWrt 25.12.6 x86 VM 200; Docker 29.6.1; containerd/runc installed via apk.
- Registry mirror
https://docker.m.daocloud.io;hello-worldpulled/ran. - Alpine volume wrote
/tmp/docker-test/hello; nginx published8082:80and served HTTP. - Reboot:
docker0missing; existing and new containers failed withveth ... Device does not exist. /etc/init.d/dockerd restartrecreateddocker0; new nginx container worked on8082.- Not tested: USB/SSD data root, AGH/HA/NAS, real-router power loss, firewall exposure, container auto-start after reboot.
Sources and review
Section titled “Sources and review”- 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
Independent OpenWrt notes. Every page states the firmware, device, package manager and way back.
Icons: Solar by 480 Design, CC BY 4.0