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