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