Local SSL/HTTPS

Local SSL/​HTTPS

Enable HTTPS for local development environments with automatically trusted SSL certificates. This skill handles certificate generation, trust configuration, and web server setup.

Core Workflows

1. mkcert Setup (Recommended Approach)

mkcert is the simplest way to generate locally-trusted certificates.

# Generate: scripts/​setup-ssl.sh

#!/​bin/​bash
set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m'

echo -e "${BLUE}🔐 Setting up local SSL certificates...${NC}\n"

# Check if mkcert is installed
if ! command -v mkcert &> /​dev/​null; then
  echo -e "${BLUE}📦 Installing mkcert...${NC}"
  
  # Detect OS and install mkcert
  if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS
    brew install mkcert nss  # nss for Firefox support
  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
    # Linux
    if command -v apt-get &> /​dev/​null; then
      sudo apt-get install -y libnss3-tools
      curl -JLO "https://dl.filippo.io/​mkcert/​latest?for=linux/​amd64"
      chmod +x mkcert-v*-linux-amd64
      sudo mv mkcert-v*-linux-amd64 /​usr/​local/​bin/​mkcert
    fi
  else
    echo -e "${RED}❌ Unsupported OS. Please install mkcert manually.${NC}"
    exit 1
  fi
fi

# Create certs directory
mkdir -p certs

# Install local CA
echo -e "${BLUE}🔒 Installing local Certificate Authority...${NC}"
mkcert -install

# Generate certificates for localhost and custom domains
echo -e "${BLUE}🔑 Generating certificates...${NC}"
mkcert -cert-file certs/​localhost.crt \
       -key-file certs/​localhost.key \
       localhost 127.0.0.1 ::1 \
       *.localhost \
       local.dev \
       *.local.dev

echo -e "\n${GREEN}✅ SSL certificates generated!${NC}"
echo -e "${BLUE}📍 Certificate files:${NC}"
echo -e "   certs/​localhost.crt"
echo -e "   certs/​localhost.key"

2. Docker Compose with SSL

# Update docker-compose.yml to mount certificates

version: '3.8'

services:
  frontend:
    build:
      context: ./​frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
      - "3443:3443"  # HTTPS port
    environment:
      - HTTPS=true
      - SSL_CRT_FILE=/​certs/​localhost.crt
      - SSL_KEY_FILE=/​certs/​localhost.key
    volumes:
      - ./​frontend:/​app
      - /​app/​node_modules
      - ./​certs:/​certs:ro  # Mount certificates as read-only
    networks:
      - app-network

  api:
    build:
      context: ./​backend
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
      - "8443:8443"  # HTTPS port
    environment:
      - SSL_CERT=/​certs/​localhost.crt
      - SSL_KEY=/​certs/​localhost.key
    volumes:
      - ./​backend:/​app
      - /​app/​node_modules
      - ./​certs:/​certs:ro
    networks:
      - app-network

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./​nginx/​nginx-ssl.conf:/​etc/​nginx/​conf.d/​default.conf:ro
      - ./​certs:/​etc/​nginx/​certs:ro
    depends_on:
      - frontend
      - api
    networks:
      - app-network

3. Nginx SSL Configuration

# Generate: nginx/​nginx-ssl.conf

# Frontend HTTPS
server {
    listen 443 ssl http2;
    server_name localhost local.dev;

    ssl_certificate /​etc/​nginx/​certs/​localhost.crt;
    ssl_certificate_key /​etc/​nginx/​certs/​localhost.key;

    # SSL Configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location / {
        proxy_pass http://frontend:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API HTTPS
server {
    listen 443 ssl http2;
    server_name api.localhost api.local.dev;

    ssl_certificate /​etc/​nginx/​certs/​localhost.crt;
    ssl_certificate_key /​etc/​nginx/​certs/​localhost.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://api:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# HTTP to HTTPS redirect
server {
    listen 80;
    server_name localhost local.dev api.localhost api.local.dev;
    return 301 https://$host$request_uri;
}

4. Vite HTTPS Configuration

// Generate: frontend/​vite.config.ts (with HTTPS)

import { defineConfig } from 'vite';
import react from '@vitejs/​plugin-react';
import fs from 'fs';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 3000,
    https: process.env.HTTPS === 'true' ? {
      key: fs.readFileSync(path.resolve(__dirname, '../​certs/​localhost.key')),
      cert: fs.readFileSync(path.resolve(__dirname, '../​certs/​localhost.crt')),
    } : undefined,
    watch: {
      usePolling: true,
    },
  },
});

5. Node.js/​Express HTTPS Setup

// Generate: backend/​src/​server.ts (with HTTPS)

import express from 'express';
import https from 'https';
import http from 'http';
import fs from 'fs';
import path from 'path';

const app = express();

// Your middleware and routes here
app.use(express.json());

// Health check
app.get('/​health', (req, res) => {
  res.json({ status: 'ok', protocol: req.protocol });
});

const PORT = process.env.PORT || 8000;
const HTTPS_PORT = 8443;

// Start HTTP server
http.createServer(app).listen(PORT, () => {
  console.log(`HTTP server running on http://localhost:${PORT}`);
});

// Start HTTPS server if certificates exist
if (process.env.SSL_CERT && process.env.SSL_KEY) {
  try {
    const httpsOptions = {
      key: fs.readFileSync(process.env.SSL_KEY),
      cert: fs.readFileSync(process.env.SSL_CERT),
    };

    https.createServer(httpsOptions, app).listen(HTTPS_PORT, () => {
      console.log(`HTTPS server running on https://localhost:${HTTPS_PORT}`);
    });
  } catch (error) {
    console.error('Failed to start HTTPS server:', error);
  }
}

6. OpenSSL Alternative (Manual)

For systems where mkcert isn't available:

# Generate: scripts/​generate-certs-openssl.sh

#!/​bin/​bash
set -e

mkdir -p certs

# Generate private key
openssl genrsa -out certs/​localhost.key 2048

# Generate certificate signing request
openssl req -new -key certs/​localhost.key -out certs/​localhost.csr \
  -subj "/​C=US/​ST=State/​L=City/​O=Development/​CN=localhost"

# Generate self-signed certificate
openssl x509 -req -days 365 -in certs/​localhost.csr \
  -signkey certs/​localhost.key -out certs/​localhost.crt \
  -extfile <(printf "subjectAltName=DNS:localhost,DNS:*.localhost,IP:127.0.0.1")

# Clean up CSR
rm certs/​localhost.csr

echo "✅ Certificates generated!"
echo "⚠️  You'll need to manually trust the certificate in your browser"

7. Certificate Trust Scripts

# Generate: scripts/​trust-cert.sh

#!/​bin/​bash

RED='\033[0;31m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m'

CERT_FILE="certs/​localhost.crt"

if [ ! -f "$CERT_FILE" ]; then
  echo -e "${RED}❌ Certificate not found: $CERT_FILE${NC}"
  exit 1
fi

echo -e "${BLUE}🔒 Adding certificate to system trust store...${NC}"

if [[ "$OSTYPE" == "darwin"* ]]; then
  # macOS
  sudo security add-trusted-cert -d -r trustRoot \
    -k /​Library/​Keychains/​System.keychain "$CERT_FILE"
  echo -e "${GREEN}✅ Certificate trusted on macOS${NC}"
  
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
  # Linux
  sudo cp "$CERT_FILE" /​usr/​local/​share/​ca-certificates/​localhost.crt
  sudo update-ca-certificates
  echo -e "${GREEN}✅ Certificate trusted on Linux${NC}"
  
else
  echo -e "${RED}❌ Unsupported OS for automatic trust${NC}"
  echo "Please manually trust the certificate:"
  echo "  - Chrome: chrome://settings/​certificates"
  echo "  - Firefox: about:preferences#privacy"
fi

Environment Configuration

# Add to .env

# SSL Configuration
HTTPS=true
SSL_CERT_FILE=./​certs/​localhost.crt
SSL_KEY_FILE=./​certs/​localhost.key

# Update URLs to use HTTPS
VITE_API_URL=https://localhost:8443
API_BASE_URL=https://localhost:8443

Testing SSL Setup

# Generate: scripts/​test-ssl.sh

#!/​bin/​bash

echo "🧪 Testing SSL setup..."

# Test HTTPS endpoint
if curl -k -s https://localhost:3443 > /​dev/​null 2>&1; then
  echo "✅ Frontend HTTPS is working"
else
  echo "❌ Frontend HTTPS failed"
fi

if curl -k -s https://localhost:8443/​health > /​dev/​null 2>&1; then
  echo "✅ API HTTPS is working"
else
  echo "❌ API HTTPS failed"
fi

# Check certificate validity
echo ""
echo "📋 Certificate details:"
openssl x509 -in certs/​localhost.crt -noout -subject -dates

Makefile Integration

.PHONY: ssl-setup ssl-test ssl-clean

ssl-setup: ## Generate and trust SSL certificates
	@./​scripts/​setup-ssl.sh

ssl-test: ## Test SSL configuration
	@./​scripts/​test-ssl.sh

ssl-clean: ## Remove SSL certificates
	@rm -rf certs
	@echo "✅ SSL certificates removed"

Best Practices

1. Never commit certificates - Add certs/ to .gitignore
2. Use mkcert for development - Easiest and most reliable
3. Automate setup - Include in onboarding scripts
4. Test in all browsers - Chrome, Firefox, Safari, Edge
5. Document the process - Help teammates get started quickly
6. Use consistent domains - *.localhost or *.local.dev

Integration with zero-to-running

When both skills are active:

1. SSL is set up automatically during make dev
2. Services available over HTTPS
3. Certificates automatically trusted
4. Environment variables configured correctly

Troubleshooting

Certificate not trusted:

# Reinstall CA
mkcert -uninstall
mkcert -install

Port conflicts:

# Change ports in .env
HTTPS_PORT=4443

Browser shows NET::ERR_CERT_AUTHORITY_INVALID:

• Run mkcert -install again
• Restart browser completely
• Check system keychain for certificate