SSL / TLS Configuration

SSL Options

SPEAR supports three SSL modes:

Mode	Description	Best For
Custom Certificate	SPEAR serves HTTPS directly using your own cert	Cloudflare Origin, DigiCert, purchased certs
Let’s Encrypt	PocketBase handles SSL via autocert	Public-facing servers with port 80/443
Traefik	Reverse proxy handles SSL termination	Complex deployments, multiple services

Custom SSL Certificates

Use your own purchased or generated SSL certificate (e.g., Cloudflare Origin Certificate, DigiCert, etc.) without needing a reverse proxy. SPEAR encrypts the certificate and private key in the database using AES-GCM.

CLI Installation

sudo ./scripts/installer/setup.sh \
    --ssl custom \
    --ssl-cert /path/to/cert.pem \
    --ssl-key /path/to/key.pem \
    --ssl-port 443 \
    --domain spear.example.com

Or with the build-and-deploy script:

sudo ./scripts/build-and-deploy.sh \
    --ssl-cert /path/to/cert.pem \
    --ssl-key /path/to/key.pem \
    --ssl-port 443

What happens during installation:

Certificate and key files are copied to a staging directory
On first boot, SPEAR reads the staging files, validates the cert/key pair, encrypts both using AES-GCM, and stores them in the database
Staging files are automatically deleted after import
SPEAR starts a custom HTTPS listener on the configured port (default: 443)
The PocketBase HTTP server continues on port 8090 for internal health checks

Admin UI

You can also upload and manage certificates through the SPEAR admin panel:

Navigate to Settings > SSL / TLS
Click Upload Certificate
Paste your certificate PEM and private key PEM
Set the HTTPS port (default: 443)
Click Save Certificate
Click Restart Now to apply changes

Architecture

Internet ──► SPEAR HTTPS :443 (custom TLS listener)
             │
             └── Same PocketBase router (all routes, middleware)

Internal ──► SPEAR HTTP :8090 (health checks, internal use)

Certificate Renewal

When your certificate expires:

Go to Settings > SSL / TLS
Click Replace Certificate
Paste the new certificate and private key
Click Save Certificate
Click Restart Now

Security

The private key is write-only: once stored, it cannot be retrieved via the API, only replaced
Both certificate and private key are encrypted at rest using AES-GCM with your SPEAR_ENCRYPTION_KEY
Certificate metadata (domain, issuer, expiry, serial number) is stored for display purposes
The API only returns metadata, never the certificate or key contents

Cloudflare Origin Certificates

For Cloudflare Origin Certificates:

In the Cloudflare dashboard, go to SSL/TLS > Origin Server
Click Create Certificate
Keep the default RSA key type
Add your hostnames (e.g., spear.example.com)
Choose certificate validity (15 years recommended for origin certs)
Copy the Origin Certificate and Private Key
Upload both to SPEAR via CLI or admin UI

Traefik Reverse Proxy

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`