Auto Route Configuration

Gordon supports two methods for automatic route creation:

1. Image Name Detection - Routes from domain-like image names
2. Image Labels - Routes from Dockerfile labels (recommended)

Configuration

[auto_route]
enabled = true

Options

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:

1. Detects app.example.com looks like a domain
2. Creates a route: app.example.com → app.example.com:latest
3. Deploys the container
4. 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

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.com uses the manually configured myapi:v2.1.0
• Other domain-named images create automatic routes

Priority Order

1. Manual routes in [routes] take precedence
2. 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

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.proxy.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:

1. Gordon reads the gordon.domains label
2. Creates routes for each domain automatically
3. Uses gordon.proxy.port for the proxy target, otherwise auto-detects an exposed port preferring common HTTP ports
4. Configures health checks if gordon.health is set
5. Extracts environment variables from gordon.env-file if specified

Label Priority

Labels take precedence over image name detection:

1. Labels present → Use gordon.domains for routing
2. No labels → Fall back to image name detection (if enabled)
3. 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:

1. Extract the file from the image
2. Store it in the env directory
3. Use the variables for container deployment

Best Practices

1. Always set gordon.proxy.port - Don't rely on EXPOSE detection
2. Use gordon.health - Enables reliable deployment verification
3. Include .env.example - Self-documenting environment requirements
4. 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.proxy.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

Related

• Routes
• Configuration Overview