Docker Labels Reference
Labels used by Gordon for container and image metadata.
Container Labels
Gordon adds these labels to managed containers:
| Label |
Value |
Description |
gordon.managed |
"true" |
Identifies Gordon-managed containers |
gordon.domain |
Domain name |
Domain this container serves |
gordon.image |
Image:tag |
Original image from configuration |
gordon.route |
Domain name |
Route this container handles |
gordon.created |
Timestamp |
When Gordon created the container |
Attachment Labels
Additional labels for attachment containers:
| Label |
Value |
Description |
gordon.attachment |
"true" |
Container is an attachment service |
gordon.attached-to |
Domain/group |
Route or network group this serves |
Backup Labels
Labels used by the backup subsystem:
| Label |
Value |
Description |
gordon.backup |
"true" / "false" |
Enables or disables backup behavior for a container |
gordon.backup.type |
e.g. "postgresql" |
Explicit database type override |
gordon.backup.version |
e.g. "17" |
Explicit database version override |
gordon.backup.schedule |
e.g. "hourly,daily" |
Schedule override hint |
gordon.backup.sidecar |
"true" |
Identifies backup sidecar containers |
Image Labels
Labels you can set in your Dockerfile:
| Label |
Example |
Description |
gordon.proxy.port |
"3000" |
Port to proxy HTTP traffic to |
Proxy Port Label
When an image exposes multiple ports, Gordon needs to know which one serves HTTP:
# Gitea exposes SSH (22) and HTTP (3000)
FROM gitea/gitea:latest
LABEL gordon.proxy.port=3000
EXPOSE 22
EXPOSE 3000
Without this label, Gordon uses the first exposed port.
When to use:
- Image exposes multiple ports
- First exposed port isn't the HTTP service
- You want explicit control over routing
Container Naming
Gordon names containers:
| Pattern |
Example |
gordon-{domain} |
gordon-app-mydomain-com |
gordon-{domain}-new |
gordon-app-mydomain-com-new (during updates) |
gordon-{domain}-{service} |
gordon-app-mydomain-com-postgres (attachments) |
Inspecting Labels
View labels on a container:
docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}' | jq
Example output:
{
"gordon.created": "2024-01-15T10:30:00Z",
"gordon.domain": "app.mydomain.com",
"gordon.image": "myapp:latest",
"gordon.managed": "true",
"gordon.route": "app.mydomain.com"
}
Filtering Containers
Find Gordon-managed containers:
# All Gordon containers
docker ps -f "label=gordon.managed=true"
# Containers for specific domain
docker ps -f "label=gordon.domain=app.mydomain.com"
# Attachment containers
docker ps -f "label=gordon.attachment=true"
# Attachments for specific route
docker ps -f "label=gordon.attached-to=app.mydomain.com"
# Backup sidecars
docker ps -f "label=gordon.backup.sidecar=true"
Examples
Standard Application Container
docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}'
{
"gordon.managed": "true",
"gordon.domain": "app.mydomain.com",
"gordon.image": "myapp:v2.1.0",
"gordon.route": "app.mydomain.com",
"gordon.created": "2024-01-15T10:30:00Z"
}
Attachment Container
docker inspect gordon-app-mydomain-com-postgres --format '{{json .Config.Labels}}'
{
"gordon.managed": "true",
"gordon.attachment": "true",
"gordon.attached-to": "app.mydomain.com",
"gordon.created": "2024-01-15T10:29:00Z"
}
Multi-Port Dockerfile
FROM node:18
LABEL gordon.proxy.port=3000
WORKDIR /app
COPY . .
# HTTP server on 3000
EXPOSE 3000
# Metrics on 9090
EXPOSE 9090
# WebSocket on 8080
EXPOSE 8080
CMD ["npm", "start"]
Gordon routes HTTP to port 3000.
source
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### Attachment Labels
18
19Additional labels for attachment containers:
20
21| Label | Value | Description |
22|-------|-------|-------------|
23| `gordon.attachment` | `"true"` | Container is an attachment service |
24| `gordon.attached-to` | Domain/group | Route or network group this serves |
25
26### Backup Labels
27
28Labels used by the backup subsystem:
29
30| Label | Value | Description |
31|-------|-------|-------------|
32| `gordon.backup` | `"true"` / `"false"` | Enables or disables backup behavior for a container |
33| `gordon.backup.type` | e.g. `"postgresql"` | Explicit database type override |
34| `gordon.backup.version` | e.g. `"17"` | Explicit database version override |
35| `gordon.backup.schedule` | e.g. `"hourly,daily"` | Schedule override hint |
36| `gordon.backup.sidecar` | `"true"` | Identifies backup sidecar containers |
37
38## Image Labels
39
40Labels you can set in your Dockerfile:
41
42| Label | Example | Description |
43|-------|---------|-------------|
44| `gordon.proxy.port` | `"3000"` | Port to proxy HTTP traffic to |
45
46### Proxy Port Label
47
48When an image exposes multiple ports, Gordon needs to know which one serves HTTP:
49
50```dockerfile
51# Gitea exposes SSH (22) and HTTP (3000)
52FROM gitea/gitea:latest
53LABEL gordon.proxy.port=3000
54EXPOSE 22
55EXPOSE 3000
56```
57
58Without this label, Gordon uses the first exposed port.
59
60**When to use:**
61- Image exposes multiple ports
62- First exposed port isn't the HTTP service
63- You want explicit control over routing
64
65## Container Naming
66
67Gordon names containers:
68
69| Pattern | Example |
70|---------|---------|
71| `gordon-{domain}` | `gordon-app-mydomain-com` |
72| `gordon-{domain}-new` | `gordon-app-mydomain-com-new` (during updates) |
73| `gordon-{domain}-{service}` | `gordon-app-mydomain-com-postgres` (attachments) |
74
75## Inspecting Labels
76
77View labels on a container:
78
79```bash
80docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}' | jq
81```
82
83Example output:
84
85```json
86{
87 "gordon.created": "2024-01-15T10:30:00Z",
88 "gordon.domain": "app.mydomain.com",
89 "gordon.image": "myapp:latest",
90 "gordon.managed": "true",
91 "gordon.route": "app.mydomain.com"
92}
93```
94
95## Filtering Containers
96
97Find Gordon-managed containers:
98
99```bash
100# All Gordon containers
101docker ps -f "label=gordon.managed=true"
102
103# Containers for specific domain
104docker ps -f "label=gordon.domain=app.mydomain.com"
105
106# Attachment containers
107docker ps -f "label=gordon.attachment=true"
108
109# Attachments for specific route
110docker ps -f "label=gordon.attached-to=app.mydomain.com"
111
112# Backup sidecars
113docker ps -f "label=gordon.backup.sidecar=true"
114```
115
116## Examples
117
118### Standard Application Container
119
120```bash
121docker inspect gordon-app-mydomain-com --format '{{json .Config.Labels}}'
122```
123
124```json
125{
126 "gordon.managed": "true",
127 "gordon.domain": "app.mydomain.com",
128 "gordon.image": "myapp:v2.1.0",
129 "gordon.route": "app.mydomain.com",
130 "gordon.created": "2024-01-15T10:30:00Z"
131}
132```
133
134### Attachment Container
135
136```bash
137docker inspect gordon-app-mydomain-com-postgres --format '{{json .Config.Labels}}'
138```
139
140```json
141{
142 "gordon.managed": "true",
143 "gordon.attachment": "true",
144 "gordon.attached-to": "app.mydomain.com",
145 "gordon.created": "2024-01-15T10:29:00Z"
146}
147```
148
149### Multi-Port Dockerfile
150
151```dockerfile
152FROM node:18
153LABEL gordon.proxy.port=3000
154
155WORKDIR /app
156COPY . .
157
158# HTTP server on 3000
159EXPOSE 3000
160# Metrics on 9090
161EXPOSE 9090
162# WebSocket on 8080
163EXPOSE 8080
164
165CMD ["npm", "start"]
166```
167
168Gordon routes HTTP to port 3000.
169
170## Related
171
172- [Configuration Overview](../config/index.md)
173- [Attachments](../config/attachments.md)
174- [Concepts](../concepts.md)