1# Network Isolation
2
3Isolate applications in separate Docker networks for enhanced security.
4
5## Configuration
6
7```toml
8[network_isolation]
9enabled = true
10network_prefix = "gordon"
11internal = false
12```
13
14## Migration Note
15
16As of this release, `network_isolation.enabled` defaults to `true` (previously `false`).
17Existing installs that rely on a shared network must explicitly opt out:
18
19```toml
20[network_isolation]
21enabled = false
22```
23
24## Options
25
26| Option | Type | Default | Description |
27|--------|------|---------|-------------|
28| `enabled` | bool | `true` | Enable per-app network isolation (changed from `false`) |
29| `network_prefix` | string | `"gordon"` | Prefix for created networks |
30| `internal` | bool | `false` | Create isolated Docker networks with Docker's `Internal` flag, blocking direct external egress from containers on those networks. Default remains `false` for compatibility. |
31
32## How It Works
33
34When network isolation is enabled, each application gets its own Docker network:
35
36```
37[network_isolation]
38enabled = true
39network_prefix = "gordon"
40
41[routes]
42"app.mydomain.com" = "myapp:latest"
43"api.mydomain.com" = "myapi:latest"
44```
45
46Creates two isolated networks:
47- `gordon-app-mydomain-com`
48- `gordon-api-mydomain-com`
49
50## Network Naming
51
52Networks are named: `{prefix}-{domain-with-dashes}`
53
54| Domain | Network Name |
55|--------|--------------|
56| `app.mydomain.com` | `gordon-app-mydomain-com` |
57| `api.company.io` | `gordon-api-company-io` |
58| `staging.app.dev` | `gordon-staging-app-dev` |
59
60## Security Benefits
61
62### Without Network Isolation
63
64All containers can potentially communicate:
65
66```
67┌───────────────────────────────────────┐
68│ Default Bridge Network                │
69│                                       │
70│  App A ←──────→ App B ←──────→ App C  │
71│    ↕              ↕              ↕    │
72│  DB A ←──────→ DB B  ←──────→  DB C   │
73│                                       │
74└───────────────────────────────────────┘
75```
76
77### With Network Isolation
78
79Each app is isolated with its dependencies:
80
81```
82┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
83│ gordon-app-a    │  │ gordon-app-b    │  │ gordon-app-c    │
84│                 │  │                 │  │                 │
85│  App A ←→ DB A  │  │  App B ←→ DB B  │  │  App C ←→ DB C  │
86│                 │  │                 │  │                 │
87└─────────────────┘  └─────────────────┘  └─────────────────┘
88        ↑                   ↑                   ↑
89        └───────── No direct communication ─────┘
90```
91
92## Service Discovery
93
94Within an isolated network, services are discoverable by name:
95
96```toml
97[network_isolation]
98enabled = true
99
100[attachments]
101"app.mydomain.com" = ["postgres:latest", "redis:latest"]
102```
103
104Your application connects using simple hostnames:
105
106```python
107# These work within the isolated network
108db = connect("postgresql://postgres:5432/mydb")
109cache = connect("redis://redis:6379")
110```
111
112## Examples
113
114### Basic Isolation
115
116```toml
117[network_isolation]
118enabled = true
119
120[routes]
121"app.mydomain.com" = "myapp:latest"
122"api.mydomain.com" = "myapi:latest"
123
124[attachments]
125"app.mydomain.com" = ["app-postgres:latest"]
126"api.mydomain.com" = ["api-postgres:latest"]
127```
128
129Each app gets its own network with its own database.
130
131### Production Configuration
132
133```toml
134[network_isolation]
135enabled = true
136network_prefix = "prod"
137
138[routes]
139"app.company.com" = "company-app:v2.1.0"
140"api.company.com" = "company-api:v1.5.0"
141"admin.company.com" = "admin-panel:v1.0.0"
142```
143
144Creates networks:
145- `prod-app-company-com`
146- `prod-api-company-com`
147- `prod-admin-company-com`
148
149### Shared Services with Network Groups
150
151When apps need to communicate, use network groups:
152
153```toml
154[network_isolation]
155enabled = true
156
157[network_groups]
158"backend" = ["app.mydomain.com", "api.mydomain.com"]
159
160[attachments]
161"backend" = ["shared-postgres:latest", "shared-redis:latest"]
162```
163
164Both apps share the `gordon-backend` network.
165
166## Inspecting Networks
167
168View created networks:
169
170```bash
171docker network ls | grep gordon
172# gordon-app-mydomain-com
173# gordon-api-mydomain-com
174# gordon-backend
175```
176
177Inspect a network:
178
179```bash
180docker network inspect gordon-app-mydomain-com
181```
182
183## Related
184
185- [Network Groups](./network-groups.md)
186- [Attachments](./attachments.md)
187- [Configuration Overview](./index.md)