docker-stack 2.1.0__tar.gz → 2.1.2__tar.gz

{docker_stack-2.1.0 → docker_stack-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.1.0
+Version: 2.1.2
 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
@@ -47,6 +47,8 @@ Typical daemon-only workflow:
 ```bash
 docker-stack deploy my-stack docker-compose.yml
 docker-stack ls
+docker-stack ls -n team-a
+docker-stack ls -A
 docker-stack versions my-stack
 docker-stack cat my-stack
 docker-stack checkout my-stack v2
@@ -78,12 +80,49 @@ steps:
   - run: docker-stack deploy my-stack docker-compose.yml
 ```
 
-This uses the normal Docker CLI path and runs `docker config` / `docker stack deploy` against the configured daemon.
+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
@@ -94,10 +133,39 @@ steps:
   - uses: mesudip/docker-stack@v2
     with:
       manager: https://manager.example.com:2378
-  - run: docker-stack deploy --with-registry-auth my-stack docker-compose.yml
+      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 }}
 ```
 
-The action uses `actions/setup-python@v6`, installs `docker-stack`, defaults to GitHub OIDC auth and the `dm-proxy` context, exports `DOCKER_CONFIG`, `DOCKER_CONTEXT`, and `DOCKER_MANAGER_URL` for later steps, and removes its generated Docker config directory in the post-action cleanup phase.
+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
+```
+
+If `office` does not exist yet, the CLI asks for its Docker-Manager URL, creates
+the context, authenticates, and opens the shell. You can also provide everything
+non-interactively with `docker-stack shell --context office <manager-url>`.
+
+Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
+Listings print the selected namespace; `docker-stack ls -A` (or
+`--all-namespaces`) lists every visible namespace.
+
+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
 
@@ -176,9 +244,6 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
     ### 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`.
 
-    ### Known Issues
-    Stored `x-files` metadata is written into Docker configs during local deploys. Docker config content is limited to 500 KB, and base64-encoded source files add roughly 33% overhead, so stacks with large compose/config source files can exceed the Docker config payload limit even when the rendered compose is valid.
-
     ### `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.
 
@@ -282,6 +347,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.1.0 → docker_stack-2.1.2}/README.md

@@ -21,6 +21,8 @@ Typical daemon-only workflow:
 ```bash
 docker-stack deploy my-stack docker-compose.yml
 docker-stack ls
+docker-stack ls -n team-a
+docker-stack ls -A
 docker-stack versions my-stack
 docker-stack cat my-stack
 docker-stack checkout my-stack v2
@@ -52,12 +54,49 @@ steps:
   - run: docker-stack deploy my-stack docker-compose.yml
 ```
 
-This uses the normal Docker CLI path and runs `docker config` / `docker stack deploy` against the configured daemon.
+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
@@ -68,10 +107,39 @@ steps:
   - uses: mesudip/docker-stack@v2
     with:
       manager: https://manager.example.com:2378
-  - run: docker-stack deploy --with-registry-auth my-stack docker-compose.yml
+      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 }}
 ```
 
-The action uses `actions/setup-python@v6`, installs `docker-stack`, defaults to GitHub OIDC auth and the `dm-proxy` context, exports `DOCKER_CONFIG`, `DOCKER_CONTEXT`, and `DOCKER_MANAGER_URL` for later steps, and removes its generated Docker config directory in the post-action cleanup phase.
+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
+```
+
+If `office` does not exist yet, the CLI asks for its Docker-Manager URL, creates
+the context, authenticates, and opens the shell. You can also provide everything
+non-interactively with `docker-stack shell --context office <manager-url>`.
+
+Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
+Listings print the selected namespace; `docker-stack ls -A` (or
+`--all-namespaces`) lists every visible namespace.
+
+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
 
@@ -150,9 +218,6 @@ Vanilla Docker Stack deployments can sometimes lack the flexibility needed for d
     ### 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`.
 
-    ### Known Issues
-    Stored `x-files` metadata is written into Docker configs during local deploys. Docker config content is limited to 500 KB, and base64-encoded source files add roughly 33% overhead, so stacks with large compose/config source files can exceed the Docker config payload limit even when the rendered compose is valid.
-
     ### `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.
 
@@ -256,6 +321,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: