1# Docker Labels Reference
2
3Labels used by Gordon for container and image metadata.
4
5## Container Labels
6
7Gordon stamps these ownership labels on every container it creates:
8
9| Label | Value | Description |
10|-------|-------|-------------|
11| `gordon.managed` | `"true"` | Identifies Gordon-managed containers |
12| `gordon.app` | App name | App this container serves |
13| `gordon.app.service` | Service name | Service this container runs |
14| `gordon.app.revision` | Revision | Active revision that created it |
15| `gordon.created` | Timestamp | When Gordon created the container |
16
17Queries by logical identity use labels, never name parsing. Resources without these labels (old or foreign containers) are preserved, never adopted or deleted.
18
19### Legacy Labels
20
21Containers created before v3 may carry these labels. They are read-only provenance hints for prune guards — Gordon never infers app state from them:
22
23| Label | Value | Description |
24|-------|-------|-------------|
25| `gordon.domain` | Domain name | Pre-v3 domain this container served |
26| `gordon.image` | Image:tag | Original image from configuration |
27| `gordon.route` | Domain name | Pre-v3 route this container handled |
28
29### Backup Metadata
30
31Backups are declarative rather than label-driven. App manifests declare database and volume targets in `[services.<name>.backup]`; Gordon does not define or write Docker labels to enable backups, select database types or schedules, or identify backup sidecars.
32
33## Image Labels
34
35No image-label inference exists in v3: Gordon never creates routes, deploys, or resolves image names from Dockerfile labels. Push with a domain-like name or a `gordon.domain` label is treated as an ordinary image name. Readiness and proxy ports come from the app manifest (`[services.<name>.readiness]`, `[[services.<name>.http]]`), not from image labels.
36
37## Container Naming
38
39Gordon names containers `gordon-<app>--<service>--<instance>` where `<instance>` is the creating operation ID. Retiring containers keep their instance names until removal.
40
41## Inspecting Labels
42
43View labels on a container:
44
45```bash
46docker inspect <container> --format '{{json .Config.Labels}}' | jq
47```
48
49Example output:
50
51```json
52{
53  "gordon.managed": "true",
54  "gordon.app": "blog",
55  "gordon.app.service": "web",
56  "gordon.app.revision": "rev-3",
57  "gordon.created": "2024-01-15T10:30:00Z"
58}
59```
60
61## Filtering Containers
62
63Find Gordon-managed containers:
64
65```bash
66# All Gordon containers
67docker ps -f "label=gordon.managed=true"
68
69# Containers for a specific app
70docker ps -f "label=gordon.app=blog"
71```
72
73## Related
74
75- [Configuration Overview](../config/index.md)
76- [App Manifest](../config/apps.md)
77- [Concepts](../concepts.md)