1# Docker Labels Reference
2
3Labels used by Gordon for container and image metadata.
4
5## Container Labels
6
7Gordon adds these labels to managed containers:
8
9| Label | Value | Description |
10|-------|-------|-------------|
11| `gordon.managed` | `"true"` | Identifies Gordon-managed containers |
12| `gordon.domain` | Domain name | Domain this container serves |
13| `gordon.image` | Image:tag | Original image from configuration |
14| `gordon.route` | Domain name | Route this container handles |
15| `gordon.created` | Timestamp | When Gordon created the container |
16
17### Propagated Image Labels
18
19When an image defines these labels, Gordon copies them onto the container for runtime use (readiness probing, proxy routing):
20
21| Label | Example | Description |
22|-------|---------|-------------|
23| `gordon.proxy.port` | `"3000"` | Port the proxy routes HTTP traffic to |
24| `gordon.health` | `"/healthz"` | Health check endpoint for readiness probing |
25
26These labels only appear on containers whose source image defined them.
27
28### Attachment Labels
29
30Additional labels for attachment containers:
31
32| Label | Value | Description |
33|-------|-------|-------------|
34| `gordon.attachment` | `"true"` | Container is an attachment service |
35| `gordon.attached-to` | Domain/group | Route or network group this serves |
36
37### Backup Labels
38
39Labels used by the backup subsystem:
40
41| Label | Value | Description |
42|-------|-------|-------------|
43| `gordon.backup` | `"true"` / `"false"` | Enables or disables backup behavior for a container |
44| `gordon.backup.type` | e.g. `"postgresql"` | Explicit database type override |
45| `gordon.backup.version` | e.g. `"17"` | Explicit database version override |
46| `gordon.backup.schedule` | e.g. `"hourly,daily"` | Schedule override hint |
47| `gordon.backup.sidecar` | `"true"` | Identifies backup sidecar containers |
48
49## Image Labels
50
51Labels you can set in your Dockerfile:
52
53| Label | Example | Description |
54|-------|---------|-------------|
55| `gordon.domains` | `"app.example.com,www.app.example.com"` | Comma-separated domains for auto-route |
56| `gordon.proxy.port` | `"3000"` | Port to proxy HTTP traffic to |
57| `gordon.health` | `"/healthz"` | HTTP health check endpoint path for readiness probing |
58| `gordon.env-file` | `"/app/.env.example"` | Path to env template file inside the image |
59
60### Health Check Label
61
62When `gordon.health` is set, Gordon performs HTTP GET requests to the specified
63path during deployment and waits for a 2xx or 3xx response before routing traffic
64to the new container:
65
66```dockerfile
67FROM node:20-alpine
68LABEL gordon.health="/api/health"
69EXPOSE 3000
70CMD ["node", "server.js"]
71```
72
73Gordon probes `http://<container-ip>:3000/api/health` until it gets a successful
74response or the `deploy.http_probe_timeout` is reached.
75
76### Proxy Port Label
77
78When an image exposes multiple ports, Gordon needs to know which one serves HTTP:
79
80```dockerfile
81# Gitea exposes SSH (22) and HTTP (3000)
82FROM gitea/gitea:latest
83LABEL gordon.proxy.port=3000
84EXPOSE 22
85EXPOSE 3000
86```
87
88Without this label, Gordon uses the first exposed port.
89
90**When to use:**
91- Image exposes multiple ports
92- First exposed port isn't the HTTP service
93- You want explicit control over routing
94
95## Container Naming
96
97Gordon names containers:
98
99| Pattern | Example |
100|---------|---------|
101| `gordon-{domain}` | `gordon-app-mydomain-com` |
102| `gordon-{domain}-new` | `gordon-app-mydomain-com-new` (during updates) |
103| `gordon-{domain}-{service}` | `gordon-app-mydomain-com-postgres` (attachments) |
104
105## Inspecting Labels
106
107View labels on a container:
108
109```bash
110docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}' | jq
111```
112
113Example output:
114
115```json
116{
117  "gordon.created": "2024-01-15T10:30:00Z",
118  "gordon.domain": "app.mydomain.com",
119  "gordon.image": "myapp:latest",
120  "gordon.managed": "true",
121  "gordon.proxy.port": "3000",
122  "gordon.route": "app.mydomain.com"
123}
124```
125
126## Filtering Containers
127
128Find Gordon-managed containers:
129
130```bash
131# All Gordon containers
132docker ps -f "label=gordon.managed=true"
133
134# Containers for specific domain
135docker ps -f "label=gordon.domain=app.mydomain.com"
136
137# Attachment containers
138docker ps -f "label=gordon.attachment=true"
139
140# Attachments for specific route
141docker ps -f "label=gordon.attached-to=app.mydomain.com"
142
143# Backup sidecars
144docker ps -f "label=gordon.backup.sidecar=true"
145```
146
147## Examples
148
149### Standard Application Container
150
151```bash
152docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}'
153```
154
155```json
156{
157  "gordon.managed": "true",
158  "gordon.domain": "app.mydomain.com",
159  "gordon.image": "myapp:v2.1.0",
160  "gordon.route": "app.mydomain.com",
161  "gordon.created": "2024-01-15T10:30:00Z"
162}
163```
164
165### Attachment Container
166
167```bash
168docker inspect gordon-app-mydomain-com-postgres --format '{{json .Config.Labels}}'
169```
170
171```json
172{
173  "gordon.managed": "true",
174  "gordon.attachment": "true",
175  "gordon.attached-to": "app.mydomain.com",
176  "gordon.created": "2024-01-15T10:29:00Z"
177}
178```
179
180### Multi-Port Dockerfile
181
182```dockerfile
183FROM node:18
184LABEL gordon.proxy.port=3000
185
186WORKDIR /app
187COPY . .
188
189# HTTP server on 3000
190EXPOSE 3000
191# Metrics on 9090
192EXPOSE 9090
193# WebSocket on 8080
194EXPOSE 8080
195
196CMD ["npm", "start"]
197```
198
199Gordon routes HTTP to port 3000.
200
201## Related
202
203- [Configuration Overview](../config/index.md)
204- [Attachments](../config/attachments.md)
205- [Concepts](../concepts.md)