Add Remote Context and Update Examples

smashedr · smashedr · commit 0feea7807138 · 2025-09-06T19:17:42.000-07:00
diff --git a/docs/guides/features.md b/docs/guides/features.md
@@ -1,11 +1,11 @@
 # Features
 
 Deploy a Docker [stack](https://docs.docker.com/reference/cli/docker/stack/deploy/) or [compose](https://docs.docker.com/reference/cli/docker/compose/up/) file, to a remote host over SSH,
-using a [remote context](https://docs.docker.com/engine/manage-resources/contexts/). This deploys the stack from the current workspace without copying files.
+using a [Remote Context](#remote-context). This deploys the stack from the current workspace without copying files.
 
 - Deploy to Docker Swarm or Compose.
 - Deploy over SSH using [keyfile](../docs/inputs.md#pass-ssh-key) or [password](../docs/inputs.md#pass-ssh-key).
-- Deploy from the current working directory.
+- Deploy from the current working [directory](#remote-context).
 - Deploy from a private registry with [credentials](../docs/inputs.md#registry-user-registry-pass).
 - [Job Summary](#job-summary) with deployment output, including errors.
 - Supports multiple compose [files](../docs/inputs.md#file) and stack deployments.
@@ -19,59 +19,56 @@ You can [get started here](get-started.md) or view [workflow examples](examples.
 If you need more options, please [open a feature request](https://github.com/cssnr/stack-deploy-action/discussions/categories/feature-requests)
 :::
 
-## Job Summary
+## Remote Context
 
-Unless disabled, a Job Summary is generated to capture the command, output and errors.
+This action uses a [remote context](https://docs.docker.com/engine/manage-resources/contexts/)
+to deploy the stack on the remote host, from the current environment.
 
-💡 _Click on the heading to expand/collapse the item._
+```shell
+docker context create remote --docker "host=ssh://user@host:port"
+docker context use remote
+```
 
-::: details Successful Job Summary ✔️
+After this all the subsequent `docker` commands, such as `stack deploy` and `compose up` are executed on the remote context (host).
 
----
+This allows you to run any steps to prepare your stack for deployment, in the workflow steps directly, without needing to copy any files.
 
-🚀 Swarm Stack `test_stack-deploy` Successfully Deployed.
+::: details View workflow steps example
 
-```text
-docker stack deploy -c docker-compose.yaml --detach=false --resolve-image=changed test_stack-deploy
-```
+```yaml
+steps:
+  - name: 'Checkout'
+    uses: actions/checkout@v5
 
-<details><summary>Results</summary>
-
-```text
-Updating service test_stack-deploy_alpine (id: tdk8v42m0rvp9hz4rbfrtszb6)
-1/1:
-overall progress: 0 out of 1 tasks
-overall progress: 1 out of 1 tasks
-verify: Waiting 5 seconds to verify that tasks are stable...
-verify: Waiting 4 seconds to verify that tasks are stable...
-verify: Waiting 3 seconds to verify that tasks are stable...
-verify: Waiting 2 seconds to verify that tasks are stable...
-verify: Waiting 1 seconds to verify that tasks are stable...
-verify: Service tdk8v42m0rvp9hz4rbfrtszb6 converged
-```
+  # Add Steps to Prepare Your Stack File or Environment...
 
-</details>
+  - name: 'Stack Deploy'
+    uses: cssnr/stack-deploy-action@v1
+    with:
+      # inputs excluded
+```
 
 :::
 
-::: details Failure Job Summary ❌
+## Job Summary
+
+Unless disabled, a Job Summary is generated to capture the command, output and errors.
+
+💡 _Click on the heading to expand/collapse the item._
+
+::: details Successful Job Summary ✔️
 
 ---
 
-⛔ Swarm Stack `test_stack-deploy` Failed to Deploy!
+<!--@include: ./include/summary-success.md-->
 
-```text
-docker stack deploy -c docker-compose.yaml --detach=false --resolve-image=changed test_stack-deploy
-```
+:::
 
-<details open><summary>Errors</summary>
+::: details Failure Job Summary ❌
 
-```text
-Creating network test_stack-deploy_default
-failed to create network test_stack-deploy_default: Error response from daemon: network with name test_stack-deploy_default already exists
-```
+---
 
-</details>
+<!--@include: ./include/summary-failed.md-->
 
 :::
 
diff --git a/docs/guides/include/summary-failed.md b/docs/guides/include/summary-failed.md
@@ -0,0 +1,14 @@
+⛔ Swarm Stack `test_stack-deploy` Failed to Deploy!
+
+```text
+docker stack deploy -c docker-compose.yaml --detach=false --resolve-image=changed test_stack-deploy
+```
+
+<details open><summary>Errors</summary>
+
+```text
+Creating network test_stack-deploy_default
+failed to create network test_stack-deploy_default: Error response from daemon: network with name test_stack-deploy_default already exists
+```
+
+</details>
diff --git a/docs/guides/include/summary-success.md b/docs/guides/include/summary-success.md
@@ -0,0 +1,22 @@
+🚀 Swarm Stack `test_stack-deploy` Successfully Deployed.
+
+```text
+docker stack deploy -c docker-compose.yaml --detach=false --resolve-image=changed test_stack-deploy
+```
+
+<details><summary>Results</summary>
+
+```text
+Updating service test_stack-deploy_alpine (id: tdk8v42m0rvp9hz4rbfrtszb6)
+1/1:
+overall progress: 0 out of 1 tasks
+overall progress: 1 out of 1 tasks
+verify: Waiting 5 seconds to verify that tasks are stable...
+verify: Waiting 4 seconds to verify that tasks are stable...
+verify: Waiting 3 seconds to verify that tasks are stable...
+verify: Waiting 2 seconds to verify that tasks are stable...
+verify: Waiting 1 seconds to verify that tasks are stable...
+verify: Service tdk8v42m0rvp9hz4rbfrtszb6 converged
+```
+
+</details>
diff --git a/docs/guides/resources.md b/docs/guides/resources.md
@@ -13,5 +13,6 @@ A collection of resources and guides for getting started.
 &nbsp;
 
 ::: tip
-Have a related resource? Let us know by creating a [PR](https://github.com/cssnr/stack-deploy-docs/edit/master/docs/guides/examples.md) or an [Issue](https://github.com/cssnr/stack-deploy-docs/issues).
+Have a related resource? Let us know by creating a [PR](https://github.com/cssnr/stack-deploy-docs/edit/master/docs/guides/examples.md)
+or an [Issue](https://github.com/cssnr/stack-deploy-docs/issues) on [GitHub](https://github.com/cssnr/stack-deploy-docs).
 :::
diff --git a/docs/snippets/basic/step.yaml b/docs/snippets/basic/step.yaml
@@ -3,9 +3,9 @@
   with:
     name: "stack-name" # set to your stack name
     file: "docker-compose.yaml" # set to your compose file
+    mode: "swarm" # if not using swarm set to "compose"
     host: ${{ secrets.DOCKER_HOST }}
     user: ${{ secrets.DOCKER_USER }}
     port: 22 # 22 is default, you can remove or change this
     pass: ${{ secrets.DOCKER_PASS }} # not needed with ssh_key
     ssh_key: ${{ secrets.DOCKER_SSH_KEY }} # not needed with pass
-    mode: swarm # if not using swarm set to: compose
diff --git a/docs/snippets/basic/workflow.yaml b/docs/snippets/basic/workflow.yaml
@@ -19,9 +19,9 @@ jobs:
         with:
           name: "stack-name" # set to your stack name
           file: "docker-compose.yaml" # set to your compose file
+          mode: "swarm" # if not using swarm set to "compose"
           host: ${{ secrets.DOCKER_HOST }}
           user: ${{ secrets.DOCKER_USER }}
           port: 22 # 22 is default, you can remove or change this
           pass: ${{ secrets.DOCKER_PASS }} # not needed with ssh_key
           ssh_key: ${{ secrets.DOCKER_SSH_KEY }} # not needed with pass
-          mode: swarm # if not using swarm set to: compose
diff --git a/docs/snippets/examples/compose/basic.yaml b/docs/snippets/examples/compose/basic.yaml
@@ -3,8 +3,8 @@
   with:
     name: "stack-name"
     file: "docker-compose.yaml"
+    mode: "compose"
     host: ${{ secrets.DOCKER_HOST }}
     user: ${{ secrets.DOCKER_USER }}
     pass: ${{ secrets.DOCKER_PASS }} # not needed with ssh_key
     ssh_key: ${{ secrets.DOCKER_SSH_KEY }} # not needed with pass
-    mode: compose
diff --git a/docs/snippets/examples/compose/full.yaml b/docs/snippets/examples/compose/full.yaml
@@ -3,6 +3,7 @@
   with:
     name: "stack-name"
     file: "docker-compose.yaml"
+    mode: "compose"
     host: ${{ secrets.DOCKER_HOST }}
     user: ${{ secrets.DOCKER_USER }}
     port: 22 # 22 is default, you can remove or change this
@@ -12,6 +13,5 @@
     registry_host: "ghcr.io"
     registry_user: ${{ vars.GHCR_USER }}
     registry_pass: ${{ secrets.GHCR_PASS }}
-    mode: compose
-    args: --remove-orphans --force-recreate
+    args: "--remove-orphans --force-recreate"
     summary: true
diff --git a/docs/snippets/examples/compose/options.yaml b/docs/snippets/examples/compose/options.yaml
@@ -3,9 +3,9 @@
   with:
     name: "stack-name"
     file: "docker-compose.yaml"
+    mode: "compose"
     host: ${{ secrets.DOCKER_HOST }}
     user: ${{ secrets.DOCKER_USER }}
     pass: ${{ secrets.DOCKER_PASS }} # not needed with ssh_key
     ssh_key: ${{ secrets.DOCKER_SSH_KEY }} # not needed with pass
-    mode: compose
-    args: --remove-orphans --force-recreate
+    args: "--remove-orphans --force-recreate"
diff --git a/docs/snippets/examples/compose/registry.yaml b/docs/snippets/examples/compose/registry.yaml
@@ -3,11 +3,11 @@
   with:
     name: "stack-name"
     file: "docker-compose.yaml"
+    mode: "compose"
     host: ${{ secrets.DOCKER_HOST }}
     user: ${{ secrets.DOCKER_USER }}
     pass: ${{ secrets.DOCKER_PASS }} # not needed with ssh_key
     ssh_key: ${{ secrets.DOCKER_SSH_KEY }} # not needed with pass
     registry_host: "ghcr.io"
     registry_user: ${{ vars.GHCR_USER }}
     registry_pass: ${{ secrets.GHCR_PASS }}
-    mode: compose
