Traefik SSL Configuration

Overview

Traefik provides automatic SSL termination, security headers, and reverse proxying for SPEAR deployments. It supports both Let’s Encrypt certificates for production and self-signed certificates for testing/internal use.

Architecture

┌─────────────────────────────────┐
│           Internet              │
└─────────────┬───────────────────┘
              │
┌─────────────▼───────────────────┐
│   Traefik (ports 80/443)        │
│   - SSL termination             │
│   - Security headers            │
│   - Request routing             │
└─────────────┬───────────────────┘
              │ http://localhost:8090
┌─────────────▼───────────────────┐
│   SPEAR Backend                 │
│   - PocketBase auth             │
│   - API endpoints               │
│   - Static file serving         │
└─────────────────────────────────┘

Integrated Installation (Recommended)

Install Traefik as part of the SPEAR deployment using the --with-traefik flag:

With Let’s Encrypt (Production)

sudo ./scripts/build-and-deploy.sh \
    --with-traefik \
    --domain example.com \
    --acme-email [email protected]

With Self-Signed Certificate (Testing/Internal)

sudo ./scripts/build-and-deploy.sh \
    --with-traefik \
    --domain example.com \
    --self-signed

This integrated approach:

Builds and deploys the SPEAR application
Downloads and installs Traefik binary
Generates configuration for your domain
Sets up SSL certificates
Creates and starts systemd services

Standalone Installation

To install Traefik separately from SPEAR:

cd scripts/traefik

# With Let's Encrypt SSL
sudo ./install.sh --domain example.com --email [email protected]

# With self-signed certificate
sudo ./install.sh --domain example.com --self-signed

# Custom backend URL
sudo ./install.sh --domain example.com --email [email protected] --backend-url http://localhost:8080

Installation Options

Option	Description
`-d, --domain DOMAIN`	Domain name for SSL certificate (required)
`-e, --email EMAIL`	Email for Let’s Encrypt (required unless —self-signed)
`-b, --backend-url URL`	Backend URL (default: http://localhost:8090)
`-s, --self-signed`	Use self-signed certificate
`-v, --version VERSION`	Traefik version (default: latest)
`--uninstall`	Remove Traefik installation

Uninstall

sudo ./install.sh --uninstall

File Structure

After installation, Traefik files are located at:

Path	Description
`/usr/local/bin/traefik`	Traefik binary
`/etc/traefik/traefik.yml`	Static configuration
`/etc/traefik/dynamic/`	Dynamic configuration files
`/var/lib/traefik/acme/`	Let’s Encrypt certificates
`/var/lib/traefik/certs/`	Self-signed certificates
`/var/log/traefik/`	Log files

Service Management

# Check status
sudo systemctl status traefik-spear

# View logs
sudo journalctl -u traefik-spear -f

# Restart
sudo systemctl restart traefik-spear

# Stop
sudo systemctl stop traefik-spear

# Start
sudo systemctl start traefik-spear

Configuration

Static Configuration

The static configuration (/etc/traefik/traefik.yml) defines:

Entry points (HTTP/HTTPS)
Let’s Encrypt or self-signed TLS
Logging settings
Metrics endpoints

Changes to static configuration require a service restart:

sudo systemctl restart traefik-spear

Dynamic Configuration

The dynamic configuration (/etc/traefik/dynamic/spear.yml) defines:

Routing rules for your domain
Backend service URL
Security headers and middleware
Large file upload support (500MB)

Changes to dynamic configuration are auto-loaded without restart.

Modifying Configuration

For dynamic config changes: Edit files in /etc/traefik/dynamic/ - changes are auto-loaded
For static config changes: Edit /etc/traefik/traefik.yml and restart:
Terminal window
```
sudo systemctl restart traefik-spear
```

Security Features

Traefik provides these security features out of the box:

Feature	Description
HTTPS Only	All HTTP traffic redirects to HTTPS
HSTS	HTTP Strict Transport Security enabled
Security Headers	XSS protection, frame options, content type sniffing prevention
CSP	Content Security Policy configured for SPEAR
Auto Renewal	Let’s Encrypt handles certificate renewal automatically

Access Points

After successful deployment:

Service	URL
SPEAR Application	`https://your-domain.com`
Health Check	`https://your-domain.com/api/health`

Log Locations

Log	Location
Traefik main log	`/var/log/traefik/traefik.log`
Access log	`/var/log/traefik/access.log`
Systemd journal	`journalctl -u traefik-spear`

Troubleshooting

Certificate Issues

# Check ACME logs
sudo journalctl -u traefik-spear | grep -i acme

# Verify certificate file
ls -la /var/lib/traefik/acme/acme.json

# Reset certificates (force renewal)
sudo rm /var/lib/traefik/acme/acme.json
sudo systemctl restart traefik-spear

Backend Unreachable

# Test backend directly
curl http://localhost:8090/api/health

# Check SPEAR service
sudo systemctl status spear

Port Conflicts

# Check what's using ports 80/443
sudo netstat -tlnp | grep -E ':80|:443'

# Or with ss
sudo ss -tlnp | grep -E ':80|:443'

DNS Issues

# Verify DNS resolution
nslookup your-domain.com
dig your-domain.com

SSL Certificate Verification

# Test SSL certificate
openssl s_client -connect your-domain.com:443 -servername your-domain.com

# Check certificate expiry
echo | openssl s_client -connect your-domain.com:443 2>/dev/null | openssl x509 -noout -dates

Validation

Run the validation script to check your installation:

cd scripts/traefik
./validate.sh

This checks:

Traefik binary installation
Configuration files
Service status
Port availability
Backend connectivity

Firewall Configuration

UFW (Ubuntu/Debian)

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

firewalld (RHEL/CentOS)

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Emergency Procedures

Disable Traefik (Direct Backend Access)

# Stop Traefik
sudo systemctl stop traefik-spear

# Access backend directly on port 8090
curl http://localhost:8090/api/health

Reset SSL Certificates

# For Let's Encrypt
sudo systemctl stop traefik-spear
sudo rm -f /var/lib/traefik/acme/acme.json
sudo systemctl start traefik-spear

# For self-signed
sudo systemctl stop traefik-spear
sudo rm -f /var/lib/traefik/certs/*.pem
# Re-run install.sh with --self-signed to regenerate

Complete Reinstall

# Uninstall
sudo ./install.sh --uninstall

# Reinstall
sudo ./install.sh --domain your-domain.com --email [email protected]

Updating Traefik

To update Traefik to a newer version:

# Stop service
sudo systemctl stop traefik-spear

# Reinstall with new version
sudo ./install.sh --domain your-domain.com --email [email protected] --version v3.1.0

# Verify
traefik version

Traefik Configuration After Deployment

After deployment with Traefik:

Item	Value
Domain	`https://your-domain.com`
Status Command	`sudo systemctl status traefik-spear`
Logs Command	`sudo journalctl -u traefik-spear -f`