feat: import MyST swap mechanism + content for sagitta (replaces #1886)

Replaces the broken #1886 with a fresh, properly-converted MyST set for
the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897.

This PR:

- Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines
  rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc
  fallback) on sagittas RST. Post-processed via the pipelines
  postprocess stage (10 ordered fixes for blanks, admonitions, label
  hyphens, pandoc artifacts, structural blanks, linter markers).
  Compared to the broken #1886 content (which was left over from an
  earlier stage-1-only run): zero raw `<div class=>` remnants.

- For 23 stems where sagittas RST is byte-identical with currents RST
  (mostly stable policy/protocol pages and the 404 page), reuses currents
  already-validated md-*.md content rather than re-converting.

- Drops cli and installation/cloud/aws from sagittas swap set: their
  RST has SEVERE/4 "Title level inconsistent" errors that crash
  rst-to-myst; they need an independent RST-source fix and are kept as
  RST-only for now.

- Adds the per-page swap mechanism: scripts/swap_sources.py,
  scripts/import_myst.py, the matching tests under tests/, _swap.txt
  with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile
  swap-wrapped targets, .readthedocs.yml swap pre/post hooks.

- Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg
  static assets; flips html_logo to vyos-logo.webp.

- Adds the MyST swap-related blocks to docs/conf.py only:
  myst_enable_extensions, myst_fence_as_directive, md-*.md exclude
  patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources
  setup hooks. github_version fallback set to 'sagitta' to match the
  branch (parallel to currents 'current' and circinuss 'circinus').

Deliberately excluded (per user direction):

- llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will
  land separately for sagitta via #1870 plus a new sagitta-specific
  llms.txt template PR. The conf.py here does not pull those extensions
  in, so the build does not depend on the new pip packages.

Verification before pushing:

- 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1).
- 0 files contain raw `<div class=` (the breakage that took down /en/1.5/).
- conf.py copyright/version/release preserve sagittas values
  (2024 / 1.4 / "1.4.x (sagitta)") - not currents.
- html_title from currents conf.py removed - PR #1880 is the right place
  for sagittas branch-localized title.

Supersedes / closes on merge:

- #1886 (broken converter output, would break /en/1.4/ if merged).

Generated by robots https://vyos.io

1 files changed, 406 insertions, 0 deletions

diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md
new file mode 100644
index 00000000..c5163a99
--- /dev/null
+++ b/docs/configuration/container/md-index.md
@@ -0,0 +1,406 @@
+---
+lastproofread: '2022-06-10'
+---
+
+# Container
+
+The VyOS container implementation is based on `Podman<https://podman.io/>` as
+a deamonless container engine.
+
+## Configuration
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> image
+
+    Sets the image name in the hub registry
+
+    .. code-block:: none
+
+      set container name mysql-server image mysql:8.0
+
+    If a registry is not specified, Docker.io will be used as the container
+    registry unless an alternative registry is specified using
+    **set container registry <name>** or the registry is included
+    in the image name
+
+    .. code-block:: none
+
+      set container name mysql-server image quay.io/mysql:8.0
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> entrypoint <entrypoint>
+
+   Override the default entrypoint from the image for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> command <command>
+
+    Override the default command from the image for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> arguments <arguments>
+
+    Set the command arguments for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> host-name <hostname>
+
+    Set the host name for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> allow-host-pid
+
+    The container and the host share the same process namespace.
+    This means that processes running on the host are visible inside the
+    container, and processes inside the container are visible on the host.
+
+    The command translates to "--pid host" when the container is created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> allow-host-networks
+
+    Allow host networking in a container. The network stack of the container is
+    not isolated from the host and will use the host IP.
+
+    The command translates to "--net host" when the container is created.
+
+    .. note:: **allow-host-networks** cannot be used with **network**
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> network <networkname>
+
+    Attaches user-defined network to a container.
+    Only one network must be specified and must already exist.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> network <networkname> address <address>
+
+    Optionally set a specific static IPv4 or IPv6 address for the container.
+    This address must be within the named network prefix.
+
+    .. note:: The first IP in the container network is reserved by the
+       engine and cannot be used
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> description <text>
+
+    Set a container description
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> environment <key> value <value>
+
+    Add custom environment variables.
+    Multiple environment variables are allowed.
+    The following commands translate to "-e key=value" when the container
+    is created.
+
+    .. code-block:: none
+
+        set container name mysql-server environment MYSQL_DATABASE value 'zabbix'
+        set container name mysql-server environment MYSQL_USER value 'zabbix'
+        set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd'
+        set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd'
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> port <portname> source <portnumber>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> port <portname> destination <portnumber>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp>
+
+    Publish a port for the container.
+
+    .. code-block:: none
+
+        set container name zabbix-web-nginx-mysql port http source 80
+        set container name zabbix-web-nginx-mysql port http destination 8080
+        set container name zabbix-web-nginx-mysql port http protocol tcp
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> volume <volumename> source <path>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> volume <volumename> destination <path>
+
+    Mount a volume into the container
+
+    .. code-block:: none
+
+        set container name coredns volume 'corefile' source /config/coredns/Corefile
+        set container name coredns volume 'corefile' destination /etc/Corefile
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw>
+
+    Volume is either mounted as rw (read-write - default) or ro (read-only)
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> uid <number>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> gid <number>
+
+    Set the User ID or Group ID of the container
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> restart [no | on-failure | always]
+
+   Set the restart behavior of the container.
+
+   - **no**: Do not restart containers on exit
+   - **on-failure**: Restart containers when they exit with a non-zero
+     exit code, retrying indefinitely (default)
+   - **always**: Restart containers when they exit, regardless of status,
+     retrying indefinitely
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> cpu-quota <num>
+
+   This specifies the number of CPU resources the container can use.
+
+   Default is 0 for unlimited.
+   For example, 1.25 limits the container to use up to 1.25 cores
+   worth of CPU time.
+   This can be a decimal number with up to three decimal places.
+
+   The command translates to "--cpus=<num>" when the container is created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> memory <MB>
+
+   Constrain the memory available to the container.
+
+   Default is 512 MB. Use 0 MB for unlimited memory.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> device <devicename> source <path>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> device <devicename> destination <path>
+
+   Add a host device to the container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> capability <text>
+
+   Set container capabilities or permissions.
+
+   - **net-admin**: Network operations (interface, firewall, routing tables)
+   - **net-bind-service**: Bind a socket to privileged ports
+     (port numbers less than 1024)
+   - **net-raw**: Permission to create raw network sockets
+   - **setpcap**: Capability sets (from bounded or inherited set)
+   - **sys-admin**: Administration operations (quotactl, mount, sethostname,
+     setdomainame)
+   - **sys-time**: Permission to set system clock
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> sysctl parameter <parameter> value <value>
+
+   Set container sysctl values.
+
+   The subset of possible parameters are:
+
+   - Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem,
+     kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
+   - Parameters beginning with fs.mqueue.*
+   - Parameters beginning with net.* (only if user-defined network is used)
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> label <label> value <value>
+
+   Add metadata label for this container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> disable
+
+   Disable a container.
+```
+
+### Container Networks
+
+```{eval-rst}
+.. cfgcmd:: set container network <name>
+
+    Creates a named container network
+```
+
+```{eval-rst}
+.. cfgcmd:: set container network <name> description
+
+    A brief description what this network is all about.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container network <name> prefix <ipv4|ipv6>
+
+    Define IPv4 and/or IPv6 prefix for a given network name.
+    Both IPv4 and IPv6 can be used in parallel.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container network <name> vrf <nme>
+
+    Bind container network to a given VRF instance.
+```
+
+### Container Registry
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name>
+
+    Adds registry to list of unqualified-search-registries. By default, for any
+    image that does not include the registry in the image name, VyOS will use
+    docker.io and quay.io as the container registry.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name> disable
+
+    Disable a given container registry
+```
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name> authentication username
+```
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name> authentication password
+
+    Some container registries require credentials to be used.
+
+    Credentials can be defined here and will only be used when adding a
+    container image to the system.
+
+```
+
+## Operation Commands
+
+```{eval-rst}
+.. opcmd:: add container image <containername>
+
+    Pull a new image for container
+```
+
+```{eval-rst}
+.. opcmd:: show container
+
+    Show the list of all active containers.
+```
+
+```{eval-rst}
+.. opcmd:: show container image
+
+    Show the local container images.
+```
+
+```{eval-rst}
+.. opcmd:: show container log <containername>
+
+    Show logs from a given container
+```
+
+```{eval-rst}
+.. opcmd:: show container network
+
+    Show a list available container networks
+```
+
+```{eval-rst}
+.. opcmd:: restart container <containername>
+
+    Restart a given container
+```
+
+```{eval-rst}
+.. opcmd:: update container image <containername>
+
+    Update container image
+```
+
+```{eval-rst}
+.. opcmd:: delete container image <image id|all> [force]
+
+    Delete a particular container image based on it's image ID.
+    You can also delete all container images at once.
+
+    You can not delete a container image if it has more then one tag
+    assigned, this is why there is a `force` option to pass down to
+    the container image to also remove those images.
+```
+
+## Example Configuration
+
+> For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers)
+> to the declarative VyOS CLI syntax.
+>
+> ```none
+> set container network zabbix prefix 172.20.0.0/16
+> set container network zabbix description 'Network for Zabbix component containers'
+>
+> set container name mysql-server image mysql:8.0
+> set container name mysql-server network zabbix
+>
+> set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix'
+> set container name mysql-server environment 'MYSQL_USER' value 'zabbix'
+> set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+> set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+>
+> set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest
+> set container name zabbix-java-gateway network zabbix
+>
+> set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest
+> set container name zabbix-server-mysql network zabbix
+>
+> set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
+> set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix'
+> set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix'
+> set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+> set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+> set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway'
+>
+> set container name zabbix-server-mysql port zabbix source 10051
+> set container name zabbix-server-mysql port zabbix destination 10051
+>
+> set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest
+> set container name zabbix-web-nginx-mysql network zabbix
+>
+> set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix'
+> set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql'
+> set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
+> set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix'
+> set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+> set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+>
+> set container name zabbix-web-nginx-mysql port http source 80
+> set container name zabbix-web-nginx-mysql port http destination 8080
+> ```