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