From 65c36ea6029652123ceee6d163aede23d1b46560 Mon Sep 17 00:00:00 2001
From: Christian Breunig <christian@breunig.cc>
Date: Sun, 30 Aug 2026 15:36:42 +0200
Subject: T9265: Update documentation for container image build

(cherry picked from commit 9a39835d9096bbdab37c97950ce3010ad2bc1402)
---
 docs/installation/virtual/docker.md | 77 +++++++++++++++++++++++++++----------
 1 file changed, 56 insertions(+), 21 deletions(-)

(limited to 'docs/installation/virtual/docker.md')

diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md
index 3489b94a..6d980066 100644
--- a/docs/installation/virtual/docker.md
+++ b/docs/installation/virtual/docker.md
@@ -1,10 +1,10 @@
 ---
-lastproofread: '2026-02-02'
+lastproofread: '2026-08-30'
 ---
 
 (docker)=
 
-# Run VyOS in a Docker Container
+# Run VyOS as a container
 
 Docker is an open-source project for deploying applications as standardized
 units called containers. Deploying VyOS in a container provides a simple and
@@ -14,8 +14,9 @@ workloads.
 ## IPv6 support for Docker
 
 VyOS requires an IPv6-enabled Docker network. Currently Linux distributions
-do not enable Docker IPv6 support by default. You can enable IPv6 support in
-two ways.
+do not enable Docker IPv6 support by default.
+
+You can enable IPv6 support in two ways.
 
 ### Method 1: Create a docker network with IPv6 support
 
@@ -25,7 +26,6 @@ Here's an example using the `macvlan` driver.
 docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet
 ```
 
-
 ### Method 2: Add IPv6 support to the Docker daemon
 
 Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and specify
@@ -47,26 +47,61 @@ $ sudo systemctl reload docker
 
 ## Deploy container from ISO
 
-Download the ISO you want to base the container on. In this example,
-the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you
-created a custom IPv6-enabled network, include it as the `--net` parameter
-to `docker run`.
+A VyOS ISO image can be converted into an OCI (Open Container Initiative)
+image using the `iso-to-oci` helper script from the
+[vyos-build](https://github.com/vyos/vyos-build) repository. The script
+extracts the root filesystem from the ISO, removes components which are not
+usable inside a container (kernel, firmware, and the corresponding CLI nodes),
+and generates a tarball which can be imported by Docker.
+
+The script requires `xorriso`, `squashfs-tools` and `jq` to be installed. All
+of them are already present in the vyos-build container.
+
+### Build a container image from a locally built ISO
+
+If you build your own ISO from source (see {ref}`build`), the `oci` make
+target converts the ISO which is generated in `build/` in one step:
+
+```none
+$ make oci
+I: extracting ISO metadata
+I: extracting squashfs image
+I: extracting squashfs content
+I: generate OCI container image vyos-1.5.1-oci-amd64.tar
+I: to import the previously generated OCI image to your local images run:
+
+   docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 --change 'CMD ["/sbin/init"]'
+```
+
+### Build a container image from a downloaded ISO
+
+To use a released or nightly ISO instead, call the script directly and pass
+the path to the ISO image:
+
+```none
+$ git clone https://github.com/vyos/vyos-build.git
+$ ./vyos-build/scripts/iso-to-oci vyos-1.5.1-generic-amd64.iso
+```
+
+### Import and run the container
+
+Import the generated tarball as a local image and start the container. If you
+created a custom IPv6-enabled network, include it as the `--net` parameter to
+`docker run`.
 
 ```none
-$ mkdir vyos && cd vyos
-$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso
-$ mkdir rootfs
-$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs
-$ sudo apt-get install -y squashfs-tools
-$ mkdir unsquashfs
-$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs
-$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249
-$ sudo umount rootfs
-$ cd ..
-$ sudo rm -rf vyos
+$ docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 \
+> --change 'CMD ["/sbin/init"]'
 $ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \
-> vyos:1.4-rolling-202111281249 /sbin/init
+> vyos:1.5.1
 $ docker exec -ti vyos su - vyos
 ```
 
 To stop the container, run `docker stop vyos`.
+
+:::{hint}
+The very same image can also be used with
+[Containerlab](https://containerlab.dev) to build virtual network labs. Refer
+to its [VyOS kind](https://containerlab.dev/manual/kinds/vyosnetworks_vyos/)
+documentation for the required node settings.
+:::
-- 
cgit v1.2.3