1 files changed, 62 insertions, 23 deletions
diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md
index 10da8d41..8ee7634d 100644
--- a/docs/installation/virtual/docker.md
+++ b/docs/installation/virtual/docker.md
@@ -1,6 +1,10 @@
+---
+lastproofread: '2026-08-30'
+---
+
 (docker)=
 
-# Running in 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
@@ -9,9 +13,10 @@ 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.
+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.
 
 ### Method 1: Create a docker network with IPv6 support
 
@@ -21,9 +26,9 @@ Here is a 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
+### Method 2: Add IPv6 support to the Docker daemon
 
-Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify
+Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and specify
 the `fixed-cidr-v6` to your desired IPv6 subnet.
 
 ```none
@@ -41,27 +46,61 @@ $ sudo systemctl reload docker
 
 ## Deploy container from ISO
 
-Download the ISO on which you want to base the container. In this example,
-the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you
-created a custom IPv6-enabled network, the `docker run` command below
-will require that this network be included as the `--net` parameter to
+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.4.5-oci-amd64.tar
+I: to import the previously generated OCI image to your local images run:
+
+   docker import vyos-1.4.5-oci-amd64.tar vyos:1.4.5 --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.4.5-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.4.5-oci-amd64.tar vyos:1.4.5 \
+> --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.4.5
 $ docker exec -ti vyos su - vyos
 ```
 
-You can execute `docker stop vyos` when you are finished with the container.
+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.
+:::