feat(Admin/AppAPI): add docker registries docs

admin_manual/exapps_management/ManagingDeployDaemons.rst

@@ -11,6 +11,9 @@ There are a few OCC CLI commands to manage Deploy Daemons:
 1. Register ``occ app_api:daemon:register``
 2. Unregister ``occ app_api:daemon:unregister``
 3. List registered daemons ``occ app_api:daemon:list``
+4. Add a Docker registry mapping ``occ app_api:daemon:registry:add``
+5. Remove a Docker registry mapping ``occ app_api:daemon:registry:remove``
+6. List Docker registry mappings ``occ app_api:daemon:registry:list``
 
 Register
 --------
@@ -92,6 +95,8 @@ Usage Examples
         app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda
 
 
+.. _deploy_config:
+
 DeployConfig
 ************
 
@@ -112,7 +117,14 @@ ExApp container.
             "frp_address": "localhost:8782",
             "docker_socket_port": "24000",
             "exapp_direct": false
-        }
+        },
+        "resourceLimits": {
+            "memory": 2147483648,
+            "nanoCPUs": 2000000000
+        },
+        "registries": [
+            {"from": "ghcr.io", "to": "registry.example.com"}
+        ]
     }
 
 DeployConfig options
@@ -126,6 +138,10 @@ DeployConfig options
         * ``frp_address`` *[optional]* - [host]:[port] of the HaRP FRP server, default host is same as HaRP host and port is 8782
         * ``docker_socket_port`` *[optional]* - 'remotePort' of the FRP client of the remote docker socket proxy. There is one included in the harp container so this can be skipped for default setups. [default: "24000"]
         * ``exapp_direct`` *[optional]* - Flag for the advanced setups only. Disables the FRP tunnel between ExApps and HaRP.
+    * ``resourceLimits`` *[optional]* - limits applied to each ExApp container deployed by this daemon. Empty (``[]``) when no limits are set, and absent for daemons registered over the CLI, both of which mean unlimited. Each limit is only present when it is set
+        * ``memory`` *[optional]* - memory limit **in bytes** (e.g. ``2147483648`` for 2 GiB). In the admin settings this is entered in MiB
+        * ``nanoCPUs`` *[optional]* - CPU limit **in nanoCPUs**, where ``1000000000`` equals one CPU core (e.g. ``2000000000`` for 2 cores). In the admin settings this is entered in cores
+    * ``registries`` *[optional]* - list of :ref:`Docker registry mappings <docker_registry_mappings>`, each entry being a ``{"from": ..., "to": ...}`` pair
 
 Unregister
 ----------
@@ -141,6 +157,173 @@ List registered Deploy Daemons (DaemonConfigs).
 
 Command: ``app_api:daemon:list``
 
+.. _docker_registry_mappings:
+
+Docker registry mappings
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 32.0.0
+
+Every ExApp declares in its ``info.xml`` the registry its image is pulled from, usually ``ghcr.io`` or ``docker.io``.
+A Deploy Daemon can override those registries so that images are pulled from somewhere else, without any change to the
+ExApp itself. This is useful when your servers have no access to the public registries, when you mirror the ExApp
+images into a private registry, or when you want to test locally built images.
+
+.. note::
+    Registry mappings only apply to daemons of the ``docker-install`` type. They have no effect on ``manual-install``
+    daemons, because those do not pull images.
+
+Finding the registry of an ExApp
+--------------------------------
+
+The registry to map is the one in the ``<registry>`` element of the ``<docker-install>`` section of the ExApp's
+``info.xml``, which is part of the ExApp source:
+
+.. code-block:: xml
+
+    <info>
+        ...
+        <external-app>
+            <docker-install>
+                <registry>ghcr.io</registry>
+                <image>example-org/exapp_name</image>
+                <image-tag>1.0.0</image-tag>
+            </docker-install>
+            ...
+        </external-app>
+    </info>
+
+Together these three elements form the image that is pulled, ``ghcr.io/example-org/exapp_name:1.0.0``. To redirect this
+ExApp, add a mapping with ``ghcr.io`` as the source registry.
+
+.. important::
+    Only the registry is replaced. The ``<image>`` and ``<image-tag>`` values are used unchanged, so the image must be
+    available in your custom registry under exactly the same repository path and tag, in this example
+    ``example-org/exapp_name:1.0.0``. Mirror the image with its original name, for instance:
+
+    .. code-block:: bash
+
+        docker pull ghcr.io/example-org/exapp_name:1.0.0
+        docker tag ghcr.io/example-org/exapp_name:1.0.0 registry.example.com/example-org/exapp_name:1.0.0
+        docker push registry.example.com/example-org/exapp_name:1.0.0
+
+How mappings are applied
+------------------------
+
+A mapping is a pair of registry domains: ``from`` is the registry declared by the ExApp, and ``to`` is the registry
+that should be used instead. During deployment, at the image pull step, AppAPI compares the ExApp registry with the
+``from`` value of each mapping. On the first match, the registry part of the image name is replaced with ``to``, while
+the image name and tag stay untouched:
+
+.. code-block:: text
+
+    mapping:  ghcr.io -> registry.example.com
+
+    declared: ghcr.io/example-org/exapp_name:1.0.0
+    pulled:   registry.example.com/example-org/exapp_name:1.0.0
+
+The special target ``local`` does not rewrite the image name. Instead it skips the image pull entirely, and the image is
+expected to already be present on the Docker host under its original name, either pulled manually beforehand or built
+locally:
+
+.. code-block:: text
+
+    mapping:  ghcr.io -> local
+
+    declared: ghcr.io/example-org/exapp_name:1.0.0
+    pulled:   nothing, the image already present on the host is used
+
+.. warning::
+    With a ``local`` target, AppAPI cannot pull a missing image. If the image is absent from the Docker host,
+    deployment of the ExApp fails at the container creation step.
+
+Mappings are stored per daemon in the ``registries`` key of its :ref:`DeployConfig <deploy_config>`, and are
+applied to every ExApp deployed through that daemon. Only one mapping per ``from`` registry is allowed, and existing
+ExApp containers are not affected: a mapping takes effect the next time an ExApp is deployed or updated.
+
+.. important::
+    AppAPI does not send registry credentials when pulling images. If your registry requires authentication, log the
+    Docker daemon into it beforehand with ``docker login``, so the pull can succeed with the stored credentials.
+
+Web interface
+-------------
+
+Open the AppAPI admin settings, click the three-dots menu of a Deploy Daemon and select **Docker registries**:
+
+.. image:: ./img/docker-registries-menu.png
+   :alt: AppAPI admin settings showing the Docker registries entry in the three-dots menu of a Deploy Daemon
+
+In the **Override Docker registries** dialog, the configured mappings are listed, and mappings with the ``local``
+target are marked with *Image pull will be skipped*. Click **Add registry override mapping**, fill in the **From** and
+**To** fields, and confirm with the **Add** button. To delete a mapping, use **Remove** in the three-dots menu of the
+respective list entry:
+
+.. image:: ./img/docker-registries-modal.png
+   :alt: AppAPI Override Docker registries dialog listing registry mappings with the form to add a new mapping
+
+Add a registry mapping
+----------------------
+
+Add a Docker registry mapping to a Deploy Daemon.
+
+Command: ``app_api:daemon:registry:add [--registry-from REGISTRY-FROM] [--registry-to REGISTRY-TO] [--] <name>``
+
+* ``name`` - name of the Deploy Daemon the mapping is added to (e.g. ``docker_install``)
+* ``--registry-from`` - ``[required]`` registry declared by the ExApp (e.g. ``ghcr.io``)
+* ``--registry-to`` - ``[required]`` registry to use instead, or ``local`` to skip the image pull
+
+The command fails if the daemon does not exist, if a mapping for the same ``from`` registry is already configured, or
+if both registries are the same.
+
+* Pull images that ExApps declare on ``ghcr.io`` from a private registry instead:
+
+    .. code-block:: bash
+
+        sudo -E -u www-data php occ app_api:daemon:registry:add docker_install --registry-from "ghcr.io" --registry-to "registry.example.com"
+
+* Use images that are already present on the Docker host instead of pulling them from ``ghcr.io``:
+
+    .. code-block:: bash
+
+        sudo -E -u www-data php occ app_api:daemon:registry:add docker_install --registry-from "ghcr.io" --registry-to "local"
+
+Remove a registry mapping
+-------------------------
+
+Remove a Docker registry mapping from a Deploy Daemon. Both registries of the mapping must be given, so that the exact
+pair is removed.
+
+Command: ``app_api:daemon:registry:remove [--registry-from REGISTRY-FROM] [--registry-to REGISTRY-TO] [--] <name>``
+
+* ``name`` - name of the Deploy Daemon the mapping is removed from (e.g. ``docker_install``)
+* ``--registry-from`` - ``[required]`` source registry of the mapping to remove
+* ``--registry-to`` - ``[required]`` target registry of the mapping to remove
+
+    .. code-block:: bash
+
+        sudo -E -u www-data php occ app_api:daemon:registry:remove docker_install --registry-from "ghcr.io" --registry-to "registry.example.com"
+
+List registry mappings
+----------------------
+
+List the Docker registry mappings configured for a Deploy Daemon.
+
+Command: ``app_api:daemon:registry:list <name>``
+
+* ``name`` - name of the Deploy Daemon to list the mappings of (e.g. ``docker_install``)
+
+    .. code-block:: bash
+
+        sudo -E -u www-data php occ app_api:daemon:registry:list docker_install
+
+The mappings are printed as ``from -> to`` pairs:
+
+.. code-block:: text
+
+    Configured registries for daemon "docker_install":
+     - ghcr.io -> registry.example.com
+     - docker.io -> local
+
 Nextcloud AIO
 ^^^^^^^^^^^^^