docker-stack 2.0.7__tar.gz → 2.1.1__tar.gz

{docker_stack-2.0.7 → docker_stack-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.0.7
+Version: 2.1.1
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -8,7 +8,7 @@ Author-email: sudip@bhattarai.me
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: PyYAML
 Provides-Extra: dev
@@ -64,7 +64,9 @@ What this gives you on a raw Docker daemon:
 
 ### GitHub Actions
 
-If you want to use `docker-stack` directly in a workflow, install the package explicitly:
+#### 1. Normal Docker daemon
+
+Use this when the runner already has Docker access through the default Docker context or `DOCKER_HOST`.
 
 ```yaml
 steps:
@@ -76,6 +78,85 @@ steps:
   - run: docker-stack deploy my-stack docker-compose.yml
 ```
 
+Use this option when CI can connect directly to the target Docker daemon.
+
+#### 2. Docker-Manager
+
+Use the bundled action when deploying through Docker-Manager:
+
+For a full compose deployment directly from CI, use the action to configure
+Docker-Manager authentication and then run the normal `docker-stack deploy`
+command:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+  - run: docker-stack deploy --namespace team-a --with-registry-auth my-stack docker-compose.yml
+```
+
+You can also deploy the full compose file through action inputs:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      compose-file: docker-compose.yml
+      namespace: team-a
+      with-registry-auth: "true"
+```
+
+To release new service images without submitting the compose file again:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      namespace: team-a
+      with-registry-auth: "true"
+      images: |
+        api=ghcr.io/acme/api:${{ github.sha }}
+        worker=ghcr.io/acme/worker:${{ github.sha }}
+```
+
+Use a full compose deployment when the workflow owns the complete stack
+definition. Use an image-only deployment when the stack is already managed and
+the workflow only needs to release new images. Both forms support namespaces;
+the namespace defaults to `default` when omitted.
+
+### Authenticated Docker-Manager shell
+
+Open an isolated Bash or Zsh session for a manager context:
+
+```bash
+docker-stack shell office
+```
+
+The prompt displays `(docker:office)`, keeps the selected manager context active,
+and refreshes authentication when needed. The session supports `docker` and
+`docker compose`; legacy `docker-compose` is not supported. If authentication
+expires, run `docker-stack login` again.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**
@@ -139,6 +220,20 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
     ```
     *(Content of `./templates/my_config.tpl` might be: `DB_HOST=${DATABASE_HOST}`)*
 
+    ### `environment`: Secret Content from Environment Variables
+    Secrets can read their content from an environment variable at deploy time.
+
+    ```yaml
+    secrets:
+      api_token:
+        environment: API_TOKEN
+    ```
+
+    If the variable is unset or empty, deployment fails before Docker objects are created.
+
+    ### Stored Source Metadata
+    Versioned stack configs include a top-level `x-files` list with base64-encoded source material for recovery and auditing. This includes the original compose file as `compose.yml`, a generated `.env` containing referenced non-secret environment values, and config files referenced by `configs.*.file` or `configs.*.x-template-file`. Secret source files and variables used by `secrets.*.environment` are not stored in `x-files`.
+
     ### `x-generate`: Dynamic Secret Generation (Secrets Only)
     This powerful feature allows you to automatically generate random secrets based on specified criteria, eliminating the need to manually create and manage them. This is particularly useful for passwords, API keys, and other sensitive data.
 
@@ -242,6 +337,11 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
               uppercase: false
         ```
 
+## Known Limitations
+
+Docker limits config content to 500 KB. Stack history includes encoded source
+files, so stacks with large compose or config files can exceed that limit.
+
 ## Development
 
 Install runtime and test dependencies with either:

{docker_stack-2.0.7 → docker_stack-2.1.1}/README.md

@@ -38,7 +38,9 @@ What this gives you on a raw Docker daemon:
 
 ### GitHub Actions
 
-If you want to use `docker-stack` directly in a workflow, install the package explicitly:
+#### 1. Normal Docker daemon
+
+Use this when the runner already has Docker access through the default Docker context or `DOCKER_HOST`.
 
 ```yaml
 steps:
@@ -50,6 +52,85 @@ steps:
   - run: docker-stack deploy my-stack docker-compose.yml
 ```
 
+Use this option when CI can connect directly to the target Docker daemon.
+
+#### 2. Docker-Manager
+
+Use the bundled action when deploying through Docker-Manager:
+
+For a full compose deployment directly from CI, use the action to configure
+Docker-Manager authentication and then run the normal `docker-stack deploy`
+command:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+  - run: docker-stack deploy --namespace team-a --with-registry-auth my-stack docker-compose.yml
+```
+
+You can also deploy the full compose file through action inputs:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      compose-file: docker-compose.yml
+      namespace: team-a
+      with-registry-auth: "true"
+```
+
+To release new service images without submitting the compose file again:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      namespace: team-a
+      with-registry-auth: "true"
+      images: |
+        api=ghcr.io/acme/api:${{ github.sha }}
+        worker=ghcr.io/acme/worker:${{ github.sha }}
+```
+
+Use a full compose deployment when the workflow owns the complete stack
+definition. Use an image-only deployment when the stack is already managed and
+the workflow only needs to release new images. Both forms support namespaces;
+the namespace defaults to `default` when omitted.
+
+### Authenticated Docker-Manager shell
+
+Open an isolated Bash or Zsh session for a manager context:
+
+```bash
+docker-stack shell office
+```
+
+The prompt displays `(docker:office)`, keeps the selected manager context active,
+and refreshes authentication when needed. The session supports `docker` and
+`docker compose`; legacy `docker-compose` is not supported. If authentication
+expires, run `docker-stack login` again.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**
@@ -113,6 +194,20 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
     ```
     *(Content of `./templates/my_config.tpl` might be: `DB_HOST=${DATABASE_HOST}`)*
 
+    ### `environment`: Secret Content from Environment Variables
+    Secrets can read their content from an environment variable at deploy time.
+
+    ```yaml
+    secrets:
+      api_token:
+        environment: API_TOKEN
+    ```
+
+    If the variable is unset or empty, deployment fails before Docker objects are created.
+
+    ### Stored Source Metadata
+    Versioned stack configs include a top-level `x-files` list with base64-encoded source material for recovery and auditing. This includes the original compose file as `compose.yml`, a generated `.env` containing referenced non-secret environment values, and config files referenced by `configs.*.file` or `configs.*.x-template-file`. Secret source files and variables used by `secrets.*.environment` are not stored in `x-files`.
+
     ### `x-generate`: Dynamic Secret Generation (Secrets Only)
     This powerful feature allows you to automatically generate random secrets based on specified criteria, eliminating the need to manually create and manage them. This is particularly useful for passwords, API keys, and other sensitive data.
 
@@ -216,6 +311,11 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
               uppercase: false
         ```
 
+## Known Limitations
+
+Docker limits config content to 500 KB. Stack history includes encoded source
+files, so stacks with large compose or config files can exceed that limit.
+
 ## Development
 
 Install runtime and test dependencies with either:

{docker_stack-2.0.7 → docker_stack-2.1.1}/docker_stack/__init__.py

@@ -8,6 +8,7 @@ def main(args=None):
 
     return cli_main(args)
 
+
 """
 Functions: