OpenWrt Docker repository

This repository contains files to create OpenWrt containers. While mostly used for our CI you may use the scripts to build containers on your own.

[!WARNING] Starting with the branch of OpenWrt 24.10 any snapshot (aka nightly), builds no longer contain the actual binaries but instead a setup.sh script. The environment variables are set automatically per container to download the correct archive containing the SDK/ImageBuilder/rootfs. This dramatically reduces bandwidth and storage usage. Sorry for the inconvenience.

Available containers:

• sdk compile OpenWrt packages
• imagebuilder create firmware images
• rootfs test software inside an OpenWrt runtime

All containers are mirrored to the following three registries under openwrt account:

• docker.io (sdk | imagebuilder | rootfs) *
• ghcr.io (sdk | imagebuilder | rootfs)
• quay.io (sdk | imagebuilder | rootfs)

* We have switched our account from openwrtorg to openwrt on docker.io

Find more details on the container types below

sdk

Contains the OpenWrt SDK based on the same container we use for our Buildbot infrastructure. This can be useful when building packages on macOS, Windows or via CI.

SDK Example

docker run --rm -v "$(pwd)"/bin/:/builder/bin -it openwrt/sdk
# inside the Docker container
[ ! -d ./scripts ] && ./setup.sh
./scripts/feeds update packages
make defconfig
./scripts/feeds install tmate
make package/tmate/{clean,compile} -j$(nproc)

Enjoy a local OpenWrt SDK container building the tmate package with the binary in hosts ./bin folder.

SDK Tags

All currently available SDKs via tags in the following format:

• <target>-<subtarget>[-<branch|tag|version>]
• <arch>[-<branch|tag|version>]

The branch|tag|version can be something like openwrt-22.03 (branch), v22.03.4 (tag) or 21.02.3 (version). To use daily builds use either main or SNAPSHOT.

imagebuilder

Contains the OpenWrt ImageBuilder based on the same container we use for our buildbot infrastructure. This can be useful when creating images on macOS, Windows or via CI.

ImageBuilder Example

docker run --rm -v "$(pwd)"/bin/:/builder/bin -it openwrt/imagebuilder
# inside the Docker container
[ ! -d ./scripts ] && ./setup.sh
make image PROFILE=generic PACKAGES=tmate

Enjoy a local OpenWrt ImageBuilder container building an image for x86/64 and store the binary in hosts ./bin folder.

ImageBuilder Tags

All currently available ImageBuilders via tags in the following format:

• <target>-<subtarget>[-<branch|tag|version>]
• <arch>[-<branch|tag|version>]

The branch|tag|version can be something like openwrt-22.03 (branch), v22.03.4 (tag) or 21.02.3 (version). To use daily builds use either main or SNAPSHOT.

rootfs (experimental)

The OpenWrt runtime uses multiple active services to work, it's not really suited as a container. This rootfs should only be used for special cases like CI testing.

An unpackaged version of OpenWrt's rootfs for different architectures. The ./rootfs folder requires slight modifications to work within Docker, additional files for the rootfs should be added there before building.

Rootfs Example

docker run --rm -it openwrt/rootfs
# inside the Docker container
[ ! -d ./scripts ] && ./setup.sh
mkdir /var/lock/
opkg update
opkg install tmate
tmate

Enjoy a local OpenWrt container running the x86/64 architecture with internet access. Once closed the container is removed.

Rootfs Tags

|||armvirt/32|armvirt/64|malta/be|mvebu/cortexa9

• x86/64 or x86_64
• x86/generic or i386_pentium4
• x86/geode or i386_pentium-mmx
• armvirt/32 or arm_cortex-a15_neon-vfpv4
• armvirt/64 or aarch64_cortex-a53
• malta/be or mips_24kc
• mvebu/cortexa9 or arm_cortex-a9_vfpv3-d16

GitHub Actions CI & Registries

The GitHub Actions workflow .github/workflows/containers.yml automatically builds and pushes the containers to the registries. If you fork this repository, you can also push to your own registry accounts.

GitHub Container Registry (GHCR)

By default, the workflow will push containers to ghcr.io/${{ github.repository_owner }}/<image>. This works automatically out of the box using GitHub's built-in GITHUB_TOKEN and does not require any additional setup.

Docker Hub & Quay.io

To push to your own Docker Hub or Quay.io registries, you need to configure the following secrets under your repository's Settings -> Secrets and variables -> Actions:

• Docker Hub (docker.io):
  • DOCKER_USER - Your Docker Hub username.
  • DOCKER_TOKEN - Your Docker Hub Personal Access Token.
• Quay.io (quay.io):
  • QUAY_USER - Your Quay.io username.
  • QUAY_TOKEN - Your Quay.io OAuth Token / Password.

If these secrets are not configured, the workflow will automatically skip logging in and pushing to these registries without failing the build.

Build Your Own

If you wan to create your own container you can use the Dockerfile. You can set the following build arguments:

• TARGET - the target to build for (e.g. x86/64)
• DOWNLOAD_FILE - the file to download (e.g. imagebuilder-.*x86_64.tar.xz)
• FILE_HOST - the host to download the ImageBuilder/SDK/rootfs from (e.g. downloads.openwrt.org)
• VERSION_PATH - the path to the ImageBuilder/SDK/rootfs (e.g. snapshots or releases/21.02.3)

Example ImageBuilder

If you plan to use your own server please add your own GPG key to the ./keys/ folder.

docker build \
    --build-arg TARGET=x86/64 \
    --build-arg DOWNLOAD_FILE="imagebuilder-.*x86_64.tar.[xz|zst]" \
    --build-arg FILE_HOST=downloads.openwrt.org \
    --build-arg VERSION_PATH=snapshots \
    -t openwrt/x86_64 .