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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.0.6
+Version: 2.1.0
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -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,27 @@ 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.
+
+#### 2. Docker-Manager
+
+Use the bundled action when deploying through Docker-Manager:
+
+```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 --with-registry-auth my-stack docker-compose.yml
+```
+
+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.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**
@@ -139,6 +162,23 @@ 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`.
+
+    ### 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.
 

{docker_stack-2.0.6 → docker_stack-2.1.0}/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,27 @@ 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.
+
+#### 2. Docker-Manager
+
+Use the bundled action when deploying through Docker-Manager:
+
+```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 --with-registry-auth my-stack docker-compose.yml
+```
+
+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.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**
@@ -113,6 +136,23 @@ 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`.
+
+    ### 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.
 

{docker_stack-2.0.6 → docker_stack-2.1.0}/docker_stack/__init__.py

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

{docker_stack-2.0.6 → docker_stack-2.1.0}/docker_stack/cli.py

@@ -32,6 +32,14 @@ from docker_stack.manager_api import (
 from docker_stack.registry import DockerRegistry
 from .envsubst import LineCheckResult, SubstitutionError, envsubst, envsubst_load_file
 
+DOCKER_SHELL_ENDPOINT_ENV_VARS = (
+    "DOCKER_HOST",
+    "DOCKER_TLS_VERIFY",
+    "DOCKER_CERT_PATH",
+    "DOCKER_API_VERSION",
+    "DOCKER_MACHINE_NAME",
+)
+
 
 @dataclass
 class EnvFileEntry:
@@ -43,6 +51,12 @@ class EnvFileEntry:
     value_inner_offset: int
 
 
+@dataclass
+class RenderedCompose:
+    clean: str
+    enriched: str
+
+
 class EnvFileResolutionError(Exception):
     def __init__(self, env_file: str, reason: str, results: List[LineCheckResult], template_lines: List[str]):
         self.env_file = env_file
@@ -133,7 +147,9 @@ def _map_substitution_error(entry: EnvFileEntry, err: SubstitutionError) -> List
     return mapped_results
 
 
-def _resolve_env_entries(entries: List[EnvFileEntry], env_file: str, base_env: Optional[Dict[str, str]] = None, max_cycles: int = 5) -> Dict[str, str]:
+def _resolve_env_entries(
+    entries: List[EnvFileEntry], env_file: str, base_env: Optional[Dict[str, str]] = None, max_cycles: int = 5
+) -> Dict[str, str]:
     base_env = dict(base_env or os.environ)
     current_values = {entry.key: entry.value for entry in entries}
     local_keys = set(current_values.keys())
@@ -183,9 +199,7 @@ def _resolve_env_entries(entries: List[EnvFileEntry], env_file: str, base_env: O
                 break
 
     if cyclic_results:
-        deduped = {
-            (result.line_no, result.variable_name, result.start_index): result for result in cyclic_results
-        }
+        deduped = {(result.line_no, result.variable_name, result.start_index): result for result in cyclic_results}
         ordered_results = sorted(deduped.values(), key=lambda x: (x.line_no, x.start_index or 0))
         raise EnvFileResolutionError(
             env_file,
@@ -255,30 +269,127 @@ class DockerStack:
         with open(compose_file) as f:
             return self.decode_yaml(f.read())
 
-    def rendered_compose_file(self, compose_file, stack=None, include_build=True) -> str:
-        with open(compose_file) as f:
-            template_content = f.read()
+    @staticmethod
+    def _b64_content(content: bytes) -> str:
+        return base64.b64encode(content).decode("utf-8")
+
+    @staticmethod
+    def _strip_source_metadata(compose_content: str) -> str:
+        compose_data = yaml.safe_load(compose_content) or {}
+        if isinstance(compose_data, dict):
+            compose_data.pop("x-files", None)
+        return yaml.dump(compose_data, sort_keys=False)
+
+    @staticmethod
+    def _iter_env_refs(value: str):
+        for match in ENV_VAR_PATTERN.finditer(value):
+            name = match.group(1) if match.group(1) is not None else match.group(3)
+            default = match.group(2) if match.group(1) is not None else None
+            yield name, default
+
+    @staticmethod
+    def _secret_environment_vars(compose_data: dict) -> set:
+        secret_env_vars = set()
+        secrets = compose_data.get("secrets", {})
+        if not isinstance(secrets, dict):
+            return secret_env_vars
+        for details in secrets.values():
+            if isinstance(details, dict) and "environment" in details:
+                env_name = str(details["environment"]).strip()
+                if env_name:
+                    secret_env_vars.add(env_name)
+        return secret_env_vars
+
+    @staticmethod
+    def _relative_source_name(path: Path, base_dir: Path) -> str:
+        return os.path.relpath(path, base_dir).replace(os.sep, "/")
+
+    def _build_env_xfile(self, sources: List[str], excluded_names: set) -> Optional[Dict[str, str]]:
+        seen = set()
+        lines = []
+        for source in sources:
+            for name, default in self._iter_env_refs(source):
+                if name in seen or name in excluded_names:
+                    continue
+                value = os.environ.get(name)
+                if value in (None, "") and default is not None:
+                    value = default
+                if value in (None, ""):
+                    continue
+                seen.add(name)
+                lines.append(f"{name}={value}")
+        if not lines:
+            return None
+        content = ("\n".join(lines) + "\n").encode("utf-8")
+        return {"path": ".env", "content": self._b64_content(content)}
+
+    def _collect_config_source_files(self, compose_data: dict, base_dir: Path) -> Tuple[List[Dict[str, str]], List[str]]:
+        x_files = []
+        env_sources = []
+        configs = compose_data.get("configs", {})
+        if not isinstance(configs, dict):
+            return x_files, env_sources
+
+        for details in configs.values():
+            if not isinstance(details, dict):
+                continue
+            source_path = details.get("x-template-file", details.get("file"))
+            if not source_path:
+                continue
+            filename = (base_dir / source_path).resolve()
+            content = filename.read_bytes()
+            x_files.append(
+                {
+                    "path": self._relative_source_name(filename, base_dir),
+                    "content": self._b64_content(content),
+                }
+            )
+            env_sources.append(content.decode("utf-8", errors="ignore"))
+        return x_files, env_sources
+
+    def rendered_compose_file(self, compose_file, stack=None, include_build=True) -> RenderedCompose:
+        compose_path = Path(compose_file).resolve()
+        template_bytes = compose_path.read_bytes()
+        template_content = template_bytes.decode("utf-8")
         # Parse the YAML content
         compose_data = self.decode_yaml(template_content)
+        base_dir = compose_path.parent
+        source_x_files: List[Dict[str, str]] = []
+        env_sources = [template_content]
+        secret_env_vars = self._secret_environment_vars(compose_data)
+        if stack:
+            source_x_files, config_env_sources = self._collect_config_source_files(compose_data, base_dir)
+            env_sources.extend(config_env_sources)
         if not include_build:
             services: dict = compose_data.get("services", {})
             for k, v in services.items():
                 if "build" in v:
                     del v["build"]
         if stack:
-            base_dir = os.path.dirname(os.path.abspath(compose_file))
             if "configs" in compose_data:
                 compose_data["configs"] = self._process_x_content(
-                    compose_data["configs"], self.docker.config, base_dir=base_dir, stack=stack
+                    compose_data["configs"], self.docker.config, base_dir=str(base_dir), stack=stack
                 )
             if "secrets" in compose_data:
                 compose_data["secrets"] = self._process_x_content(
-                    compose_data["secrets"], self.docker.secret, base_dir=base_dir, stack=stack
+                    compose_data["secrets"], self.docker.secret, base_dir=str(base_dir), stack=stack
                 )
 
         # Define the replacements for '$' to '$$' for env variables in compose files
         replacements_map = {"$": "$$"}
-        return envsubst(yaml.dump(compose_data, sort_keys=False), replacements=replacements_map)
+        clean_content = envsubst(yaml.dump(compose_data, sort_keys=False), replacements=replacements_map)
+        enriched_data = yaml.safe_load(clean_content) or {}
+        x_files = [
+            {"path": "compose.yml", "content": self._b64_content(template_bytes)},
+        ]
+        env_xfile = self._build_env_xfile(env_sources, secret_env_vars)
+        if env_xfile:
+            x_files.append(env_xfile)
+        x_files.extend(source_x_files)
+        if isinstance(enriched_data, dict):
+            enriched_data["x-files"] = x_files
+        enriched_content = yaml.dump(enriched_data, sort_keys=False)
+        return RenderedCompose(clean=clean_content, enriched=enriched_content)
 
     def decode_yaml(self, data: str) -> dict:
         return yaml.safe_load(data)
@@ -287,15 +398,7 @@ class DockerStack:
         """
         Render the Docker Compose file with environment variables and create Docker configs/secrets.
         """
-
-        # Convert the modified data back to YAML
-        rendered_content = self.rendered_compose_file(compose_file, stack, include_build=include_build)
-
-        # Write the rendered file
-        rendered_filename = Path(compose_file).with_name(f"{Path(compose_file).stem}-rendered{Path(compose_file).suffix}")
-        with open(rendered_filename, "w") as f:
-            f.write(rendered_content)
-        return (rendered_filename, rendered_content)
+        return self.rendered_compose_file(compose_file, stack, include_build=include_build)
 
     def _process_x_content(self, objects, manager: DockerObjectManager, base_dir="", stack=None):
         """
@@ -354,7 +457,7 @@ class DockerStack:
                 processed_objects[name] = {"name": response["actual_name"], "external": True}
                 return
 
-            (object_name, command) = manager.create(docker_object_name, data, labels=labels, stack=stack)
+            object_name, command = manager.create(docker_object_name, data, labels=labels, stack=stack)
             if not command.isNop():
                 self.commands.append(command)
                 if is_generated_secret:
@@ -366,7 +469,7 @@ class DockerStack:
             if isinstance(details, dict) and "x-content" in details:
                 add_obj(name, details["x-content"], explicit_name=explicit_name)
             elif isinstance(details, dict) and "x-template" in details:
-                add_obj(name, envsubst(details["x-content"], os.environ), explicit_name=explicit_name)
+                add_obj(name, envsubst(details["x-template"], os.environ), explicit_name=explicit_name)
             elif isinstance(details, dict) and "x-template-file" in details:
                 filename = os.path.join(base_dir, details["x-template-file"])
                 add_obj(name, envsubst_load_file(filename, os.environ), explicit_name=explicit_name)
@@ -374,8 +477,15 @@ class DockerStack:
                 filename = os.path.join(base_dir, details["file"])
                 with open(filename) as file:
                     add_obj(name, file.read(), explicit_name=explicit_name)
-            elif isinstance(details, dict) and "x-generate" in details and manager.object_type == "secret":
-                generate_options = details["x-generate"]
+            elif isinstance(details, dict) and manager.object_type == "secret" and "environment" in details:
+                env_name = str(details["environment"]).strip()
+                env_value = os.environ.get(env_name)
+                if env_value in (None, ""):
+                    raise ValueError(f"Secret {name} references environment variable {env_name}, but it is not set.")
+                add_obj(name, env_value, explicit_name=explicit_name)
+            elif isinstance(details, dict) and manager.object_type == "secret" and ("x-generate" in details or "x-generated" in details):
+                # Support both spellings for compatibility.
+                generate_options = details.get("x-generate", details.get("x-generated"))
                 if isinstance(generate_options, bool) and generate_options:
                     if manager_client and stack:
                         add_obj(name, "", explicit_name=explicit_name, is_generated_secret=True, generate_options={})
@@ -383,7 +493,9 @@ class DockerStack:
                         add_obj(name, generate_secret(), explicit_name=explicit_name, is_generated_secret=True)
                 elif isinstance(generate_options, int):
                     if manager_client and stack:
-                        add_obj(name, "", explicit_name=explicit_name, is_generated_secret=True, generate_options={"length": generate_options})
+                        add_obj(
+                            name, "", explicit_name=explicit_name, is_generated_secret=True, generate_options={"length": generate_options}
+                        )
                     else:
                         add_obj(name, generate_secret(length=generate_options), explicit_name=explicit_name, is_generated_secret=True)
                 elif isinstance(generate_options, dict):
@@ -433,12 +545,6 @@ class DockerStack:
     @staticmethod
     def _version_sort_key(raw: str):
         return int(raw) if raw.isdigit() else raw
-    @staticmethod
-    def _display_stack_name(raw: str) -> str:
-        value = raw.strip()
-        if value.startswith("default--"):
-            return value[len("default--"):]
-        return value
 
     def _print_stack_listing(self, stack_versions: Dict[str, List[str]]) -> None:
         max_stack_name_length = max(len(stack) for stack in stack_versions) if stack_versions else 10
@@ -468,12 +574,10 @@ class DockerStack:
             try:
                 payload = client.list_stacks()
                 stack_versions = {
-                    self._display_stack_name(str(item.get("stack"))): [
+                    str(item.get("stack")): [
                         str(version)
                         for version in (
-                            item.get("versions")
-                            if isinstance(item.get("versions"), list)
-                            else item.get("available_versions", [])
+                            item.get("versions") if isinstance(item.get("versions"), list) else item.get("available_versions", [])
                         )
                         if str(version).strip()
                     ]
@@ -494,7 +598,7 @@ class DockerStack:
             parts = line.split("\t")
             if len(parts) == 3 and "mesudip.stack.name" in parts[2]:
                 labels = {k: v for k, v in (label.split("=") for label in parts[2].split(",") if "=" in label)}
-                stack_name = self._display_stack_name(labels.get("mesudip.stack.name", "")) or None
+                stack_name = labels.get("mesudip.stack.name")
                 version = labels.get("mesudip.object.version", "unknown")
 
                 if stack_name:
@@ -565,7 +669,7 @@ class DockerStack:
             parts = line.split("\t")
             if len(parts) == 2 and "mesudip.stack.name" in parts[1]:
                 labels = {k: v for k, v in (label.split("=") for label in parts[1].split(",") if "=" in label)}
-                stack = self._display_stack_name(labels.get("mesudip.stack.name", "")) or None
+                stack = labels.get("mesudip.stack.name")
                 version = labels.get("mesudip.object.version", "unknown")
                 tag = labels.get("mesudip.stack.tag", "")
 
@@ -651,15 +755,12 @@ class DockerStack:
                 version = matching_versions[0]
             compose_content = self.cat(stack_name, version, namespace=namespace)
 
-        temp_file = f"/tmp/{stack_name}_v{version}.yml"
-        with open(temp_file, "w") as f:
-            f.write(compose_content)
-
+        deploy_content = self._strip_source_metadata(compose_content)
         print(f"Deploying stack {stack_name} with version {version} (tag: {tag})...")
         self._deploy(
             stack_name,
-            temp_file,
-            compose_content,
+            deploy_content,
+            stored_content=compose_content,
             with_registry_auth=with_registry_auth,
             tag=tag,
             namespace=namespace,
@@ -669,13 +770,14 @@ class DockerStack:
     def _deploy(
         self,
         stack_name,
-        rendered_filename,
         rendered_content,
+        stored_content=None,
         with_registry_auth=False,
         tag=None,
         namespace: str = "default",
         dry_run: bool = False,
     ):
+        stored_content = stored_content if stored_content is not None else rendered_content
         labels = [
             f"mesudip.stack.name={stack_name}",
             f"com.mesudip.namespace={namespace}",
@@ -685,19 +787,21 @@ class DockerStack:
             labels.append(f"mesudip.stack.tag={tag}")
 
         manager_deploy = self._manager_client_for_feature(FEATURE_STACK_DEPLOY)
-        if manager_deploy and not with_registry_auth and dry_run:
+        manager_options = {"with_registry_auth": with_registry_auth} if with_registry_auth else {}
+        if manager_deploy and dry_run:
             self._validate_via_manager(
                 manager_deploy,
                 stack_name=stack_name,
                 namespace=namespace,
-                rendered_content=rendered_content,
+                rendered_content=stored_content,
+                options=manager_options,
             )
             return
 
         # Manager-backed deploys must stay on the manager stack APIs. Hitting
         # direct daemon config endpoints here breaks GitHub OIDC workflows,
         # which are intentionally restricted away from generic daemon access.
-        if manager_deploy and not with_registry_auth:
+        if manager_deploy:
             self.commands.append(
                 CallbackCommand(
                     f"docker-manager stack deploy {stack_name}",
@@ -705,20 +809,21 @@ class DockerStack:
                         manager_deploy,
                         stack_name=stack_name,
                         namespace=namespace,
-                        rendered_content=rendered_content,
+                        rendered_content=stored_content,
+                        options=manager_options,
                     ),
                 )
             )
             return
 
-        _, cmd = self.docker.config.increment(stack_name, rendered_content, labels=labels, stack=stack_name)
+        _, cmd = self.docker.config.increment(stack_name, stored_content, labels=labels, stack=stack_name)
         if not cmd.isNop():
             self.commands.append(cmd)
 
-        cmd = ["docker", "stack", "deploy", "-c", str(rendered_filename), stack_name]
+        cmd = ["docker", "stack", "deploy", "-c", "-", stack_name]
         if with_registry_auth:
             cmd.insert(3, "--with-registry-auth")
-        self.commands.append(Command(cmd, give_console=True))
+        self.commands.append(Command(cmd, stdin=rendered_content, give_console=True))
 
     @staticmethod
     def _validate_via_manager(
@@ -727,12 +832,13 @@ class DockerStack:
         stack_name: str,
         namespace: str,
         rendered_content: str,
+        options: Dict[str, object],
     ) -> Optional[str]:
         payload = manager_client.validate_stack(
             stack=stack_name,
             namespace=namespace,
             compose=rendered_content,
-            options={},
+            options=options,
         )
         warnings = payload.get("warnings") or []
         for warning in warnings:
@@ -741,10 +847,7 @@ class DockerStack:
         service_count = summary.get("service_count", 0)
         config_count = summary.get("config_count", 0)
         secret_count = summary.get("secret_count", 0)
-        print(
-            "[manager] validation: "
-            f"services={service_count}, configs={config_count}, secrets={secret_count}"
-        )
+        print("[manager] validation: " f"services={service_count}, configs={config_count}, secrets={secret_count}")
         return None
 
     @staticmethod
@@ -754,12 +857,13 @@ class DockerStack:
         stack_name: str,
         namespace: str,
         rendered_content: str,
+        options: Dict[str, object],
     ) -> Optional[str]:
         payload = manager_client.deploy_stack(
             stack=stack_name,
             namespace=namespace,
             compose=rendered_content,
-            options={},
+            options=options,
         )
         warnings = payload.get("warnings") or []
         for warning in warnings:
@@ -807,11 +911,11 @@ class DockerStack:
         dry_run: bool = False,
     ):
         self.generated_secrets = {}  # Reset for each deployment
-        rendered_filename, rendered_content = self.render_compose_file(compose_file, stack=stack_name, include_build=False)
+        rendered = self.render_compose_file(compose_file, stack=stack_name, include_build=False)
         self._deploy(
             stack_name,
-            rendered_filename,
-            rendered_content,
+            rendered.clean,
+            stored_content=rendered.enriched,
             with_registry_auth=with_registry_auth,
             tag=tag,
             namespace=namespace,
@@ -922,10 +1026,7 @@ class DockerNode:
             ("Address", "address"),
         ]
 
-        widths = {
-            key: max(len(title), max((len(str(row[key])) for row in rows), default=0))
-            for title, key in columns
-        }
+        widths = {key: max(len(title), max((len(str(row[key])) for row in rows), default=0)) for title, key in columns}
         terminal_width = shutil.get_terminal_size((120, 20)).columns
         static_width = sum(widths.values()) + (3 * (len(columns) - 1))
         label_width = max(24, min(60, terminal_width - static_width - 3 - len("Labels")))
@@ -973,9 +1074,7 @@ class DockerNode:
             if not line:
                 continue
             node = json.loads(line)
-            inspect = json.loads(
-                run_cli_command(["docker", "node", "inspect", node["ID"], "--format", "{{json .}}"], log=False)
-            )
+            inspect = json.loads(run_cli_command(["docker", "node", "inspect", node["ID"], "--format", "{{json .}}"], log=False))
             labels = inspect.get("Spec", {}).get("Labels", {})
             manager_status = node.get("ManagerStatus", "").strip()
             role = inspect.get("Spec", {}).get("Role", "-")
@@ -997,12 +1096,22 @@ class DockerNode:
 
 def open_context_shell(config_dir: Path, context_name: str) -> int:
     env = dict(os.environ)
+    for key in DOCKER_SHELL_ENDPOINT_ENV_VARS:
+        env.pop(key, None)
     env["DOCKER_CONFIG"] = str(config_dir)
     env["DOCKER_CONTEXT"] = context_name
     shell = env.get("SHELL", "").strip() or "/bin/bash"
     return subprocess.run([shell, "-i"], check=False, env=env).returncode
 
 
+def active_shell_config_dir(context_name: str) -> Optional[Path]:
+    docker_config = os.getenv("DOCKER_CONFIG", "").strip()
+    docker_context = os.getenv("DOCKER_CONTEXT", "").strip()
+    if not docker_config or docker_context != context_name:
+        return None
+    return Path(docker_config)
+
+
 def main(args: List[str] = None):
     parser = argparse.ArgumentParser(description="Deploy and manage Docker stacks.")
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -1107,19 +1216,30 @@ def main(args: List[str] = None):
                 context_name=args.context_name,
                 timeout_secs=args.timeout_secs,
             )
-            result = docker_manager_login(config)
+            current_shell_config = active_shell_config_dir(config.context_name)
+            if current_shell_config:
+                config_dir, result = ensure_isolated_login(config, docker_config_dir=current_shell_config)
+            else:
+                config_dir = None
+                result = docker_manager_login(config)
         except RuntimeError as exc:
             print(f"docker-stack login: {exc}", file=sys.stderr)
             sys.exit(2)
-        print("Docker-Manager browser login successful.")
-        print(f"Callback: {result.redirect_uri}")
+        if result is None:
+            print("Docker-Manager login already active.")
+        else:
+            print("Docker-Manager browser login successful.")
+            print(f"Callback: {result.redirect_uri}")
         print(f"DOCKER_CONTEXT={config.context_name}")
+        if config_dir is not None:
+            print(f"DOCKER_CONFIG={config_dir}")
         print(f"Context host={config.docker_context_host}")
         if config.manager_url.startswith("https://"):
             print(f"TLS detected for manager endpoint ({'verification skipped' if config.skip_tls_verify else 'verified'})")
-        expiry = format_expiry(result.expires_at)
-        if expiry:
-            print(f"Access token expires in {expiry}")
+        if result is not None:
+            expiry = format_expiry(result.expires_at)
+            if expiry:
+                print(f"Access token expires in {expiry}")
         print("Try: docker ps")
         return
 
@@ -1133,11 +1253,15 @@ def main(args: List[str] = None):
                 context_name=args.context_name,
                 timeout_secs=args.timeout_secs,
             )
+            existing_shell_config = active_shell_config_dir(config.context_name)
             config_dir, result = ensure_isolated_login(config)
         except RuntimeError as exc:
             print(f"docker-stack shell: {exc}", file=sys.stderr)
             sys.exit(2)
-        print(f"Shell context={config.context_name}")
+        if existing_shell_config:
+            print(f"Refreshing current shell context={config.context_name}")
+        else:
+            print(f"Opening shell context={config.context_name}")
         print(f"Shell manager={config.manager_url}")
         print(f"DOCKER_CONFIG={config_dir}")
         if result is not None: