Gordon v2 Configuration Examples
This directory contains configuration examples for different use cases and environments.
📁 Available Examples
🚀 minimal.toml
Perfect for getting started
- Single route configuration
- Default settings
- No authentication
- Ideal for testing and learning
🏠 development.toml
Local development setup
- Multiple .local domains
- No authentication for ease of use
- Third-party development tools
- localhost registry
🧪 staging.toml
Staging and preview environments
- Branch-based deployments
- Feature branch testing
- PR preview environments
- Separate staging registry
🏭 production.toml
Production-ready configuration
- Pinned image versions
- Registry authentication
- Multiple production services
- Monitoring tools included
🏢 saas-multi-tenant.toml
Multi-tenant SaaS platform
- Customer subdomains
- Custom domains
- Shared application architecture
- Enterprise features
📊 logging.toml
Comprehensive logging configuration
- Complete logging setup examples
- Different logging levels and configurations
- Production and development logging strategies
- Log rotation and monitoring examples
🔄 rollback-workflow-example.md
Simple version deployment and rollback workflow
- Manifest annotation-based deployments
- Simple version changes for deployments and rollbacks
- Version tracking and deployment strategies
🚀 Quick Start
- Choose an example that matches your use case
- Copy the config file to your Gordon directory:
cp examples/minimal.toml gordon.toml - Edit the configuration with your domains and settings
- Start Gordon:
gordon start
🔧 Customization Tips
Domain Configuration
Update the [routes] section with your actual domains:
[routes]
"your-domain.com" = "your-app:latest"
"api.your-domain.com" = "your-api:v1.0.0"
Registry Setup
Configure your registry domain and authentication:
[server]
registry_domain = "registry.your-domain.com"
[registry_auth]
enabled = true
username = "your-username"
password = "your-secure-password"
Container Runtime Setup
Gordon supports Docker and Podman with automatic detection:
[server]
runtime = "auto" # auto, docker, podman, podman-rootless
socket_path = "" # optional custom socket path
# Examples:
# runtime = "docker" # Force Docker
# runtime = "podman" # Force Podman root
# runtime = "podman-rootless" # Force Podman rootless
# socket_path = "unix:///run/user/1000/podman/podman.sock"
Override with environment variables:
# Works for both Docker and Podman
export CONTAINER_HOST=unix:///custom/path/container.sock
export CONTAINER_HOST=tcp://remote-docker:2376
gordon start
Logging Configuration
Enable comprehensive logging to monitor your deployments:
[logging]
enabled = true # Enable file-based logging
level = "info" # Log level: trace, debug, info, warn, error
dir = "./logs" # Directory for log files
main_log_file = "gordon.log" # Main application logs
proxy_log_file = "proxy.log" # HTTP proxy traffic logs
container_log_dir = "containers" # Container logs subdirectory
# Log rotation settings
max_size = 100 # Max log file size in MB
max_backups = 5 # Number of old log files to keep
max_age = 30 # Max age in days
compress = true # Compress old log files
See logging.toml for comprehensive logging examples.
Environment Variables
Gordon intelligently merges environment variables from multiple sources:
- Dockerfile ENV directives (automatically detected)
- Your .env files (override Dockerfile ENV)
- Runtime environment (lowest priority)
Dockerfile ENV (Automatic Detection)
FROM node:18-alpine
WORKDIR /app
# Gordon automatically reads these ENV directives
ENV NODE_ENV=production
ENV PORT=3000
ENV LOG_LEVEL=info
ENV DATABASE_HOST=localhost
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
Custom Environment Files
Create .env files for each route: ./data/env/app_yourdomain_com.env
# Your custom overrides (these take precedence over Dockerfile ENV)
DATABASE_HOST=db.mydomain.com
DATABASE_USER=myapp
DATABASE_PASSWORD=${pass:myapp/db-password}
API_KEY=${sops:secrets.yaml:api_key}
# NODE_ENV, PORT, LOG_LEVEL from Dockerfile are preserved
Final Applied Environment
NODE_ENV=production # From Dockerfile ENV
PORT=3000 # From Dockerfile ENV
LOG_LEVEL=info # From Dockerfile ENV
DATABASE_HOST=db.mydomain.com # From .env (overridden)
DATABASE_USER=myapp # From .env (new)
DATABASE_PASSWORD=secret123 # From .env via pass
API_KEY=abc123 # From .env via SOPS
Production Environment Variables
For sensitive production data:
export GORDON_REGISTRY_PASSWORD="your-secure-password"
export GORDON_SSL_EMAIL="admin@your-domain.com"
Volume Management
Gordon automatically creates persistent volumes from Dockerfile VOLUME directives:
Dockerfile VOLUME (Automatic Detection)
FROM postgres:15
# Gordon automatically creates persistent volumes for these paths
VOLUME ["/var/lib/postgresql/data"]
# Multi-volume example
FROM myapp:latest
VOLUME ["/app/data", "/app/logs", "/app/uploads"]
Volume Features
- Zero Configuration: Reads VOLUME directives automatically
- Persistent Storage: Data survives container restarts and updates
- Predictable Naming:
gordon-{domain}-{path-hash}format - Cross-Platform: Works with Docker and Podman
Volume Configuration (Optional)
[volumes]
auto_create = true # Default: true (automatically handle VOLUME directives)
prefix = "gordon" # Default: "gordon" (volume name prefix)
preserve = true # Default: true (keep volumes when containers are removed)
Complete Dockerfile Example
FROM node:18-alpine
WORKDIR /app
# Environment variables (automatically merged with your .env files)
ENV NODE_ENV=production
ENV PORT=3000
ENV LOG_LEVEL=info
# Install dependencies
COPY package*.json ./
RUN npm install
# Copy application code
COPY . .
# Persistent storage (automatically managed by Gordon)
VOLUME ["/app/data", "/app/logs"]
# Network configuration
EXPOSE 3000
# Start command
CMD ["npm", "start"]
When you deploy this image:
- Gordon reads ENV directives and merges with your .env files
- Gordon creates volumes for
/app/dataand/app/logs - Your data persists across deployments and reboots
- Environment variables are intelligently managed
🌐 DNS Configuration
Cloudflare Setup (Recommended)
For all examples except development, set up these DNS records:
Type Name Content
A app.your-domain.com YOUR_SERVER_IP
A api.your-domain.com YOUR_SERVER_IP
A registry.your-domain.com YOUR_SERVER_IP
Or use a wildcard:
Type Name Content
A *.your-domain.com YOUR_SERVER_IP
Local Development
For the development example, add to /etc/hosts:
127.0.0.1 app.local
127.0.0.1 api.local
127.0.0.1 admin.local
🔄 Workflow Examples
Simple Deployment
# Build your app
export VERSION=latest
docker build --tag myapp:$VERSION --tag registry.your-domain.com/myapp:$VERSION .
# Push to deploy
docker push registry.your-domain.com/myapp:$VERSION
Version Management
# Build and push specific version
export VERSION=v1.2.0
docker build --tag myapp:$VERSION --tag registry.your-domain.com/myapp:$VERSION .
docker push registry.your-domain.com/myapp:$VERSION
# Update config
# "app.your-domain.com" = "myapp:v1.2.0"
Simple Version Deployment with Manifest Annotations
# Build and push your versions first
export VERSION=v1.1.0
podman build --tag myapp:$VERSION --tag registry.your-domain.com/myapp:$VERSION .
podman push registry.your-domain.com/myapp:$VERSION
export VERSION=v1.2.0
podman build --tag myapp:$VERSION --tag registry.your-domain.com/myapp:$VERSION .
podman push registry.your-domain.com/myapp:$VERSION
# Deploy v1.2.0
export VERSION=v1.2.0
podman manifest create myapp:latest
podman manifest add myapp:latest registry.your-domain.com/myapp:$VERSION
podman manifest annotate myapp:latest --annotation version=$VERSION registry.your-domain.com/myapp:$VERSION
podman manifest push myapp:latest registry.your-domain.com/myapp:latest
# Rollback to v1.1.0 (just change the version)
export VERSION=v1.1.0
podman manifest create myapp:latest --amend
podman manifest add myapp:latest registry.your-domain.com/myapp:$VERSION
podman manifest annotate myapp:latest --annotation version=$VERSION registry.your-domain.com/myapp:$VERSION
podman manifest push myapp:latest registry.your-domain.com/myapp:latest
See rollback-workflow-example.md for complete version deployment workflow documentation.
🤝 Need Help?
- 📖 Read the main README for detailed documentation
- 🔍 Check the logs for deployment issues
- 🐛 Open an issue if you find problems with these examples
- 💡 Contribute your own configuration examples!
These examples are starting points - customize them for your specific needs!