OpenWRT Docker: How to Run and Manage Docker Containers on OpenWRT

Running OpenWRT Docker unlocks a new flexibility level for power users and network administrators. OpenWRT is a lightweight Linux-based operating system for routers and is widely used for advanced customization, firewall control, and network optimization features. When combined with Docker, which is one of the best containerization platforms, it transforms your router into a compact, multi-purpose server that is capable of hosting isolated applications on your network. 

Whether you want to run a local DNS resolver, deploy ad-blocking tools like Pi-hole or use lightweight web services, using OpenWRT Docker can make it possible. With the right preparation, compatible hardware, and clear understanding of how containers integrate, you can set up Docker on OpenWRT. 

In this guide, we will walk through everything that you need to know about OpenWRT Docker.

What Is OpenWRT and Docker 

OpenWRT is one of the open-source Linux distributions that is designed specifically for embedded devices like routers and network gateways. It replaces the stock firmware provided by router manufacturers using a customizable system that gives full control over networking and security. 

Docker is a lightweight containerization platform that allows you to run applications in isolated containers. Each container has a complete package that you need to run an application, from the code to libraries and dependencies. 

When you use OpenWRT Docker, you get the flexibility to deploy multiple self-contained applications directly on your router. This means that you can run services like Pihole, AdGuard Home, or network monitoring tools without relying on a separate PC or server. 

So what are the benefits of using Docker on OpenWRT?

1. Since OpenWRT is lightweight and Docker adds a negligible overhead, it helps with efficient resource utilization. 
2. Since OpenWRT already excels at traffic management, running Docker on it allows you to host and control network services directly. 
3. The container runs independently, so if one of the services fails or is compromised, it won’t affect the rest of your system. 
4. With Docker, you can easily pull and run applications without complex installations. 
5. You can run multiple network tools, from VPN clients and proxies to DNS blockers, directly on your router. 

Step-by-Step Guide To Install OpenWRT Docker 

Prerequisites for Installing Docker on OpenWRT

Make sure that your system fulfils the following prerequisites before installing Docker on OpenWRT. 

1. Hardware Requirements

• A router or device with at 1GB of RAM and sufficient flash storage (preferably more than 16GB).
• ARM, x86, or x86_64 architecture, Docker is not supported on all MIPS-based routers.
• External storage (USB drive or SSD) if your internal space is limited.

2. OpenWRT Version

• Docker requires OpenWRT 19.07 or newer.
• Firmware with kernel modules for cgroups and overlayfs. 

3. Network and Package Dependencies

• A working internet connection on your OpenWRT device.
• Update your package lists using:
  opkg update
• Recommended packages:
  opkg install dockerd docker docker-compose luci-app-dockerman

(The luci-app-dockerman package provides a web interface for managing Docker via LuCI.)

How to Install Docker on OpenWRT

Once the prerequisites are in place, you can follow these steps to install and enable Docker on your OpenWRT router. 

• Step 1: Update System Packages

opkg update && opkg upgrade

• Step 2: Install Docker and Its Dependencies

opkg install dockerd docker

• Step 3: Enable and Start Docker Service

/etc/init.d/dockerd enable

/etc/init.d/dockerd start

• Step 4: Verify Installation

Check if Docker is running:

docker version

If successful, you’ll see the Docker client and server versions printed in the terminal.

Running Docker Containers on OpenWRT

Once OpenWRT Docker is up and running successfully, you can start to deploy containers from the router. 

1. Pull a Docker Image

Example: Running an Alpine Linux container.

docker pull alpine

2. Run a Container

docker run -it –name test-container alpine /bin/sh

This command would launch a lightweight Alpine Linux shell inside the container. 

3. Run Useful Network Applications

You can host services like:

• Pi-hole for ad-blocking
• AdGuard Home for DNS filtering
• Watchtower for automatic container updates

Example:

docker run -d –name pihole -p 53:53/tcp -p 53:53/udp -p 80:80 pihole/pihole

4. Manage Containers

List running containers:

docker ps

Stop or remove containers as needed:

docker stop <container_name>

docker rm <container_name>

Configuring Docker Networking on OpenWRT

Docker’s network configuration determines how the containers will connect to the internet and your LAN. On OpenWRT, it is essential to manage all this properly to avoid IP conflicts or routing issues. 

1. Default Bridge Network

By default, Docker creates a docker0 bridge network. You can inspect it with:

ip addr show docker0

This bridge allows containers to communicate internally with each other and access the internet via NAT. 

2. Custom Bridge Network

You can create a custom Docker bridge using a specific subnet for better control routing: 

docker network create –subnet=172.20.0.0/16 my_bridge

3. Host Networking

If you want your container to use the router’s network stack directly, run: 

docker run –network host <image_name>

4. Integrating with OpenWRT Firewall

If Docker containers need to communicate either outside to within the LAN, add forwarding rules in LuCI → Network → Firewall.

Or manually allow traffic:
iptables -I FORWARD -i docker0 -o br-lan -j ACCEPT

iptables -I FORWARD -i br-lan -o docker0 -j ACCEPT

Managing Docker via Docker Compose 

Even though you could run containers manually using Docker commands, Docker Compose helps simplify the process by allowing you to define multi-container applications in a single YAML file. This is particularly useful when you are running complex setups like Pihole with Unbound or an ARR stack directly on OpenWRT.

1. Install Docker Compose on OpenWRT

If it’s not already installed:

opkg install docker-compose

If unavailable in your repository, install it manually:

wget https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-armv7

chmod +x docker-compose-linux-armv7

mv docker-compose-linux-armv7 /usr/bin/docker-compose

2. Create a docker-compose.yml File

version: ‘3’

services:

  adguardhome:

    image: adguard/adguardhome

    container_name: adguardhome

    ports:

      – “53:53/tcp”

      – “53:53/udp”

      – “80:80”

    restart: unless-stopped

  watchtower:

    image: containrrr/watchtower

    container_name: watchtower

    volumes:

      – /var/run/docker.sock:/var/run/docker.sock

    restart: unless-stopped

3. Launch Containers

docker-compose up -d

4. Manage Containers

• Start services: docker-compose start
• Stop services: docker-compose stop
• View logs: docker-compose logs -f

Using Docker Compose allows you to conveniently manage and work with the OpenWRT router. 

Troubleshooting Common Docker on OpenWRT Issues

Issue	Possible Cause	Solution
Docker fails to start	Missing kernel modules or insufficient memory	Ensure cgroup and overlayfs modules are enabled; free up memory or use external storage
docker: command not found	Docker not installed or PATH misconfigured	Reinstall using opkg install docker dockerd and restart your router
Low storage space errors	Router flash memory is too small	Mount external USB or SSD and move /var/lib/dockerthere
Network connectivity issues inside containers	Misconfigured bridge or firewall	Check docker0 bridge; add iptables forwarding rules for LAN access
Containers can’t access DNS	Docker daemon using wrong DNS	Add DNS servers in /etc/docker/daemon.json and restart Docker
Docker not starting on boot	Service not enabled	Run /etc/init.d/dockerd enable
Performance lag or high CPU	Too many active containers	Limit the number of running containers or use lightweight images
LuCI Docker interface missing	GUI package not installed	Run opkg install luci-app-dockerman and refresh LuCI
Permission denied errors	User privileges issue	Run Docker commands as root or use sudo
Compose file fails to deploy	YAML formatting errors	Validate using docker-compose config before starting services

Conclusion

Running Docker on OpenWRT is an excellent way to expand on your router’s functionality, turning it into a compact and versatile home server. It allows you to deploy services like DNS blocks, VPN clients, and more. 

FAQs