attachments.md Raw History Folder

Attachments Commands

Manage attachments on local or remote Gordon instances.

Remote targeting uses client config or an active remote by default. When you provide a concrete target (for example attachments list app.example.com or attachments remove app.example.com postgres:18) and no remote is selected, Gordon can also auto-infer a saved remote when exactly one match is found. Use --remote and --token to override. See CLI Overview.

Requirements

Attachments 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).

The CLI will warn you if you try to add an attachment without network isolation enabled.

gordon attachments

Subcommands

Subcommand	Description
`list`	List all attachments or attachments for a specific target
`add`	Add an attachment to a domain or network group
`push`	Build or push attachment images to the Gordon registry
`remove`	Remove an attachment from a domain or network group
`orphans`	List running attachment containers no longer configured
`prune`	Dry-run or stop orphaned attachment containers while preserving volumes

Alias

gordon attach is an alias for gordon attachments:

gordon attach list
gordon attach add app.example.com postgres:18
gordon attach remove app.example.com postgres:18

gordon attachments list

List all configured attachments.

# List all attachments
gordon attachments list
gordon attachments list --json

# List attachments for a specific domain or group
gordon attachments list app.example.com
gordon attachments list backend

# Remote (override)
gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN

Output

Target                    Attachments
--------------------------------------------------------------------------------
app.example.com           postgres:18, redis:7-alpine
api.example.com           postgres:18
backend (group)           rabbitmq:3-management

JSON Output

gordon attachments list --json

[
  {
    "target": "app.example.com",
    "attachments": ["postgres:18", "redis:7-alpine"]
  },
  {
    "target": "backend",
    "attachments": ["rabbitmq:3-management"]
  }
]

Options

Option	Description
`--json`	Output attachments as JSON
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

gordon attachments orphans

List running attachment containers that are no longer configured.

gordon attachments orphans
gordon attachments orphans --json

Output

Container ID	Name	Image	Status	Owner
`pg123`	`postgres`	`postgres:16`	`running`	`myapp.example.com`

JSON Output

{
  "attachments": [
    {
      "container_id": "pg123",
      "name": "postgres",
      "image": "postgres:16",
      "status": "running",
      "owner": "myapp.example.com"
    }
  ]
}

gordon attachments prune

Lists orphaned attachments by default (dry-run). Use --stop to stop and remove the orphaned containers while preserving attachment volumes/data.

gordon attachments prune          # dry-run/report only
gordon attachments prune --stop   # stop/remove orphaned containers, preserve volumes

Output

Orphaned attachments
  postgres -> postgres:16
Hint: orphaned attachments preserved; rerun with --stop to stop/remove containers while preserving volumes

Output with `--stop`

Removed orphaned attachment containers:
  postgres
Hint: attachment volumes and data were preserved

Options

Option	Description
`--stop`	Stop and remove orphaned attachment containers while preserving volumes/data
`--json`	Output the cleanup report as JSON
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

gordon attachments add

Add an attachment to a domain or network group.

gordon attachments add <domain-or-group> <image>
gordon attachments add app.example.com postgres:18
gordon attachments add backend redis:7-alpine

Arguments

Argument	Description
`<domain-or-group>`	The domain name or network group name
`<image>`	The container image to attach

Options

Option	Description
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Examples

# Add database to a domain
gordon attachments add app.example.com postgres:18

# Add cache to a network group (shared by all domains in the group)
gordon attachments add backend redis:7-alpine

# Remote (override)
gordon attachments add app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN

gordon attachments push

Push attachment images to the Gordon registry.

gordon attachments push <image> [options]

Arguments

Argument	Description
`<image>`	The attachment image to build/tag and push

Options

Option	Description
`--build`	Build the image first using `docker buildx`
`-f, --file`	Path to Dockerfile (default: `./Dockerfile`, used with `--build`)
`--platform`	Target platform for buildx (default: `linux/amd64`)
`--build-arg`	Additional build args (repeatable, `KEY=VALUE`)
`--tag`	Override version tag
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Description

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.

It uses the same native chunked upload transport as gordon push, sending image layers in 50MB chunks so pushes work through Cloudflare-proxied Gordon instances. Keep the server's max_blob_chunk_size larger than the client chunk size; the default 95MB is compatible.

Examples

# Push a pre-built attachment image
gordon attachments push pitlane-pgsql

# Build and push an attachment image
gordon attachments push pitlane-pgsql --build

# Push with a specific tag
gordon attachments push pitlane-pgsql --tag v18

gordon attachments remove

Remove an attachment.

gordon attachments remove <domain-or-group> <image>
gordon attachments remove app.example.com postgres:18

Arguments

Argument	Description
`<domain-or-group>`	The domain name or network group name
`<image>`	The container image to remove

Options

Option	Description
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Examples

# Remove database from a domain
gordon attachments remove app.example.com postgres:18

# Remove from network group
gordon attachments remove backend redis:7-alpine

# Remote (override)
gordon attachments remove app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN

Workflow Examples

Add Database and Cache

# Add PostgreSQL database
gordon attachments add app.example.com postgres:18

# Add Redis cache
gordon attachments add app.example.com redis:7-alpine

# Verify
gordon attachments list app.example.com

Shared Services via Network Groups

# First, ensure you have a network group defined in your config:
# [network_groups]
# "backend" = ["app.example.com", "api.example.com"]

# Add shared cache to the group
gordon attachments add backend redis:7-alpine

# Both app.example.com and api.example.com can now access the shared Redis

First Deploy with Custom Attachment Image

# Configure the route and attachment
gordon bootstrap app.example.com myapp:latest --attachment pitlane-pgsql

# Push the custom attachment image first
gordon attachments push pitlane-pgsql --build

# Then push and deploy the route image
gordon push myapp:latest --domain app.example.com --build --no-confirm

CI/CD Integration

# In your CI/CD pipeline
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=$GORDON_TOKEN

# Add new attachment
gordon attachments add app.example.com elasticsearch:8

# Trigger redeploy to pick up the new attachment
gordon routes deploy app.example.com

source

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| `orphans` | List running attachment containers no longer configured |
28| `prune` | Dry-run or stop orphaned attachment containers while preserving volumes |
29
30### Alias
31
32`gordon attach` is an alias for `gordon attachments`:
33
34```bash
35gordon attach list
36gordon attach add app.example.com postgres:18
37gordon attach remove app.example.com postgres:18
38```
39
40---
41
42## gordon attachments list
43
44List all configured attachments.
45
46```bash
47# List all attachments
48gordon attachments list
49gordon attachments list --json
50
51# List attachments for a specific domain or group
52gordon attachments list app.example.com
53gordon attachments list backend
54
55# Remote (override)
56gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
57```
58
59### Output
60
61```
62Target                    Attachments
63--------------------------------------------------------------------------------
64app.example.com           postgres:18, redis:7-alpine
65api.example.com           postgres:18
66backend (group)           rabbitmq:3-management
67```
68
69### JSON Output
70
71```bash
72gordon attachments list --json
73```
74
75```json
76[
77  {
78    "target": "app.example.com",
79    "attachments": ["postgres:18", "redis:7-alpine"]
80  },
81  {
82    "target": "backend",
83    "attachments": ["rabbitmq:3-management"]
84  }
85]
86```
87
88### Options
89
90| Option | Description |
91|--------|-------------|
92| `--json` | Output attachments as JSON |
93| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
94| `--token` | Authentication token for remote |
95
96---
97
98## gordon attachments orphans
99
100List running attachment containers that are no longer configured.
101
102```bash
103gordon attachments orphans
104gordon attachments orphans --json
105```
106
107### Output
108
109| Container ID | Name | Image | Status | Owner |
110|--------------|------|-------|--------|-------|
111| `pg123` | `postgres` | `postgres:16` | `running` | `myapp.example.com` |
112
113### JSON Output
114
115```json
116{
117  "attachments": [
118    {
119      "container_id": "pg123",
120      "name": "postgres",
121      "image": "postgres:16",
122      "status": "running",
123      "owner": "myapp.example.com"
124    }
125  ]
126}
127```
128
129## gordon attachments prune
130
131Lists orphaned attachments by default (dry-run). Use `--stop` to stop and remove the orphaned containers while preserving attachment volumes/data.
132
133```bash
134gordon attachments prune          # dry-run/report only
135gordon attachments prune --stop   # stop/remove orphaned containers, preserve volumes
136```
137
138### Output
139
140```text
141Orphaned attachments
142  postgres -> postgres:16
143Hint: orphaned attachments preserved; rerun with --stop to stop/remove containers while preserving volumes
144```
145
146### Output with `--stop`
147
148```text
149Removed orphaned attachment containers:
150  postgres
151Hint: attachment volumes and data were preserved
152```
153
154### Options
155
156| Option | Description |
157|--------|-------------|
158| `--stop` | Stop and remove orphaned attachment containers while preserving volumes/data |
159| `--json` | Output the cleanup report as JSON |
160| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
161| `--token` | Authentication token for remote |
162
163## gordon attachments add
164
165Add an attachment to a domain or network group.
166
167```bash
168gordon attachments add <domain-or-group> <image>
169gordon attachments add app.example.com postgres:18
170gordon attachments add backend redis:7-alpine
171```
172
173### Arguments
174
175| Argument | Description |
176|----------|-------------|
177| `<domain-or-group>` | The domain name or network group name |
178| `<image>` | The container image to attach |
179
180### Options
181
182| Option | Description |
183|--------|-------------|
184| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
185| `--token` | Authentication token for remote |
186
187### Examples
188
189```bash
190# Add database to a domain
191gordon attachments add app.example.com postgres:18
192
193# Add cache to a network group (shared by all domains in the group)
194gordon attachments add backend redis:7-alpine
195
196# Remote (override)
197gordon attachments add app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
198```
199
200---
201
202## gordon attachments push
203
204Push attachment images to the Gordon registry.
205
206```bash
207gordon attachments push <image> [options]
208```
209
210### Arguments
211
212| Argument | Description |
213|----------|-------------|
214| `<image>` | The attachment image to build/tag and push |
215
216### Options
217
218| Option | Description |
219|--------|-------------|
220| `--build` | Build the image first using `docker buildx` |
221| `-f, --file` | Path to Dockerfile (default: `./Dockerfile`, used with `--build`) |
222| `--platform` | Target platform for buildx (default: `linux/amd64`) |
223| `--build-arg` | Additional build args (repeatable, `KEY=VALUE`) |
224| `--tag` | Override version tag |
225| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
226| `--token` | Authentication token for remote |
227
228### Description
229
230`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.
231
232It uses the same native chunked upload transport as `gordon push`, sending image
233layers in 50MB chunks so pushes work through Cloudflare-proxied Gordon
234instances. Keep the server's `max_blob_chunk_size` larger than the client chunk
235size; the default `95MB` is compatible.
236
237### Examples
238
239```bash
240# Push a pre-built attachment image
241gordon attachments push pitlane-pgsql
242
243# Build and push an attachment image
244gordon attachments push pitlane-pgsql --build
245
246# Push with a specific tag
247gordon attachments push pitlane-pgsql --tag v18
248```
249
250---
251
252## gordon attachments remove
253
254Remove an attachment.
255
256```bash
257gordon attachments remove <domain-or-group> <image>
258gordon attachments remove app.example.com postgres:18
259```
260
261### Arguments
262
263| Argument | Description |
264|----------|-------------|
265| `<domain-or-group>` | The domain name or network group name |
266| `<image>` | The container image to remove |
267
268### Options
269
270| Option | Description |
271|--------|-------------|
272| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
273| `--token` | Authentication token for remote |
274
275### Examples
276
277```bash
278# Remove database from a domain
279gordon attachments remove app.example.com postgres:18
280
281# Remove from network group
282gordon attachments remove backend redis:7-alpine
283
284# Remote (override)
285gordon attachments remove app.example.com postgres:18 --remote https://gordon.mydomain.com --token $TOKEN
286```
287
288---
289
290## Workflow Examples
291
292### Add Database and Cache
293
294```bash
295# Add PostgreSQL database
296gordon attachments add app.example.com postgres:18
297
298# Add Redis cache
299gordon attachments add app.example.com redis:7-alpine
300
301# Verify
302gordon attachments list app.example.com
303```
304
305### Shared Services via Network Groups
306
307```bash
308# First, ensure you have a network group defined in your config:
309# [network_groups]
310# "backend" = ["app.example.com", "api.example.com"]
311
312# Add shared cache to the group
313gordon attachments add backend redis:7-alpine
314
315# Both app.example.com and api.example.com can now access the shared Redis
316```
317
318### First Deploy with Custom Attachment Image
319
320```bash
321# Configure the route and attachment
322gordon bootstrap app.example.com myapp:latest --attachment pitlane-pgsql
323
324# Push the custom attachment image first
325gordon attachments push pitlane-pgsql --build
326
327# Then push and deploy the route image
328gordon push myapp:latest --domain app.example.com --build --no-confirm
329```
330
331### CI/CD Integration
332
333```bash
334# In your CI/CD pipeline
335export GORDON_REMOTE=https://gordon.mydomain.com
336export GORDON_TOKEN=$GORDON_TOKEN
337
338# Add new attachment
339gordon attachments add app.example.com elasticsearch:8
340
341# Trigger redeploy to pick up the new attachment
342gordon routes deploy app.example.com
343```
344
345## Related
346
347- [CLI Overview](./index.md)
348- [Attachments Configuration](../config/attachments.md)
349- [Network Groups](../config/network-groups.md)

attachments.md RawHistoryFolder

Attachments Commands

Requirements

gordon attachments

Subcommands

Alias

gordon attachments list

Output

JSON Output

Options

gordon attachments orphans

Output

JSON Output

gordon attachments prune

Output

Output with --stop

Options

gordon attachments add

Arguments

Options

Examples

gordon attachments push

Arguments

Options

Description

Examples

gordon attachments remove

Arguments

Options

Examples

Workflow Examples

Add Database and Cache

Shared Services via Network Groups

First Deploy with Custom Attachment Image

CI/CD Integration

Related

attachments.md Raw History Folder

Output with `--stop`