From 95d6c1151c8145a7c3f581db07f5ae22f57cb78c Mon Sep 17 00:00:00 2001
From: Frederik Ring <frederik.ring@gmail.com>
Date: Mon, 9 Jun 2025 13:55:41 +0200
Subject: [PATCH] Update documentation

---
 docs/how-tos/use-with-docker-swarm.md | 3 ++-
 test/README.md                        | 8 ++++++++
 test/test.sh                          | 7 +++++--
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/how-tos/use-with-docker-swarm.md b/docs/how-tos/use-with-docker-swarm.md
index 2917855..004f562 100644
--- a/docs/how-tos/use-with-docker-swarm.md
+++ b/docs/how-tos/use-with-docker-swarm.md
@@ -8,7 +8,8 @@ nav_order: 13
 # Use with Docker Swarm
 
 {: .note }
-The mechanisms described in this page __do only apply when Docker is running in [Swarm mode][swarm]__.
+The mechanisms described in this page __do only apply when Docker is running in [Swarm mode][swarm]__ and __when placing the `docker-volume-backup` container on a manager node__.
+Containers that are placed on worker nodes function as if the Docker engine is not running in Swarm mode, i.e. there is no access to services and there is no way to interact with resources that are running on different host nodes.
 
 [swarm]: https://docs.docker.com/engine/swarm/
 
diff --git a/test/README.md b/test/README.md
index f5b963c..ce96a32 100644
--- a/test/README.md
+++ b/test/README.md
@@ -67,3 +67,11 @@ A test case can signal it wants to run in swarm mode by placing an empty `.swarm
 In case the swarm setup should be compose of multiple nodes, a `.multinode` file can be used.
 
 A multinode setup will contain one manager (`manager`) and two worker nodes (`worker1` and `worker2`).
+
+If a test is expected to run in the context of a node other than the `manager`, the hostname can be put in the `.multinode` file.
+
+> [!IMPORTANT]
+> When running against a multi-node setup and targeting a non-manager node, the test script will automatically deploy a stack named `test_stack` based on the compose file in the test directory.
+> This is required because the non-manager node cannot deploy the stack itself from within the test script.
+> This also means, you cannot mount local directories created in your test script, as the containers are already created when the script runs.
+> You can work around this limitation by creating named volumes and then `docker cp`ing the contents your test needs to inspect.
diff --git a/test/test.sh b/test/test.sh
index dc42cd0..dc2c8de 100755
--- a/test/test.sh
+++ b/test/test.sh
@@ -46,8 +46,9 @@ for dir in $(find $find_args | sort); do
 
   docker compose --profile $compose_profile up -d --wait
   test_context=manager
-  if [ -f "${dir}/.multinode" ]; then
+  if [ -f "${dir}/.multinode" ] && [ -s "${dir}/.multinode" ]; then
     test_context=$(cat $dir/.multinode)
+    echo "Running tests on $test_context instead of manager"
   fi
   docker compose exec $test_context /bin/sh -c "docker load -i /cache/image.tar.gz"
 
@@ -60,7 +61,9 @@ for dir in $(find $find_args | sort); do
     docker compose exec worker1 docker swarm join --token $token $manager_ip:2377
     docker compose exec worker2 docker swarm join --token $token $manager_ip:2377
 
-    docker compose exec -w "/code/$dir" manager docker stack deploy --compose-file="docker-compose.yml" test_stack
+    if [ "$test_context" != "manager" ]; then
+      docker compose exec -w "/code/$dir" manager docker stack deploy --compose-file="docker-compose.yml" test_stack
+    fi
   fi
 
   docker compose exec -e TEST_VERSION=$IMAGE_TAG $test_context /bin/sh -c "/code/$test"