TimeTracker/docs/security/HTTPS_MKCERT_GUIDE.md

HTTPS Setup with mkcert - Complete Guide

🎯 What is mkcert?

mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration and creates certificates that work with:

• ✅ localhost
• ✅ IP addresses (192.168.1.100)
• ✅ Custom domains (timetracker.local)
• ✅ NO browser warnings!

Perfect for development and local network deployment.

---

📦 Installation

Windows

Option 1: Chocolatey

choco install mkcert

Option 2: Scoop

scoop bucket add extras
scoop install mkcert

macOS

brew install mkcert

Linux

Ubuntu/Debian:

sudo apt install 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

Arch Linux:

sudo pacman -S mkcert

---

🚀 Quick Setup

Automated Setup (Recommended)

Windows:

setup-https-mkcert.bat

Linux/Mac:

bash setup-https-mkcert.sh

This will:

1. Install local Certificate Authority (CA)
2. Generate certificates for localhost + your IP
3. Create nginx configuration
4. Create docker-compose.https.yml
5. Update .env with secure settings

Start with HTTPS

docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

Access Your Application

https://localhost
https://192.168.1.100  (your IP)
https://timetracker.local

No certificate warnings! 🎉

---

🔧 Manual Setup

If you prefer to do it manually:

Step 1: Install CA

mkcert -install

This installs a local Certificate Authority on your system that browsers will trust.

Step 2: Generate Certificates

# Create directories
mkdir -p nginx/ssl

# Generate certs (replace 192.168.1.100 with your IP)
mkcert -key-file nginx/ssl/key.pem \
       -cert-file nginx/ssl/cert.pem \
       localhost 127.0.0.1 ::1 192.168.1.100 *.local

Windows PowerShell:

mkdir nginx\ssl -Force
mkcert -key-file nginx\ssl\key.pem -cert-file nginx\ssl\cert.pem localhost 127.0.0.1 ::1 192.168.1.100 *.local

Step 3: Create nginx Configuration

Create nginx/conf.d/https.conf:

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name _;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

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

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;

    location / {
        proxy_pass http://app:8080;
        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;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Step 4: Create docker-compose.https.yml

services:
  nginx:
    image: nginx:alpine
    container_name: timetracker-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - app
    restart: unless-stopped

  app:
    ports: []  # nginx handles ports
    environment:
      - WTF_CSRF_SSL_STRICT=true
      - SESSION_COOKIE_SECURE=true
      - CSRF_COOKIE_SECURE=true

Step 5: Update .env

WTF_CSRF_SSL_STRICT=true
SESSION_COOKIE_SECURE=true
CSRF_COOKIE_SECURE=true

Step 6: Start Services

docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

---

🌐 Access from Other Devices

To access from phones, tablets, or other computers on your network without certificate warnings:

Step 1: Find Your CA Location

mkcert -CAROOT

This shows the directory containing rootCA.pem

Example output:

/Users/username/Library/Application Support/mkcert
C:\Users\username\AppData\Local\mkcert

Step 2: Copy rootCA.pem to Device

Transfer the rootCA.pem file to your device via:

• USB drive
• Network share
• Email
• Cloud storage

Step 3: Install CA on Device

iOS/iPadOS:

1. Open rootCA.pem file
2. Install profile
3. Settings → General → About → Certificate Trust Settings
4. Enable the certificate

Android:

1. Settings → Security → Encryption & credentials
2. Install certificate from storage
3. Select rootCA.pem

Windows:

1. Double-click rootCA.pem
2. Install Certificate
3. Store: Local Machine → Trusted Root Certification Authorities

macOS:

1. Double-click rootCA.pem
2. Add to Keychain
3. Trust for SSL

Linux:

sudo cp rootCA.pem /usr/local/share/ca-certificates/mkcert-rootCA.crt
sudo update-ca-certificates

Step 4: Access from Device

https://192.168.1.100

✅ No certificate warning!

---

🔍 Verification

Check Certificate in Browser

1. Navigate to https://localhost
2. Click the padlock icon
3. View certificate details
4. Should show:
   • ✅ Issued by: mkcert
   • ✅ Valid for: localhost, 127.0.0.1, your IP
   • ✅ No warnings

Test HTTPS Redirect

# Should redirect to HTTPS
curl -I http://localhost

# Should show 301 redirect

Verify nginx

# Check nginx is running
docker-compose ps nginx

# Check nginx logs
docker-compose logs nginx

Test Application

1. Access via HTTPS
2. Open DevTools (F12) → Application → Cookies
3. Verify cookies have Secure flag
4. Test form submissions (login, create project)
5. Should work without CSRF errors

---

🛠️ Troubleshooting

Certificate Warning Still Appears

Cause: CA not installed or browser not restarted

Solution:

# Reinstall CA
mkcert -install

# Restart browser completely (close all windows)

# Clear browser cache and cookies

"NET::ERR_CERT_AUTHORITY_INVALID"

Cause: Browser doesn't trust the CA

Solution:

1. Check CA is installed: mkcert -CAROOT
2. Reinstall: mkcert -install
3. On Linux, may need libnss3-tools
4. Restart browser

nginx Won't Start

Cause: Port 80 or 443 already in use

Check:

# Windows
netstat -ano | findstr :443

# Linux/Mac
lsof -i :443

Solution:

# Stop conflicting service or change ports in docker-compose.https.yml
ports:
  - "8080:80"
  - "8443:443"

Certificate Not Valid for IP Address

Cause: IP not included when generating cert

Solution:

# Regenerate with your IP
mkcert -key-file nginx/ssl/key.pem \
       -cert-file nginx/ssl/cert.pem \
       localhost 127.0.0.1 ::1 YOUR_IP_HERE *.local

# Restart nginx
docker-compose restart nginx

Other Devices Show Warning

Cause: CA not installed on device

Solution:

• Follow "Access from Other Devices" section above
• Install rootCA.pem on each device
• Restart browser/app on device

---

🔄 Certificate Renewal

mkcert certificates are valid for 10 years by default. No renewal needed for development use!

To check expiration:

openssl x509 -in nginx/ssl/cert.pem -noout -dates

To regenerate:

# Re-run setup script
bash setup-https-mkcert.sh

# Or manually
mkcert -key-file nginx/ssl/key.pem -cert-file nginx/ssl/cert.pem localhost 127.0.0.1 ::1 YOUR_IP *.local

# Restart nginx
docker-compose restart nginx

---

🔐 Security Notes

Development Use Only

mkcert is designed for development and testing:

• ✅ Perfect for local development
• ✅ Great for LAN/home network
• ✅ Safe for trusted networks
• ❌ NOT for production internet-facing apps

For Production

Use real certificates:

• Let's Encrypt (free, automated)
• Commercial CA (paid)
• Use Caddy for automatic HTTPS

See production deployment guides for details.

Best Practices

1. ✅ Keep rootCA.pem secure (anyone with it can create trusted certs)
2. ✅ Don't commit nginx/ssl/*.pem to git (add to .gitignore)
3. ✅ Use different certs for each project
4. ✅ Uninstall CA when not needed: mkcert -uninstall

---

📋 Command Reference

# Install CA
mkcert -install

# Find CA location
mkcert -CAROOT

# Generate certificate
mkcert -key-file KEY.pem -cert-file CERT.pem DOMAIN1 DOMAIN2

# Uninstall CA
mkcert -uninstall

# Check certificate
openssl x509 -in CERT.pem -text -noout

---

🎉 Summary

What You Get

✅ Local HTTPS with NO warnings ✅ Works with IP addresses ✅ Trusted by all browsers ✅ Valid for 10 years ✅ Perfect for development

Quick Start

# Install mkcert
# Windows: choco install mkcert
# Mac: brew install mkcert

# Run setup
bash setup-https-mkcert.sh

# Start with HTTPS
docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

# Access
https://localhost
https://192.168.1.100

That's it! Enjoy secure HTTPS! 🔒