1# Attachments Commands
2
3Manage attachments on local or remote Gordon instances.
4
5Remote targeting uses client config or an active remote by default.
6Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
7
8## Requirements
9
10Attachments require `network_isolation.enabled = true` in your configuration. Without network isolation, containers use Docker's default bridge network which does not provide DNS resolution - your app won't be able to reach attachments by hostname (e.g., `postgres:5432`).
11
12The CLI will warn you if you try to add an attachment without network isolation enabled.
13
14## gordon attachments
15
16### Subcommands
17
18| Subcommand | Description |
19|------------|-------------|
20| `list` | List all attachments or attachments for a specific target |
21| `add` | Add an attachment to a domain or network group |
22| `remove` | Remove an attachment from a domain or network group |
23
24### Alias
25
26`gordon attach` is an alias for `gordon attachments`:
27
28```bash
29gordon attach list
30gordon attach add app.example.com postgres:18
31gordon attach remove app.example.com postgres:18
32```
33
34---
35
36## gordon attachments list
37
38List all configured attachments.
39
40```bash
41# List all attachments
42gordon attachments list
43
44# List attachments for a specific domain or group
45gordon attachments list app.example.com
46gordon attachments list backend
47
48# Remote (override)
49gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
50```
51
52### Output
53
54```
55Target                    Attachments
56--------------------------------------------------------------------------------
57app.example.com           postgres:18, redis:7-alpine
58api.example.com           postgres:18
59backend (group)           rabbitmq:3-management
60```
61
62---
63
64## gordon attachments add
65
66Add an attachment to a domain or network group.
67
68```bash
69gordon attachments add <domain-or-group> <image>
70gordon attachments add app.example.com postgres:18
71gordon attachments add backend redis:7-alpine
72```
73
74### Arguments
75
76| Argument | Description |
77|----------|-------------|
78| `<domain-or-group>` | The domain name or network group name |
79| `<image>` | The container image to attach |
80
81### Options
82
83| Option | Description |
84|--------|-------------|
85| `--remote` | Remote Gordon URL |
86| `--token` | Authentication token for remote |
87
88### Examples
89
90```bash
91# Add database to a domain
92gordon attachments add app.example.com postgres:18
93
94# Add cache to a network group (shared by all domains in the group)
95gordon attachments add backend redis:7-alpine
96
97# Remote (override)
98gordon attachments add app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
99```
100
101---
102
103## gordon attachments remove
104
105Remove an attachment.
106
107```bash
108gordon attachments remove <domain-or-group> <image>
109gordon attachments remove app.example.com postgres:18
110```
111
112### Arguments
113
114| Argument | Description |
115|----------|-------------|
116| `<domain-or-group>` | The domain name or network group name |
117| `<image>` | The container image to remove |
118
119### Options
120
121| Option | Description |
122|--------|-------------|
123| `--remote` | Remote Gordon URL |
124| `--token` | Authentication token for remote |
125
126### Examples
127
128```bash
129# Remove database from a domain
130gordon attachments remove app.example.com postgres:18
131
132# Remove from network group
133gordon attachments remove backend redis:7-alpine
134
135# Remote (override)
136gordon attachments remove app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
137```
138
139---
140
141## Workflow Examples
142
143### Add Database and Cache
144
145```bash
146# Add PostgreSQL database
147gordon attachments add app.example.com postgres:18
148
149# Add Redis cache
150gordon attachments add app.example.com redis:7-alpine
151
152# Verify
153gordon attachments list app.example.com
154```
155
156### Shared Services via Network Groups
157
158```bash
159# First, ensure you have a network group defined in your config:
160# [network_groups]
161# "backend" = ["app.example.com", "api.example.com"]
162
163# Add shared cache to the group
164gordon attachments add backend redis:7-alpine
165
166# Both app.example.com and api.example.com can now access the shared Redis
167```
168
169### CI/CD Integration
170
171```bash
172# In your CI/CD pipeline
173export GORDON_REMOTE=https://gordon.mydomain.com
174export GORDON_TOKEN=$GORDON_TOKEN
175
176# Add new attachment
177gordon attachments add app.example.com elasticsearch:8
178
179# Trigger redeploy to pick up the new attachment
180gordon routes deploy app.example.com
181```
182
183## Related
184
185- [CLI Overview](./index.md)
186- [Attachments Configuration](../config/attachments.md)
187- [Network Groups](../config/network-groups.md)