traefik/README.md

# Traefik Reverse Proxy Configuration

This directory contains the Traefik reverse proxy configuration for managing SSL certificates and routing traffic to services.

## Services Managed

- **Mealie** (recipes.pkartchner.com) - Recipe manager
- **Gogs** (git.pkartchner.com) - Git repository server
- **Traefik Dashboard** (traefik.pkartchner.com) - Traefik management UI

## Features

- ✅ Automatic HTTPS with Let's Encrypt SSL certificates
- ✅ Automatic HTTP to HTTPS redirect
- ✅ Docker service discovery
- ✅ Security headers middleware
- ✅ Traefik dashboard with basic auth

## Files

- `docker-compose.yml` - Traefik container configuration
- `traefik.yml` - Main Traefik configuration
- `config.yml` - Dynamic configuration for external services
- `acme.json` - Let's Encrypt certificate storage (auto-generated)

## Setup

### 1. DNS Configuration

Ensure these DNS records point to your server's public IP:

```
A    recipes.pkartchner.com    →  YOUR_PUBLIC_IP
A    git.pkartchner.com        →  YOUR_PUBLIC_IP
A    traefik.pkartchner.com    →  YOUR_PUBLIC_IP
```

### 2. Start Traefik

```bash
cd /srv/docker-compose/traefik
docker compose up -d
```

### 3. Check Logs

```bash
docker logs traefik -f
```

## Dashboard Access

Access the Traefik dashboard at: `https://traefik.pkartchner.com`

**Default credentials:**
- Username: `admin`
- Password: `change-this-password`

**Change the password:**
```bash
# Generate new password hash
echo $(htpasswd -nb admin yournewpassword) | sed -e s/\\$/\\$\\$/g

# Update the label in docker-compose.yml:
# traefik.http.middlewares.traefik-auth.basicauth.users=admin:$HASH
```

## SSL Certificates

Traefik automatically obtains and renews SSL certificates from Let's Encrypt.

- Certificates are stored in `acme.json`
- Auto-renewal happens 30 days before expiration
- Email notifications sent to: pkartch@gmail.com

### Staging vs Production

The configuration uses **Let's Encrypt production** by default.

To use **staging** (for testing, to avoid rate limits):
Uncomment this line in `traefik.yml`:
```yaml
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
```

## Port Configuration

- **80** - HTTP (redirects to HTTPS)
- **443** - HTTPS (main entry point)
- **8080** - Traefik dashboard

## Adding New Services

### Docker Services

Add labels to your service's docker-compose.yml:

```yaml
services:
  myservice:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myservice.rule=Host(`myservice.pkartchner.com`)"
      - "traefik.http.routers.myservice.entrypoints=https"
      - "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
      - "traefik.http.services.myservice.loadbalancer.server.port=PORT"
    networks:
      - traefik
```

### External Services

Add to `config.yml`:

```yaml
http:
  routers:
    myservice:
      rule: "Host(`myservice.pkartchner.com`)"
      entryPoints:
        - https
      service: myservice
      tls:
        certResolver: letsencrypt

  services:
    myservice:
      loadBalancer:
        servers:
          - url: "http://INTERNAL_IP:PORT"
```

## Troubleshooting

### Check Traefik logs
```bash
docker logs traefik --tail 100
```

### Verify network
```bash
docker network ls | grep traefik
```

### Test certificate
```bash
openssl s_client -connect recipes.pkartchner.com:443 -servername recipes.pkartchner.com
```

### Reload configuration
```bash
docker compose restart traefik
```

## Security Notes

- Change the default dashboard password immediately
- Keep `acme.json` permissions at 600
- Regularly update Traefik image
- Monitor access logs
- Consider disabling the dashboard in production

## Maintenance

### Update Traefik
```bash
docker compose pull
docker compose up -d
```

### Backup certificates
```bash
cp acme.json acme.json.backup
```

### View certificate info
Check the Traefik dashboard under "HTTP" → "Routers"