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