1# Volumes Configuration
2
3Configure automatic persistent storage for containers.
4
5## Configuration
6
7```toml
8[volumes]
9auto_create = true
10prefix = "gordon"
11preserve = true
12```
13
14## Options
15
16| Option | Type | Default | Description |
17|--------|------|---------|-------------|
18| `auto_create` | bool | `true` | Automatically create volumes from Dockerfile VOLUME |
19| `prefix` | string | `"gordon"` | Prefix for volume names |
20| `preserve` | bool | `true` | Keep volumes when containers are removed |
21
22## How It Works
23
24Gordon automatically creates Docker volumes from Dockerfile `VOLUME` directives:
25
26```dockerfile
27FROM postgres:18
28VOLUME ["/var/lib/postgresql/data"]
29```
30
31When Gordon deploys this container:
32
331. Reads `VOLUME` directives from image metadata
342. Creates named volumes with `prefix-domain-path` naming
353. Mounts volumes to the container
364. Preserves data across container updates
37
38## Volume Naming
39
40Volumes are named: `{prefix}-{domain}-{path}`
41
42| Domain | Volume Path | Volume Name |
43|--------|-------------|-------------|
44| `app.mydomain.com` | `/data` | `gordon-app-mydomain-com-data` |
45| `db.mydomain.com` | `/var/lib/postgresql/data` | `gordon-db-mydomain-com-var-lib-postgresql-data` |
46
47## Persistence
48
49### Default: Preserve Volumes
50
51```toml
52[volumes]
53preserve = true
54```
55
56With `preserve = true`:
57- Volumes persist when containers are updated
58- Data survives container restarts
59- Volumes remain even if container is removed
60
61### Remove with Container
62
63```toml
64[volumes]
65preserve = false
66```
67
68With `preserve = false`:
69- Volumes are removed when containers are removed
70- Useful for stateless containers
71- Frees up disk space automatically
72
73## Examples
74
75### Database Container
76
77```dockerfile
78# my-postgres.Dockerfile
79FROM postgres:18
80VOLUME ["/var/lib/postgresql/data"]
81ENV POSTGRES_DB=myapp
82ENV POSTGRES_USER=app
83```
84
85Gordon automatically:
86- Creates `gordon-db-mydomain-com-var-lib-postgresql-data` volume
87- Mounts it to `/var/lib/postgresql/data`
88- Preserves data across postgres container updates
89
90### Application with Uploads
91
92```dockerfile
93FROM node:18
94WORKDIR /app
95VOLUME ["/app/uploads", "/app/data"]
96COPY . .
97CMD ["npm", "start"]
98```
99
100Creates two volumes:
101- `gordon-app-mydomain-com-app-uploads`
102- `gordon-app-mydomain-com-app-data`
103
104### Custom Prefix
105
106```toml
107[volumes]
108prefix = "prod"
109```
110
111Volume names become:
112- `prod-app-mydomain-com-data`
113- `prod-db-mydomain-com-var-lib-postgresql-data`
114
115## Managing Volumes
116
117### List Volumes
118
119```bash
120docker volume ls | grep gordon
121```
122
123### Inspect Volume
124
125```bash
126docker volume inspect gordon-app-mydomain-com-data
127```
128
129### Backup Volume
130
131```bash
132docker run --rm \
133  -v gordon-db-mydomain-com-var-lib-postgresql-data:/data \
134  -v $(pwd):/backup \
135  alpine tar -czf /backup/db-backup.tar.gz -C /data .
136```
137
138### Restore Volume
139
140```bash
141docker run --rm \
142  -v gordon-db-mydomain-com-var-lib-postgresql-data:/data \
143  -v $(pwd):/backup \
144  alpine tar -xzf /backup/db-backup.tar.gz -C /data
145```
146
147## Volume Cleanup
148
149If you have orphaned volumes:
150
151```bash
152# List all gordon volumes
153docker volume ls -f name=gordon
154
155# Remove specific volume (warning: deletes data!)
156docker volume rm gordon-old-app-data
157
158# Prune unused volumes (be careful!)
159docker volume prune
160```
161
162## Related
163
164- [Attachments](./attachments.md)
165- [Configuration Overview](./index.md)