0
# Stack Management
1

2
Docker stack management for deploying multi-service applications using Docker Compose files in swarm mode. Stacks provide a way to manage complex applications as a single unit with shared networks, volumes, and configurations.
3

4
## Capabilities
5

6
### Stack Deployment
7

8
Deploy stacks from Docker Compose files with environment variable support.
9

10
```python { .api }
11
def deploy(
12
    name: str,  
13
    compose_files: List[str],
14
    *,
15
    orchestrator: Optional[str] = None,
16
    prune: bool = False,
17
    resolve_image: str = "always",
18
    with_registry_auth: bool = False,
19
    env_files: Optional[List[str]] = None,
20
    variables: Optional[Dict[str, str]] = None
21
) -> None:
22
    """
23
    Deploy a stack from compose files.
24
    
25
    Parameters:
26
    - name: Stack name
27
    - compose_files: List of Docker Compose files
28
    - orchestrator: Orchestrator to use (swarm/kubernetes)
29
    - prune: Prune services no longer referenced
30
    - resolve_image: Image resolution (always/changed/never)
31
    - with_registry_auth: Use registry authentication
32
    - env_files: Environment files to load
33
    - variables: Environment variables to set
34
    """
35
```
36

37
### Stack Information
38

39
List stacks and inspect stack components.
40

41
```python { .api }
42
def list() -> List[Stack]:
43
    """
44
    List all stacks.
45
    
46
    Returns:
47
    List of Stack objects
48
    """
49

50
def services(stack: Union[str, Stack]) -> List[Service]:
51
    """
52
    List services in a stack.
53
    
54
    Parameters:
55
    - stack: Stack name or Stack object
56
    
57
    Returns:
58
    List of Service objects
59
    """
60

61
def ps(x: Union[str, Stack]) -> List[Task]:
62
    """
63
    List tasks in a stack.
64
    
65
    Parameters:  
66
    - x: Stack name or Stack object
67
    
68
    Returns:
69
    List of Task objects
70
    """
71
```
72

73
### Stack Removal
74

75
Remove stacks and their associated resources.
76

77
```python { .api }
78
def remove(x: Union[str, List[str]]) -> None:
79
    """
80
    Remove one or more stacks.
81
    
82
    Parameters:
83
    - x: Stack name(s) to remove
84
    """
85
```
86

87
**Usage Examples:**
88

89
```python
90
from python_on_whales import docker
91

92
# Deploy stack from compose file
93
docker.stack.deploy(
94
    "my-app-stack",
95
    ["docker-compose.yml", "docker-compose.prod.yml"],
96
    env_files=[".env.prod"],
97
    variables={"REPLICAS": "3", "IMAGE_TAG": "v1.2.0"},
98
    with_registry_auth=True
99
)
100

101
# List all stacks
102
stacks = docker.stack.list()
103
for stack in stacks:
104
    print(f"Stack: {stack.name} - Services: {len(stack.services())}")
105

106
# Get stack services
107
services = docker.stack.services("my-app-stack")
108
for service in services:
109
    print(f"Service: {service.spec.name} - Replicas: {service.spec.mode.replicated.replicas}")
110

111
# Get stack tasks
112
tasks = docker.stack.ps("my-app-stack")
113
for task in tasks:
114
    print(f"Task: {task.name} - State: {task.desired_state} - Node: {task.node_id}")
115

116
# Remove stack
117
docker.stack.remove("my-app-stack")
118
```
119

120
## Types
121

122
```python { .api }
123
class Stack:
124
    name: str
125
    services: int
126
    orchestrator: str
127
    namespace: str
128
    
129
    def remove(self) -> None:
130
        """Remove this stack."""
131
    
132
    def ps(self) -> List[Task]:
133
        """List tasks in this stack."""
134
    
135
    def services(self) -> List[Service]:
136
        """List services in this stack."""
137
```