1# Attachments Configuration
2
3Attach service dependencies (databases, caches, queues) to your applications.
4
5## Configuration
6
7```toml
8[attachments]
9"app.mydomain.com" = ["postgres:latest", "redis:latest"]
10"api.mydomain.com" = ["postgres:latest"]
11```
12
13## Syntax
14
15```toml
16[attachments]
17"<domain-or-group>" = ["<image>:<tag>", "<image>:<tag>"]
18```
19
20| Component | Description |
21|-----------|-------------|
22| `domain-or-group` | Route domain or network group name |
23| `image:tag` | Service images to deploy alongside the app |
24
25## How Attachments Work
26
27When you define attachments:
28
291. Gordon deploys attachment containers to the same network as your app
302. Services are accessible by their image name (before the colon)
313. Attachments start before your main application
324. Attachments persist across app updates
33
34```
35┌───────────────────────────────────────────────────┐
36│ Network: gordon-app-mydomain-com                  │
37│                                                   │
38│  ┌──────────┐    ┌──────────┐    ┌──────────┐     │
39│  │   App    │───>│ postgres │    │  redis   │     │
40│  │  :3000   │    │  :5432   │    │  :6379   │     │
41│  └──────────┘    └──────────┘    └──────────┘     │
42│                                                   │
43└───────────────────────────────────────────────────┘
44```
45
46## Service Discovery
47
48Attachments are accessible by their image name within the network:
49
50```toml
51[attachments]
52"app.mydomain.com" = ["postgres:latest", "redis:latest"]
53```
54
55In your application:
56```javascript
57// Connect using simple hostnames
58const db = await pg.connect("postgresql://postgres:5432/mydb");
59const cache = await redis.connect("redis://redis:6379");
60```
61
62## Persistent Storage
63
64Use Dockerfile VOLUME directives for persistent data:
65
66```dockerfile
67# postgres.Dockerfile
68FROM postgres:15
69VOLUME ["/var/lib/postgresql/data"]
70ENV POSTGRES_DB=myapp
71ENV POSTGRES_USER=app
72ENV POSTGRES_PASSWORD=secret
73```
74
75Build and push to Gordon:
76```bash
77docker build -f postgres.Dockerfile -t my-postgres:latest .
78docker push registry.mydomain.com/my-postgres:latest
79```
80
81Use in attachments:
82```toml
83[attachments]
84"app.mydomain.com" = ["my-postgres:latest"]
85```
86
87## Shared Attachments with Network Groups
88
89Share services between multiple apps using network groups:
90
91```toml
92[network_groups]
93"backend" = ["app.mydomain.com", "api.mydomain.com"]
94
95[attachments]
96"backend" = ["shared-postgres:latest", "shared-redis:latest"]
97```
98
99Both `app.mydomain.com` and `api.mydomain.com` can access the shared services.
100
101## Per-App vs Shared Attachments
102
103### Per-App Attachments
104
105Each app gets its own isolated service instances:
106
107```toml
108[attachments]
109"app.mydomain.com" = ["postgres:latest"]   # App's own postgres
110"api.mydomain.com" = ["postgres:latest"]   # API's own postgres
111```
112
113### Shared Attachments
114
115Multiple apps share the same service instances:
116
117```toml
118[network_groups]
119"backend" = ["app.mydomain.com", "api.mydomain.com"]
120
121[attachments]
122"backend" = ["postgres:latest", "redis:latest"]  # Shared by both
123```
124
125### Mixed Approach
126
127```toml
128[network_groups]
129"backend" = ["app.mydomain.com", "api.mydomain.com"]
130
131[attachments]
132"backend" = ["redis:latest"]                   # Shared cache
133"app.mydomain.com" = ["postgres:latest"]       # App's own database
134"api.mydomain.com" = ["postgres:latest"]       # API's own database
135```
136
137## Examples
138
139### Web App with Database
140
141```toml
142[routes]
143"app.mydomain.com" = "myapp:latest"
144
145[attachments]
146"app.mydomain.com" = ["postgres:15", "redis:7-alpine"]
147```
148
149### Microservices with Shared Queue
150
151```toml
152[routes]
153"orders.mydomain.com" = "orders-service:latest"
154"inventory.mydomain.com" = "inventory-service:latest"
155"notifications.mydomain.com" = "notifications-service:latest"
156
157[network_groups]
158"services" = ["orders.mydomain.com", "inventory.mydomain.com", "notifications.mydomain.com"]
159
160[attachments]
161"services" = ["rabbitmq:3-management"]
162"orders.mydomain.com" = ["orders-db:latest"]
163"inventory.mydomain.com" = ["inventory-db:latest"]
164```
165
166### Custom Service Images
167
168Build custom service images with your configuration:
169
170```dockerfile
171# my-postgres.Dockerfile
172FROM postgres:15
173VOLUME ["/var/lib/postgresql/data"]
174ENV POSTGRES_DB=production
175ENV POSTGRES_USER=appuser
176# Password should come from env file
177```
178
179```dockerfile
180# my-redis.Dockerfile
181FROM redis:7-alpine
182VOLUME ["/data"]
183CMD ["redis-server", "--appendonly", "yes"]
184```
185
186```toml
187[attachments]
188"app.mydomain.com" = ["my-postgres:latest", "my-redis:latest"]
189```
190
191## Container Naming
192
193Attachment containers are named:
194- `gordon-<domain>-<image-name>`
195- Example: `gordon-app-mydomain-com-postgres`
196
197## Labels
198
199Gordon adds labels to attachment containers:
200
201| Label | Value |
202|-------|-------|
203| `gordon.managed` | `true` |
204| `gordon.attachment` | `true` |
205| `gordon.attached-to` | Domain or group name |
206
207## Related
208
209- [Network Isolation](./network-isolation.md)
210- [Network Groups](./network-groups.md)
211- [Routes](./routes.md)