home/Projects/kompose/docs/content/5.stacks/proxy.md

title, description, navigation

title	description	navigation
Proxy - The Traffic Cop of Your Infrastructure	Beep beep! Make way for HTTPS traffic!	icon i-lucide-traffic-cone

"Beep beep! Make way for HTTPS traffic!" - Traefik

What's This All About?

Traefik (pronounced "traffic") is your reverse proxy and load balancer extraordinaire! Think of it as the extremely organized doorman at a fancy hotel - it knows exactly where every guest (request) needs to go, handles their SSL certificates, redirects them when needed, and does it all with style!

The Traffic Master

:icon{name="lucide:target"} Traefik

Container: proxy_app
Image: traefik:latest
Ports: 80 (HTTP), 443 (HTTPS), 8080 (Dashboard)
Home: http://localhost:8080/dashboard/

Traefik is the Swiss Army knife of reverse proxies:

• :icon{name="lucide:lock"} Auto SSL: Let's Encrypt certificates automatically
• :icon{name="lucide:tag"} Service Discovery: Finds your containers via Docker labels
• :icon{name="lucide:refresh-cw"} Auto-Config: No config files to edit (mostly!)
• :icon{name="lucide:bar-chart"} Dashboard: Beautiful visual overview
• :icon{name="lucide:zap"} Fast: Written in Go for max performance
• :icon{name="lucide:plug"} Middleware: Compress, auth, rate limit, and more
• :icon{name="lucide:target"} Load Balancing: Distribute traffic intelligently

How It Works

Internet Request (https://yoursite.com)
    ↓
Traefik (Port 443)
    ├─ Checks Docker labels
    ├─ Finds matching service
    ├─ Terminates SSL
    ├─ Applies middleware
    └─ Forwards to container
        ↓
    Your Service (blog, auth, etc.)

Configuration Breakdown

Command Arguments

Let's decode the Traefik startup commands:

--api.dashboard=true              # Enable the fancy dashboard
--api.insecure=true              # Allow dashboard on :8080 (dev mode)
--log.level=DEBUG                # Verbose logging for troubleshooting
--global.sendAnonymousUsage=false # No telemetry (privacy!)
--global.checkNewVersion=true    # Check for updates
--providers.docker=true          # Watch Docker for services
--providers.docker.exposedbydefault=false  # Require explicit labels
--providers.docker.network=kompose         # Use kompose network
--entrypoints.web.address=:80             # HTTP on port 80
--entryPoints.web-secure.address=:443     # HTTPS on port 443
--certificatesresolvers.resolver.acme.tlschallenge=true  # SSL verification
--certificatesresolvers.resolver.acme.email=admin@example.com  # For Let's Encrypt
--certificatesresolvers.resolver.acme.storage=/letsencrypt/acme.json  # Cert storage

Entry Points

web (Port 80):

• Receives HTTP traffic
• Usually redirects to HTTPS

web-secure (Port 443):

• Handles HTTPS traffic
• Terminates SSL here
• Forwards decrypted traffic to services

Certificate Resolver

Let's Encrypt Integration:

• Automatic SSL certificates
• TLS challenge method
• Stores certs in /letsencrypt/acme.json
• Auto-renewal (60 days before expiry)

Dashboard Access :icon

Development/Testing

URL: http://localhost:8080/dashboard/

Features:

• :icon{name="lucide:clipboard"} All routers and services
• :icon{name="lucide:lock"} Active certificates
• :icon{name="lucide:globe"} Entry points status
• :icon{name="lucide:bar-chart"} Real-time metrics
• :icon{name="lucide:search"} Request logs

Production (Secure It!)

Add authentication to dashboard:

labels:
  - "traefik.http.routers.dashboard.middlewares=auth"
  - "traefik.http.middlewares.auth.basicauth.users=admin:$$apr1$$password"

Generate password hash:

htpasswd -nb admin your_password

Label-Based Configuration :icon

Every service in kompose uses Traefik labels. Here's what they mean:

Basic Labels

labels:
  - 'traefik.enable=true'  # "Hey Traefik, route me!"
  - 'traefik.http.routers.myapp-web.rule=Host(`app.example.com`)'  # Domain routing
  - 'traefik.http.routers.myapp-web.entrypoints=web'  # Use HTTP
  - 'traefik.http.services.myapp.loadbalancer.server.port=8080'  # Internal port

HTTPS Setup

- 'traefik.http.routers.myapp-web-secure.rule=Host(`app.example.com`)'
- 'traefik.http.routers.myapp-web-secure.entrypoints=web-secure'  # HTTPS
- 'traefik.http.routers.myapp-web-secure.tls.certresolver=resolver'  # Auto SSL

HTTP → HTTPS Redirect

- 'traefik.http.middlewares.myapp-redirect.redirectscheme.scheme=https'
- 'traefik.http.routers.myapp-web.middlewares=myapp-redirect'

Compression

- 'traefik.http.middlewares.myapp-compress.compress=true'
- 'traefik.http.routers.myapp-web-secure.middlewares=myapp-compress'

Ports & Networking

Port	Purpose	Access
80	HTTP Traffic	Public
443	HTTPS Traffic	Public
8080	Dashboard	Local only (for now)

Network: kompose - must be created before starting:

docker network create kompose

SSL Certificate Management :icon

Let's Encrypt Process

1. Service starts with Traefik labels
2. Traefik detects it needs SSL
3. Requests certificate from Let's Encrypt
4. TLS challenge runs (Traefik proves domain ownership)
5. Certificate issued (valid 90 days)
6. Auto-renewal happens at 60 days

Certificate Storage

/var/local/data/traefik/letsencrypt/acme.json

:icon{name="lucide:alert-triangle"} PROTECT THIS FILE!

• Contains private keys
• Encrypted by Traefik
• Backup regularly
• Permissions: 600

View Certificates

# In dashboard
http://localhost:8080/dashboard/#/http/routers

# Or check file
sudo cat /var/local/data/traefik/letsencrypt/acme.json | jq '.resolver.Certificates'

Common Middleware :icon

Rate Limiting

- "traefik.http.middlewares.ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.ratelimit.ratelimit.burst=50"

IP Whitelist

- "traefik.http.middlewares.ipwhitelist.ipwhitelist.sourcerange=192.168.1.0/24"

CORS Headers

- "traefik.http.middlewares.cors.headers.accesscontrolallowmethods=GET,POST,PUT"
- "traefik.http.middlewares.cors.headers.accesscontrolalloworigin=*"

Basic Auth

- "traefik.http.middlewares.auth.basicauth.users=user:$$apr1$$password"

Strip Prefix

- "traefik.http.middlewares.stripprefix.stripprefix.prefixes=/api"

Health Check :icon

Traefik has a built-in health check:

traefik healthcheck --ping

Runs every 30 seconds. If it fails 3 times, Docker restarts the container.

Monitoring & Debugging

Real-Time Logs

docker logs proxy_app -f

Access Logs (Enable in config)

--accesslog=true
--accesslog.filepath=/var/log/traefik/access.log

Metrics (Prometheus)

--metrics.prometheus=true
--metrics.prometheus.buckets=0.1,0.3,1.2,5.0

Adding a New Service

1. Create compose file with labels:

   services:
     myapp:
       image: nginx
       networks:
         - kompose
       labels:
         - 'traefik.enable=true'
         - 'traefik.http.routers.myapp.rule=Host(`myapp.example.com`)'
         - 'traefik.http.routers.myapp.entrypoints=web-secure'
         - 'traefik.http.routers.myapp.tls.certresolver=resolver'
   

2. Start the service:

   docker compose up -d
   

3. Traefik auto-detects it!

4. Check dashboard to confirm routing

Troubleshooting :icon

Q: Service not accessible?

# Check if Traefik sees it
docker logs proxy_app | grep your-service

# Verify labels
docker inspect your-container | grep traefik

Q: SSL certificate not working?

• Check domain DNS points to server
• Verify port 80/443 are open
• Check Let's Encrypt rate limits
• Look for errors in logs

Q: "Gateway Timeout" errors?

• Service might be slow to respond
• Check service health
• Increase timeout in labels:

  - "traefik.http.services.myapp.loadbalancer.healthcheck.timeout=10s"
  

Q: HTTP not redirecting to HTTPS?

• Verify redirect middleware is applied
• Check router configuration
• Look for middleware typos

Q: Certificate renewal failing?

# Check renewal logs
docker logs proxy_app | grep -i "renew\|certificate"

# Ensure ports are accessible
curl -I http://yourdomain.com/.well-known/acme-challenge/test

Advanced Configuration

Multiple Domains

- 'traefik.http.routers.myapp.rule=Host(`app1.com`) || Host(`app2.com`)'

Path-Based Routing

- 'traefik.http.routers.api.rule=Host(`example.com`) && PathPrefix(`/api`)'
- 'traefik.http.routers.web.rule=Host(`example.com`) && PathPrefix(`/`)'

Weighted Load Balancing

services:
  app-v1:
    labels:
      - "traefik.http.services.myapp.loadbalancer.server.weight=90"
  app-v2:
    labels:
      - "traefik.http.services.myapp.loadbalancer.server.weight=10"

Security Best Practices :icon

1. Secure Dashboard:

   • Add authentication
   • Or disable in production: --api.dashboard=false

2. HTTPS Only:

   • Always redirect HTTP → HTTPS
   • Use HSTS headers

3. Regular Updates:

   docker compose pull
   docker compose up -d
   

4. Backup Certificates:

   cp /var/local/data/traefik/letsencrypt/acme.json ~/backups/
   

5. Monitor Logs:

   • Watch for unusual patterns
   • Set up alerts for errors

Performance Tips :icon

1. Enable Compression: Already done for most services!
2. HTTP/2: Automatically enabled with HTTPS
3. Connection Pooling: Traefik handles it
4. Caching: Use middleware or CDN
5. Keep-Alive: Enabled by default

Fun Traefik Facts :icon

• Written in Go (blazing fast!)
• Powers thousands of production systems
• Open source since 2015
• Cloud-native from the ground up
• Originally created for microservices
• Supports Docker, Kubernetes, Consul, and more

Resources

• Traefik Documentation
• Let's Encrypt
• Traefik Plugins

---

"Life is like a reverse proxy - it's all about routing requests to the right destination." - Ancient Traefik Wisdom :icon{name="lucide:traffic-cone"}:icon{name="lucide:sparkles"}