Auto Route Configuration
Gordon supports two methods for automatic route creation:
- Image Name Detection - Routes from domain-like image names
- Image Labels - Routes from Dockerfile labels (recommended)
Configuration
[auto_route]
enabled = true
Options
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Enable automatic route creation |
How It Works
When auto-route is enabled, Gordon automatically creates routes for images with domain-like names:
# Push an image with a domain name
docker push registry.mydomain.com/app.example.com:latest
Gordon automatically:
- Detects
app.example.comlooks like a domain - Creates a route:
app.example.com→app.example.com:latest - Deploys the container
- Routes traffic to it
Domain Detection
Gordon recognizes image names as domains when they:
- Contain at least one dot (
.) - Don't start or end with a dot
- Look like valid hostnames
| Image Name | Detected as Domain? |
|---|---|
app.example.com |
Yes |
myapp.dev |
Yes |
staging.api.io |
Yes |
myapp |
No (no dots) |
.invalid |
No (starts with dot) |
myapp. |
No (ends with dot) |
Use Cases
Simplified Deployment
Without auto-route:
# Must define each route in config
[routes]
"app.example.com" = "app.example.com:latest"
With auto-route:
[auto_route]
enabled = true
# No routes needed - just push!
docker push registry.mydomain.com/app.example.com:latest
# Route automatically created
Development Workflow
# Create a new app instantly
docker build -t myapp .
docker tag myapp registry.mydomain.com/newapp.mydomain.com:latest
docker push registry.mydomain.com/newapp.mydomain.com:latest
# newapp.mydomain.com is now live!
Multi-Tenant SaaS
# Quickly provision customer subdomains
docker push registry.mydomain.com/acme.saas.com:latest
docker push registry.mydomain.com/beta.saas.com:latest
docker push registry.mydomain.com/gamma.saas.com:latest
Combining with Manual Routes
Auto-route works alongside manual routes:
[auto_route]
enabled = true
[routes]
# Pinned versions override auto-route
"api.mydomain.com" = "myapi:v2.1.0"
api.mydomain.comuses the manually configuredmyapi:v2.1.0- Other domain-named images create automatic routes
Priority Order
- Manual routes in
[routes]take precedence - Auto-routes are created for domain-named images without manual routes
Examples
Enable Auto-Route
[auto_route]
enabled = true
Development with Auto-Route
[server]
gordon_domain = "gordon.local"
[auto_route]
enabled = true
# No routes defined - all come from image names
Usage:
docker push gordon.local/myapp.local:latest
docker push gordon.local/api.local:latest
# Both routes created automatically
Production with Auto-Route
[auto_route]
enabled = true
[routes]
# Critical services with pinned versions
"api.company.com" = "company-api:v2.1.0"
"app.company.com" = "company-app:v1.5.0"
# Other services can use auto-route
Limitations (Image Name Detection)
- Auto-routes always use the pushed image tag
- No support for HTTP-only routes (all HTTPS)
- No automatic attachment configuration
- Cannot pin versions (always uses pushed tag)
For more control, define routes manually in [routes] or use image labels.
Image Labels (Recommended)
The preferred method for automatic routing uses Dockerfile labels. This gives you full control over routing behavior directly in your application.
Supported Labels
| Label | Description | Example |
|---|---|---|
gordon.domains |
Comma-separated list of domains | app.example.com,www.app.example.com |
gordon.port |
Container port to proxy | 3000 |
gordon.health |
Health check endpoint path | /health |
gordon.env-file |
Path to .env file in image | /app/.env.example |
Dockerfile Example
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
# Gordon routing labels
LABEL gordon.domains="myapp.example.com,www.myapp.example.com"
LABEL gordon.port="3000"
LABEL gordon.health="/api/health"
LABEL gordon.env-file="/app/.env.example"
EXPOSE 3000
CMD ["npm", "start"]
How It Works
When you push an image with Gordon labels:
- Gordon reads the
gordon.domainslabel - Creates routes for each domain automatically
- Uses
gordon.portfor the proxy target (or first EXPOSE port) - Configures health checks if
gordon.healthis set - Extracts environment variables from
gordon.env-fileif specified
Label Priority
Labels take precedence over image name detection:
- Labels present → Use
gordon.domainsfor routing - No labels → Fall back to image name detection (if enabled)
- Manual routes → Always take highest priority
Multi-Domain Example
# Single image serving multiple domains
LABEL gordon.domains="api.example.com,api.staging.example.com"
Both domains will route to the same container.
Environment File Extraction
The gordon.env-file label tells Gordon where to find a template .env file:
# Include a .env.example in your image
COPY .env.example /app/.env.example
LABEL gordon.env-file="/app/.env.example"
Gordon will:
- Extract the file from the image
- Store it in the env directory
- Use the variables for container deployment
Best Practices
- Always set
gordon.port- Don't rely on EXPOSE detection - Use
gordon.health- Enables reliable deployment verification - Include
.env.example- Self-documenting environment requirements - Separate domains with commas - No spaces around commas
Example: Complete Setup
FROM golang:1.25-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o server
FROM alpine:3.21
WORKDIR /app
COPY --from=builder /app/server .
COPY .env.example .
# Gordon labels
LABEL gordon.domains="api.mycompany.com"
LABEL gordon.port="8080"
LABEL gordon.health="/health"
LABEL gordon.env-file="/app/.env.example"
EXPOSE 8080
CMD ["./server"]
# Push and Gordon handles everything
docker push registry.mycompany.com/api:latest
# Route automatically created: api.mycompany.com → container:8080