HTTPS Setup Guide¶

PCB Stackup Generator - Complete HTTPS Implementation¶

This guide provides comprehensive instructions for enabling HTTPS in your PCB Stackup Generator application, covering both development and production environments.

🔒 Security Implementation Overview¶

Your application now includes:

✅ HTTPS Redirect Middleware - Automatically redirects HTTP to HTTPS
✅ Security Headers - HSTS, CSP, XSS Protection, etc.
✅ Trusted Host Validation - Prevents host header attacks
✅ Environment-based Configuration - Different settings for dev/prod
✅ SSL Certificate Support - Both self-signed and CA-signed certificates

🛠️ Development Setup (Local HTTPS)¶

Step 1: Generate Development SSL Certificates¶

The repo does not ship a certificate-generation script. Create the certificates yourself with an external tool such as mkcert:

# From the frontend/ directory (Vite resolves the cert paths from where it runs)
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost

The Vite config (frontend/vite.config.ts) expects: - certs/localhost-key.pem - Private key - certs/localhost.pem - Certificate

If either file is missing, the dev server silently falls back to HTTP.

Step 2: Enable HTTPS in Development¶

Create or update the repo-root .env file (Vite loads VITE_* vars from the project root, not frontend/.env):

# Enable HTTPS in development
VITE_FORCE_HTTPS=true
FORCE_HTTPS=true

# API URLs with HTTPS
VITE_FASTAPI_URL=https://localhost:8000

Step 3: Start Development Servers¶

# Start all servers with HTTPS support
.\start-all-servers-windowed.ps1

Your application will be available at: - Frontend: https://localhost:5180 - FastAPI Backend: https://localhost:8000 (also serves the AI chat via SSE — there is no separate Node.js backend)

Browser Security Warning¶

Since we're using self-signed certificates, your browser will show a security warning. Click "Advanced" → "Proceed to localhost (unsafe)" to continue.

🌐 Production Setup (Real HTTPS)¶

Step 1: Domain and DNS Configuration¶

Purchase a domain (e.g., pcbgenerator.com)

Point DNS A records to your server's IP address:

pcbgenerator.com        A    YOUR_SERVER_IP
www.pcbgenerator.com    A    YOUR_SERVER_IP

Step 2: Server Setup and SSL Certificates¶

The repo does not ship an SSL setup script — use the standard Certbot + Nginx flow on your production server:

# Install Certbot and the Nginx plugin (Debian/Ubuntu example)
sudo apt install certbot python3-certbot-nginx

# Obtain certificates and configure Nginx for your domain
sudo certbot --nginx -d pcbgenerator.com -d www.pcbgenerator.com

This flow: - ✅ Obtains SSL certificates from Let's Encrypt - ✅ Configures Nginx with HTTPS - ✅ Sets up automatic certificate renewal (systemd timer / cron)

Step 3: Production Environment Configuration¶

Copy and configure your production environment:

# Copy template to production environment file
cp env.production.template .env.production

# Edit with your actual values
nano .env.production

Update these critical values:

# Your domain
TRUSTED_HOSTS=pcbgenerator.com,www.pcbgenerator.com
CORS_ORIGINS=https://pcbgenerator.com,https://www.pcbgenerator.com

# API URLs
VITE_API_URL=https://pcbgenerator.com/api
VITE_FASTAPI_URL=https://pcbgenerator.com/api

# Security
API_KEY=your_secure_api_key_here
SESSION_SECRET=your_session_secret_here

Step 4: Docker Production Deployment¶

# Deploy with HTTPS configuration
docker-compose -f docker-compose.prod.yml up -d

🔧 Configuration Details¶

Environment Variables¶

Variable	Development	Production	Description
`FORCE_HTTPS`	`true`	`true`	Enables HTTPS redirect
`ENVIRONMENT`	`development`	`production`	App environment
`TRUSTED_HOSTS`	`localhost,127.0.0.1`	`pcbgenerator.com,www.pcbgenerator.com`	Allowed hostnames
`CORS_ORIGINS`	`http://localhost:5180,https://localhost:5180`	`https://pcbgenerator.com,https://www.pcbgenerator.com`	Allowed origins

Security Headers Applied¶

When HTTPS is enabled, these headers are automatically added:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://www.googletagmanager.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https:; font-src 'self' https:; frame-src 'none';
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

🧪 Testing HTTPS Setup¶

1. Test SSL Certificate¶

# Check certificate details
openssl x509 -in /etc/letsencrypt/live/pcbgenerator.com/fullchain.pem -text -noout

# Test SSL connection
openssl s_client -connect pcbgenerator.com:443 -servername pcbgenerator.com

2. Test Security Headers¶

# Check security headers
curl -I https://pcbgenerator.com

# Test HTTPS redirect
curl -I http://pcbgenerator.com

3. SSL Labs Test¶

Visit: https://www.ssllabs.com/ssltest/analyze.html?d=pcbgenerator.com

4. Security Headers Test¶

Visit: https://securityheaders.com/?q=pcbgenerator.com

🚨 Troubleshooting¶

Common Issues¶

1. Certificate Not Found

# Check if certificates exist
ls -la /etc/letsencrypt/live/pcbgenerator.com/

# Renew certificates manually
sudo certbot renew --dry-run

2. Port 80/443 Not Accessible

# Check if ports are open
sudo netstat -tlnp | grep :80
sudo netstat -tlnp | grep :443

# Check firewall
sudo ufw status
sudo ufw allow 80
sudo ufw allow 443

3. DNS Issues

# Check DNS resolution
nslookup pcbgenerator.com
dig pcbgenerator.com A

4. CORS Errors

Update CORS origins in your environment:

CORS_ORIGINS=https://pcbgenerator.com,https://www.pcbgenerator.com

5. Mixed Content Warnings

Ensure all API calls use HTTPS in production:

// Use the API configuration
import { ENDPOINTS } from './config/api';

// This automatically uses HTTPS in production
const response = await fetch(ENDPOINTS.FASTAPI.KICAD_EXPORT, {
  method: 'POST',
  body: JSON.stringify(data)
});

📋 Security Checklist¶

Development¶

Self-signed certificates generated
HTTPS enabled in Vite config
Environment variables configured
All API calls use HTTPS URLs
Browser accepts self-signed certificate

Production¶

Domain DNS configured
SSL certificates obtained from Let's Encrypt
Nginx configured with HTTPS
Security headers enabled
HTTP to HTTPS redirect working
Automatic certificate renewal configured
CORS origins restricted to your domain
API keys secured in environment variables
SSL Labs test shows A+ rating

🔄 Maintenance¶

Certificate Renewal¶

Certificates are automatically renewed via cron job:

# Check renewal status
sudo certbot certificates

# Test renewal
sudo certbot renew --dry-run

# Manual renewal if needed
sudo certbot renew

Monitoring¶

Set up monitoring for: - Certificate expiration dates - SSL Labs rating - Security headers compliance - HTTPS redirect functionality

📚 Additional Resources¶

🎉 Verification¶

After completing this setup, your application should:

✅ Redirect HTTP to HTTPS automatically
✅ Display green padlock in browser
✅ Pass SSL Labs test with A+ rating
✅ Include security headers in all responses
✅ Work with all application features over HTTPS

Your PCB Stackup Generator is now fully secured with HTTPS! 🔒