mirror of https://github.com/openwrt/docker.git
229 lines
8.3 KiB
Markdown
229 lines
8.3 KiB
Markdown
# OpenWrt Docker repository
|
|
|
|
[![GPL-2.0-only License][license-badge]][license-ref]
|
|
[![CI][ci-badge]][ci-ref]
|
|
[![Docker Hub][docker-hub-badge]][docker-hub-ref]
|
|
|
|
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](https://hub.docker.com/r/openwrt/sdk) | [imagebuilder](https://hub.docker.com/r/openwrt/imagebuilder) | [rootfs](https://hub.docker.com/r/openwrt/rootfs)) `*`
|
|
* ghcr.io ([sdk](https://github.com/openwrt/docker-openwrt/pkgs/container/sdk) | [imagebuilder](https://github.com/openwrt/docker-openwrt/pkgs/container/imagebuilder) | [rootfs](https://github.com/openwrt/docker-openwrt/pkgs/container/rootfs))
|
|
* quay.io ([sdk](https://quay.io/repository/openwrt/sdk) | [imagebuilder](https://quay.io/repository/openwrt/imagebuilder) | [rootfs](https://quay.io/repository/openwrt/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](https://openwrt.org/docs/guide-developer/toolchain/using_the_sdk) based on
|
|
the same container we use for our [Buildbot](https://buildbot.openwrt.org/)
|
|
infrastructure. This can be useful when building packages on macOS, Windows or
|
|
via CI.
|
|
|
|
### SDK Example
|
|
|
|
```shell
|
|
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](https://openwrt.org/docs/guide-user/additional-software/imagebuilder)
|
|
based on the same container we use for our [buildbot](https://buildbot.openwrt.org)
|
|
infrastructure. This can be useful when creating images on macOS, Windows or
|
|
via CI.
|
|
|
|
### ImageBuilder Example
|
|
|
|
Built images will be stored in `bin`, and cached packages, that can be reused
|
|
for other builds - in `dl`. Packages from differenet platforms/versions might
|
|
have the same package names, but different checksums, which will cause
|
|
errors during build, so working directories shouldn't be shared between
|
|
different image builders.
|
|
|
|
> If you're running on a SELinux-enabled system (e.g. RHEL), volumes must be
|
|
> mounted with a `:z` flag:
|
|
>
|
|
> ```shell
|
|
> --volume "$(pwd)"/bin/:/builder/bin:z
|
|
> ```
|
|
|
|
Using Docker:
|
|
|
|
```shell
|
|
# NB: Replace these variables, according to your needs
|
|
PLATFORM=ath79-generic
|
|
VERSION=25.12.5
|
|
PROFILE=tplink_archer-c7-v2
|
|
PACKAGES="ath10k-firmware-qca988x kmod-ath10k kmod-usb-ledtrig-usbport kmod-usb-net-cdc-ether kmod-usb2 luci luci-ssl luci-app-sqm luci-app-attendedsysupgrade owut -ppp -ppp-mod-pppoe -luci-proto-ppp -ath10k-firmware-qca988x-ct -kmod-ath10k-ct"
|
|
|
|
mkdir -p openwrt-${PLATFORM}-${VERSION}/{bin,dl}
|
|
cd openwrt-${PLATFORM}-${VERSION}
|
|
|
|
docker run --rm \
|
|
--volume "$(pwd)"/bin/:/builder/bin \
|
|
--volume "$(pwd)"/dl:/builder/dl \
|
|
openwrt/imagebuilder:${PLATFORM}-${VERSION} \
|
|
sh -c "
|
|
[ ! -d ./scripts ] && ./setup.sh;
|
|
make image PROFILE='${PROFILE}' PACKAGES='${PACKAGES}'
|
|
"
|
|
```
|
|
|
|
Using Podman we need to map user account to same UID within container using
|
|
`--userns=keep-id`:
|
|
|
|
```shell
|
|
# Same variables as above
|
|
|
|
podman run --rm \
|
|
--userns=keep-id \
|
|
--volume "$(pwd)"/bin/:/builder/bin \
|
|
--volume "$(pwd)"/dl:/builder/dl \
|
|
openwrt/imagebuilder:${PLATFORM}-${VERSION} \
|
|
sh -c "
|
|
[ ! -d ./scripts ] && ./setup.sh;
|
|
make image PROFILE='${PROFILE}' PACKAGES='${PACKAGES}'
|
|
"
|
|
```
|
|
|
|
Variables can be inlined to make these into one-liners.
|
|
|
|
> For snapshots use `VERSION=SNAPSHOT`.
|
|
|
|
### 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
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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 .
|
|
```
|
|
|
|
[ci-badge]: https://github.com/openwrt/docker/actions/workflows/containers.yml/badge.svg
|
|
[ci-ref]: https://github.com/openwrt/docker/actions/workflows/containers.yml
|
|
[docker-hub-badge]: https://img.shields.io/badge/docker--hub-openwrt-blue.svg?style=flat-square
|
|
[docker-hub-ref]: https://hub.docker.com/u/openwrt
|
|
[license-badge]: https://img.shields.io/github/license/openwrt/docker.svg?style=flat-square
|
|
[license-ref]: LICENSE
|