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 (enabled by default). 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| `push` | Build or push attachment images to the Gordon registry |
23| `remove` | Remove an attachment from a domain or network group |
24
25### Alias
26
27`gordon attach` is an alias for `gordon attachments`:
28
29```bash
30gordon attach list
31gordon attach add app.example.com postgres:18
32gordon attach remove app.example.com postgres:18
33```
34
35---
36
37## gordon attachments list
38
39List all configured attachments.
40
41```bash
42# List all attachments
43gordon attachments list
44gordon attachments list --json
45
46# List attachments for a specific domain or group
47gordon attachments list app.example.com
48gordon attachments list backend
49
50# Remote (override)
51gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
52```
53
54### Output
55
56```
57Target                    Attachments
58--------------------------------------------------------------------------------
59app.example.com           postgres:18, redis:7-alpine
60api.example.com           postgres:18
61backend (group)           rabbitmq:3-management
62```
63
64### JSON Output
65
66```bash
67gordon attachments list --json
68```
69
70```json
71[
72  {
73    "target": "app.example.com",
74    "attachments": ["postgres:18", "redis:7-alpine"]
75  },
76  {
77    "target": "backend",
78    "attachments": ["rabbitmq:3-management"]
79  }
80]
81```
82
83### Options
84
85| Option | Description |
86|--------|-------------|
87| `--json` | Output attachments as JSON |
88| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
89| `--token` | Authentication token for remote |
90
91---
92
93## gordon attachments add
94
95Add an attachment to a domain or network group.
96
97```bash
98gordon attachments add <domain-or-group> <image>
99gordon attachments add app.example.com postgres:18
100gordon attachments add backend redis:7-alpine
101```
102
103### Arguments
104
105| Argument | Description |
106|----------|-------------|
107| `<domain-or-group>` | The domain name or network group name |
108| `<image>` | The container image to attach |
109
110### Options
111
112| Option | Description |
113|--------|-------------|
114| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
115| `--token` | Authentication token for remote |
116
117### Examples
118
119```bash
120# Add database to a domain
121gordon attachments add app.example.com postgres:18
122
123# Add cache to a network group (shared by all domains in the group)
124gordon attachments add backend redis:7-alpine
125
126# Remote (override)
127gordon attachments add app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
128```
129
130---
131
132## gordon attachments push
133
134Push attachment images to the Gordon registry.
135
136```bash
137gordon attachments push <image> [options]
138```
139
140### Arguments
141
142| Argument | Description |
143|----------|-------------|
144| `<image>` | The attachment image to build/tag and push |
145
146### Options
147
148| Option | Description |
149|--------|-------------|
150| `--build` | Build the image first using `docker buildx` |
151| `-f, --file` | Path to Dockerfile (default: `./Dockerfile`, used with `--build`) |
152| `--platform` | Target platform for buildx (default: `linux/amd64`) |
153| `--build-arg` | Additional build args (repeatable, `KEY=VALUE`) |
154| `--tag` | Override version tag |
155| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
156| `--token` | Authentication token for remote |
157
158### Description
159
160`gordon attachments push` pushes attachment images such as databases and caches to the Gordon registry so they are available when routes deploy. It does not trigger deployment. The image must already be configured as an attachment first.
161
162It uses the same native chunked upload transport as `gordon push`, sending image
163layers in 50MB chunks so pushes work through Cloudflare-proxied Gordon
164instances. Keep the server's `max_blob_chunk_size` larger than the client chunk
165size; the default `95MB` is compatible.
166
167### Examples
168
169```bash
170# Push a pre-built attachment image
171gordon attachments push pitlane-pgsql
172
173# Build and push an attachment image
174gordon attachments push pitlane-pgsql --build
175
176# Push with a specific tag
177gordon attachments push pitlane-pgsql --tag v18
178```
179
180---
181
182## gordon attachments remove
183
184Remove an attachment.
185
186```bash
187gordon attachments remove <domain-or-group> <image>
188gordon attachments remove app.example.com postgres:18
189```
190
191### Arguments
192
193| Argument | Description |
194|----------|-------------|
195| `<domain-or-group>` | The domain name or network group name |
196| `<image>` | The container image to remove |
197
198### Options
199
200| Option | Description |
201|--------|-------------|
202| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
203| `--token` | Authentication token for remote |
204
205### Examples
206
207```bash
208# Remove database from a domain
209gordon attachments remove app.example.com postgres:18
210
211# Remove from network group
212gordon attachments remove backend redis:7-alpine
213
214# Remote (override)
215gordon attachments remove app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
216```
217
218---
219
220## Workflow Examples
221
222### Add Database and Cache
223
224```bash
225# Add PostgreSQL database
226gordon attachments add app.example.com postgres:18
227
228# Add Redis cache
229gordon attachments add app.example.com redis:7-alpine
230
231# Verify
232gordon attachments list app.example.com
233```
234
235### Shared Services via Network Groups
236
237```bash
238# First, ensure you have a network group defined in your config:
239# [network_groups]
240# "backend" = ["app.example.com", "api.example.com"]
241
242# Add shared cache to the group
243gordon attachments add backend redis:7-alpine
244
245# Both app.example.com and api.example.com can now access the shared Redis
246```
247
248### First Deploy with Custom Attachment Image
249
250```bash
251# Configure the route and attachment
252gordon bootstrap app.example.com myapp:latest --attachment pitlane-pgsql
253
254# Push the custom attachment image first
255gordon attachments push pitlane-pgsql --build
256
257# Then push and deploy the route image
258gordon push myapp:latest --domain app.example.com --build --no-confirm
259```
260
261### CI/CD Integration
262
263```bash
264# In your CI/CD pipeline
265export GORDON_REMOTE=https://gordon.mydomain.com
266export GORDON_TOKEN=$GORDON_TOKEN
267
268# Add new attachment
269gordon attachments add app.example.com elasticsearch:8
270
271# Trigger redeploy to pick up the new attachment
272gordon routes deploy app.example.com
273```
274
275## Related
276
277- [CLI Overview](./index.md)
278- [Attachments Configuration](../config/attachments.md)
279- [Network Groups](../config/network-groups.md)