From a12832ec7bd083c853aa05624fb3c988713d8d31 Mon Sep 17 00:00:00 2001
From: Cesar <275373127+sanzakicesarr@users.noreply.github.com>
Date: Tue, 16 Jun 2026 09:28:49 +0200
Subject: [PATCH 1/2] docs(admin): add Docker/AIO systemd example for the AI
 worker

The "Systemd service" section only documented running the AI worker on
bare metal. When Nextcloud runs inside a Docker container (for example
Nextcloud AIO) the service has to wait for Docker and invoke occ inside
the container via docker exec.

Document extending the [Unit] section with a dependency on docker.service
and a taskprocessing.sh that uses "docker exec -i" without -t, since
systemd provides no pseudo-TTY. The command mirrors the existing AIO
docker exec example in the screen/tmux section and uses the current
taskprocessing:worker command.

Signed-off-by: Cesar <275373127+sanzakicesarr@users.noreply.github.com>
---
 admin_manual/ai/overview.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/admin_manual/ai/overview.rst b/admin_manual/ai/overview.rst
index cb59310b04a..7b8d02798f4 100644
--- a/admin_manual/ai/overview.rst
+++ b/admin_manual/ai/overview.rst
@@ -416,6 +416,28 @@ The complete logs of the workers can be checked with (replace 1 with the worker
 
    journalctl -xeu nextcloud-ai-worker@1.service -f
 
+If your Nextcloud runs inside a Docker container (for example with Nextcloud AIO), the worker has to run
+*inside* the container. Make the service unit shown above wait for Docker by extending its ``[Unit]``
+section:
+
+.. code-block:: ini
+
+   [Unit]
+   Description=Nextcloud AI worker %i
+   After=network.target docker.service
+   Requires=docker.service
+
+and call ``occ`` through ``docker exec`` in ``taskprocessing.sh`` instead of running it locally:
+
+.. code-block:: bash
+
+   #!/bin/sh
+   echo "Starting Nextcloud AI Worker $1"
+   docker exec -i nextcloud-aio-nextcloud sudo -E -u www-data php occ taskprocessing:worker -v -t 60
+
+Use ``docker exec -i`` without ``-t``: systemd does not allocate a pseudo-TTY, so adding ``-t`` makes the
+command fail with ``the input device is not a TTY``.
+
 
 Frequently Asked Questions
 --------------------------

From cdd09977060c903395bacfb26921f3628d52c82c Mon Sep 17 00:00:00 2001
From: Cesar <275373127+sanzakicesarr@users.noreply.github.com>
Date: Tue, 16 Jun 2026 22:46:35 +0200
Subject: [PATCH 2/2] docs(admin): wait for the AIO container to be healthy
 before exec

The Docker/AIO worker variant only ordered the unit on docker.service,
which gates on the Docker daemon, not on the nextcloud-aio-nextcloud
container. After a host reboot or a container update, docker exec could
fire before the container was back, exit non-zero, and with
Restart=always trip systemd's start-rate limit, leaving the worker down
until a manual reset.

Make taskprocessing.sh wait until the container reports healthy (the AIO
image ships a healthcheck for php-fpm and the database) before running
occ, bounded to five minutes so a genuinely missing container still
surfaces as a failure instead of hanging forever.

Signed-off-by: Cesar <275373127+sanzakicesarr@users.noreply.github.com>
---
 admin_manual/ai/overview.rst | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/admin_manual/ai/overview.rst b/admin_manual/ai/overview.rst
index 7b8d02798f4..944b6803b0c 100644
--- a/admin_manual/ai/overview.rst
+++ b/admin_manual/ai/overview.rst
@@ -427,12 +427,23 @@ section:
    After=network.target docker.service
    Requires=docker.service
 
-and call ``occ`` through ``docker exec`` in ``taskprocessing.sh`` instead of running it locally:
+and call ``occ`` through ``docker exec`` in ``taskprocessing.sh`` instead of running it locally. The
+``[Unit]`` ordering above only waits for the Docker daemon, not for the ``nextcloud-aio-nextcloud``
+container, so the script waits until that container reports healthy before running ``occ`` (the AIO image
+ships a healthcheck for php-fpm and the database). Without this wait the worker would exit immediately
+after a host reboot and, with ``Restart=always``, hit systemd's start-rate limit and stay down until a
+manual reset:
 
 .. code-block:: bash
 
    #!/bin/sh
    echo "Starting Nextcloud AI Worker $1"
+   i=0
+   until [ "$(docker inspect -f '{{.State.Health.Status}}' nextcloud-aio-nextcloud 2>/dev/null)" = healthy ]; do
+       i=$((i + 1))
+       [ "$i" -ge 60 ] && echo "nextcloud-aio-nextcloud not healthy after 5 min" && exit 1
+       sleep 5
+   done
    docker exec -i nextcloud-aio-nextcloud sudo -E -u www-data php occ taskprocessing:worker -v -t 60
 
 Use ``docker exec -i`` without ``-t``: systemd does not allocate a pseudo-TTY, so adding ``-t`` makes the