docker-stack 1.0.0__tar.gz → 2.0.1__tar.gz

{docker_stack-1.0.0 → docker_stack-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 1.0.0
+Version: 2.0.1
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -11,21 +11,96 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 Requires-Dist: PyYAML
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
 # Docker Stack CLI Utility
 
-A powerful command-line utility designed to enhance Docker Swarm stack deployments by providing advanced features for managing Docker configs and secrets. This tool aims to simplify complex deployment scenarios and offer capabilities beyond vanilla Docker Stack.
+A command-line tool for advanced Docker Swarm stack deployments on plain Docker daemons. `docker-stack` extends vanilla `docker stack deploy` with generated secrets, templated configs, versioned stack state, safer rollbacks, and better day-to-day stack workflows.
 
-## Features
+## Installation
+
+Install or upgrade `docker-stack` with:
+
+```bash
+pip install docker-stack --upgrade --break-system-packages
+```
+
+## Quick Start
+
+### Plain Docker Daemon
+
+If you already have a Docker Swarm daemon or Docker context, you can use the advanced stack features directly against it.
+
+Typical daemon-only workflow:
+
+```bash
+docker-stack deploy my-stack docker-compose.yml
+docker-stack ls
+docker-stack versions my-stack
+docker-stack cat my-stack
+docker-stack checkout my-stack v2
+docker-stack node ls
+```
+
+What this gives you on a raw Docker daemon:
+
+-   richer secret and config handling in Compose
+-   generated secrets without external scripts
+-   template expansion from env vars and files
+-   versioned stack config history
+-   stack version inspection and checkout
+-   raw daemon compatibility without extra infrastructure
+
+### GitHub Actions
+
+If you want to use `docker-stack` directly in a workflow, install the package explicitly:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v6
+    with:
+      python-version: '3.x'
+  - run: python3 -m pip install --upgrade docker-stack
+  - run: docker-stack deploy my-stack docker-compose.yml
+```
+
+## Core Capabilities
+
+-   **Advanced Deployments on Plain Docker Daemons:**
+    `docker-stack` works directly against a raw Docker daemon and adds capabilities that standard `docker stack deploy` does not provide out of the box:
+    - generated secrets
+    - inline configs and secrets
+    - template rendering from environment variables and files
+    - versioned config and secret history
+    - version lookup, checkout, and rollback-oriented workflows
+    - more ergonomic stack and node inspection output
+
+-   **Docker Stack Versioning and Config Backup for Rollback:**
+    The utility automatically versions your Docker configs and secrets, allowing for easy tracking of changes and seamless rollbacks to previous states. This provides a safety net for your deployments, ensuring you can always revert to a stable configuration.
+
+## Why Use It?
+
+Vanilla Docker Stack deployments can sometimes lack the flexibility needed for dynamic environments or robust secret management. This utility bridges those gaps by:
+
+-   **Automating Secret Management:** No more manual secret generation or complex external scripts.
+-   **Simplifying Configuration:** Define configs and secrets directly in your compose files or use templates.
+-   **Enhancing Security:** Generate strong, random secrets on the fly.
+-   **Enabling Rollbacks:** Versioning ensures you can always revert to a known good state.
+-   **Improving Raw Daemon Workflows:** Works directly with a plain Docker Swarm daemon.
+
+## Advanced Compose Features
 
 -   **Docker Config and Secret Management with Extended Options:**
     This utility significantly extends Docker's native config and secret management by introducing `x-` prefixed directives in your `docker-compose.yml` files. These directives allow for dynamic content generation, templating, and file inclusion, making your deployments more flexible and secure.
@@ -67,6 +142,33 @@ A powerful command-line utility designed to enhance Docker Swarm stack deploymen
     ### `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.
 
+    Supported `x-generate` forms:
+
+    -   `true`
+        Generate a secret with default options.
+    -   integer
+        Generate a secret with the requested length.
+    -   object
+        Generate a secret with explicit generation flags.
+
+    Supported object flags:
+
+    -   `length`
+        Exact secret length.
+    -   `numbers`
+        Include digits `0-9`.
+    -   `special`
+        Include special characters.
+    -   `uppercase`
+        Include uppercase letters `A-Z`.
+
+    Behavior notes:
+
+    -   Generated values are created at deploy time.
+    -   Generated secrets are versioned like other managed secrets.
+    -   Newly generated values can be shown after deploy when `--show-generated` is enabled.
+    -   `x-generate` is for secrets only; configs should use `x-content`, `x-template`, or `x-template-file`.
+
     -   **Simple Generation (12-20 characters, default options):**
         ```yaml
         secrets:
@@ -104,15 +206,52 @@ A powerful command-line utility designed to enhance Docker Swarm stack deploymen
               uppercase: false
         ```
 
--   **Docker Stack Versioning and Config Backup for Rollback:**
-    The utility automatically versions your Docker configs and secrets, allowing for easy tracking of changes and seamless rollbacks to previous states. This provides a safety net for your deployments, ensuring you can always revert to a stable configuration.
+    -   **Database Password Style Secret:**
+        Generates a strong password with uppercase letters, lowercase letters, numbers, and special characters.
+        ```yaml
+        secrets:
+          db_password:
+            x-generate:
+              length: 32
+              numbers: true
+              special: false
+              uppercase: true
+        ```
+
+    -   **Application Token Without Special Characters:**
+        Useful when the target application rejects punctuation in credentials or tokens.
+        ```yaml
+        secrets:
+          app_token:
+            x-generate:
+              length: 40
+              numbers: true
+              special: false
+              uppercase: true
+        ```
+
+    -   **Lowercase Alphanumeric Secret:**
+        Useful for systems that want URL-safe or copy-friendly generated values.
+        ```yaml
+        secrets:
+          compact_secret:
+            x-generate:
+              length: 24
+              numbers: true
+              special: false
+              uppercase: false
+        ```
 
-## Why use Docker Stack CLI Utility?
+## Development
 
-Vanilla Docker Stack deployments can sometimes lack the flexibility needed for dynamic environments or robust secret management. This utility bridges those gaps by:
--   **Automating Secret Management:** No more manual secret generation or complex external scripts.
--   **Simplifying Configuration:** Define configs and secrets directly in your compose files or use templates.
--   **Enhancing Security:** Generate strong, random secrets on the fly.
--   **Enabling Rollbacks:** Versioning ensures you can always revert to a known good state.
+Install runtime and test dependencies with either:
+
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
+or:
 
-Get started today and streamline your Docker Swarm deployments!
+```bash
+python3 -m pip install -e '.[dev]'
+```

docker_stack-2.0.1/README.md

@@ -0,0 +1,231 @@
+# Docker Stack CLI Utility
+
+A command-line tool for advanced Docker Swarm stack deployments on plain Docker daemons. `docker-stack` extends vanilla `docker stack deploy` with generated secrets, templated configs, versioned stack state, safer rollbacks, and better day-to-day stack workflows.
+
+## Installation
+
+Install or upgrade `docker-stack` with:
+
+```bash
+pip install docker-stack --upgrade --break-system-packages
+```
+
+## Quick Start
+
+### Plain Docker Daemon
+
+If you already have a Docker Swarm daemon or Docker context, you can use the advanced stack features directly against it.
+
+Typical daemon-only workflow:
+
+```bash
+docker-stack deploy my-stack docker-compose.yml
+docker-stack ls
+docker-stack versions my-stack
+docker-stack cat my-stack
+docker-stack checkout my-stack v2
+docker-stack node ls
+```
+
+What this gives you on a raw Docker daemon:
+
+-   richer secret and config handling in Compose
+-   generated secrets without external scripts
+-   template expansion from env vars and files
+-   versioned stack config history
+-   stack version inspection and checkout
+-   raw daemon compatibility without extra infrastructure
+
+### GitHub Actions
+
+If you want to use `docker-stack` directly in a workflow, install the package explicitly:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v6
+    with:
+      python-version: '3.x'
+  - run: python3 -m pip install --upgrade docker-stack
+  - run: docker-stack deploy my-stack docker-compose.yml
+```
+
+## Core Capabilities
+
+-   **Advanced Deployments on Plain Docker Daemons:**
+    `docker-stack` works directly against a raw Docker daemon and adds capabilities that standard `docker stack deploy` does not provide out of the box:
+    - generated secrets
+    - inline configs and secrets
+    - template rendering from environment variables and files
+    - versioned config and secret history
+    - version lookup, checkout, and rollback-oriented workflows
+    - more ergonomic stack and node inspection output
+
+-   **Docker Stack Versioning and Config Backup for Rollback:**
+    The utility automatically versions your Docker configs and secrets, allowing for easy tracking of changes and seamless rollbacks to previous states. This provides a safety net for your deployments, ensuring you can always revert to a stable configuration.
+
+## Why Use It?
+
+Vanilla Docker Stack deployments can sometimes lack the flexibility needed for dynamic environments or robust secret management. This utility bridges those gaps by:
+
+-   **Automating Secret Management:** No more manual secret generation or complex external scripts.
+-   **Simplifying Configuration:** Define configs and secrets directly in your compose files or use templates.
+-   **Enhancing Security:** Generate strong, random secrets on the fly.
+-   **Enabling Rollbacks:** Versioning ensures you can always revert to a known good state.
+-   **Improving Raw Daemon Workflows:** Works directly with a plain Docker Swarm daemon.
+
+## Advanced Compose Features
+
+-   **Docker Config and Secret Management with Extended Options:**
+    This utility significantly extends Docker's native config and secret management by introducing `x-` prefixed directives in your `docker-compose.yml` files. These directives allow for dynamic content generation, templating, and file inclusion, making your deployments more flexible and secure.
+
+    ### `x-content`: Inline Content for Configs and Secrets
+    Allows you to define the content of a Docker config or secret directly within your `docker-compose.yml`.
+
+    ```yaml
+    secrets:
+      my_inline_secret:
+        x-content: "This is my secret content defined inline."
+
+    configs:
+      my_inline_config:
+        x-content: |
+          key=value
+          another_key=another_value
+    ```
+
+    ### `x-template`: Environment Variable Templating
+    Enables the use of environment variables within your config or secret content, which are substituted at deployment time.
+
+    ```yaml
+    secrets:
+      my_templated_secret:
+        x-template: "I can create composite secret with template. ${API_KEY_NAME}:${MY_API_KEY}"
+    ```
+
+    ### `x-template-file`: External Template Files
+    Reference an external file whose content will be treated as a template and processed with environment variables.
+
+    ```yaml
+    configs:
+      my_config_from_template_file:
+        x-template-file: "./templates/my_config.tpl"
+    ```
+    *(Content of `./templates/my_config.tpl` might be: `DB_HOST=${DATABASE_HOST}`)*
+
+    ### `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.
+
+    Supported `x-generate` forms:
+
+    -   `true`
+        Generate a secret with default options.
+    -   integer
+        Generate a secret with the requested length.
+    -   object
+        Generate a secret with explicit generation flags.
+
+    Supported object flags:
+
+    -   `length`
+        Exact secret length.
+    -   `numbers`
+        Include digits `0-9`.
+    -   `special`
+        Include special characters.
+    -   `uppercase`
+        Include uppercase letters `A-Z`.
+
+    Behavior notes:
+
+    -   Generated values are created at deploy time.
+    -   Generated secrets are versioned like other managed secrets.
+    -   Newly generated values can be shown after deploy when `--show-generated` is enabled.
+    -   `x-generate` is for secrets only; configs should use `x-content`, `x-template`, or `x-template-file`.
+
+    -   **Simple Generation (12-20 characters, default options):**
+        ```yaml
+        secrets:
+          my_simple_generated_secret:
+            x-generate: true
+        ```
+
+    -   **Specify Length:**
+        ```yaml
+        secrets:
+          my_fixed_length_secret:
+            x-generate: 30 # Generates a 30-character secret
+        ```
+
+    -   **Custom Generation Options:**
+        You can provide a dictionary to fine-tune the generation process:
+        -   `length`: (integer, default: 12-20 random) Exact length of the secret.
+        -   `numbers`: (boolean, default: `true`) Include numbers (0-9).
+        -   `special`: (boolean, default: `true`) Include special characters (!@#$%^&*...).
+        -   `uppercase`: (boolean, default: `true`) Include uppercase letters (A-Z).
+
+        ```yaml
+        secrets:
+          my_complex_generated_secret:
+            x-generate:
+              length: 25
+              numbers: false
+              special: true
+              uppercase: true
+          my_alphanumeric_secret:
+            x-generate:
+              length: 15
+              numbers: true
+              special: false
+              uppercase: false
+        ```
+
+    -   **Database Password Style Secret:**
+        Generates a strong password with uppercase letters, lowercase letters, numbers, and special characters.
+        ```yaml
+        secrets:
+          db_password:
+            x-generate:
+              length: 32
+              numbers: true
+              special: false
+              uppercase: true
+        ```
+
+    -   **Application Token Without Special Characters:**
+        Useful when the target application rejects punctuation in credentials or tokens.
+        ```yaml
+        secrets:
+          app_token:
+            x-generate:
+              length: 40
+              numbers: true
+              special: false
+              uppercase: true
+        ```
+
+    -   **Lowercase Alphanumeric Secret:**
+        Useful for systems that want URL-safe or copy-friendly generated values.
+        ```yaml
+        secrets:
+          compact_secret:
+            x-generate:
+              length: 24
+              numbers: true
+              special: false
+              uppercase: false
+        ```
+
+## Development
+
+Install runtime and test dependencies with either:
+
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
+or:
+
+```bash
+python3 -m pip install -e '.[dev]'
+```

{docker_stack-1.0.0 → docker_stack-2.0.1}/docker_stack/__init__.py

@@ -1,7 +1,12 @@
 from .envsubst import envsubst, envsubst_load_file
 from .compose import read_compose_file
 from .docker_objects import DockerConfig, DockerSecret
-from .cli import main
+
+
+def main(args=None):
+    from .cli import main as cli_main
+
+    return cli_main(args)
 
 """
 Functions: