TimeTracker/docs/admin/security/README_HTTPS_AUTO.md

🚀 Automatic HTTPS Setup

One-Command HTTPS Startup

HTTPS is now completely automatic! Just run one command and everything is configured:

Windows

start-https.bat

Linux/Mac

bash start-https.sh

That's it! 🎉

---

What Happens Automatically

When you run the startup script:

1. ✅ Detects your local IP (e.g., 192.168.1.100)
2. ✅ Creates nginx HTTPS configuration automatically
3. ✅ Generates SSL certificates (init container runs once)
4. ✅ Updates security settings to strict mode
5. ✅ Starts all services with HTTPS enabled

No manual steps required!

---

Two Certificate Options

Option 1: Self-Signed Certificates (Default)

• ✅ Works immediately, zero setup
• ✅ Fully functional HTTPS
• ⚠️ Browser shows security warning (safe to click through)

When to use: Quick testing, development

Option 2: mkcert (Trusted Certificates)

• ✅ No browser warnings!
• ✅ Trusted by all browsers
• 📋 Requires one-time mkcert installation

When to use: Cleaner experience, demos, regular development

---

Quick Start

First Time Setup

1. Create .env file:

cp env.example .env
# Edit .env with your settings

2. Start with HTTPS:

Windows:

start-https.bat

Linux/Mac:

bash start-https.sh

3. Choose certificate method when prompted:

• Press 1 for self-signed (default)
• Press 2 for mkcert (if installed)

4. Access your app:

https://localhost
https://192.168.1.100  (your actual IP)

---

Self-Signed Certificates (Option 1)

What You'll See

Browser will show: "Your connection is not private"

How to Proceed

1. Click "Advanced"
2. Click "Proceed to localhost (unsafe)"
3. That's it! You're in.

Why It's Safe

• Certificates are generated by YOU
• Traffic is encrypted
• Warning is just because it's self-signed
• Perfect for development

---

mkcert Certificates (Option 2)

Prerequisites

Install mkcert first:

Windows:

choco install mkcert

macOS:

brew install mkcert

Linux:

# See HTTPS_MKCERT_GUIDE.md

One-Time CA Installation

After first startup with mkcert:

1. Find the CA certificate:

   nginx/ssl/rootCA.pem
   

2. Install it:

   Windows:

   • Double-click rootCA.pem
   • Install to "Trusted Root Certification Authorities"
   • Restart browser

   macOS:

   • Double-click rootCA.pem
   • Add to Keychain
   • Mark as "Always Trust"

   Linux:

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

3. Restart browser

4. Access app - No warnings! ✅

---

How It Works

Architecture

┌─────────────────┐
│  start-https    │  ← You run this
│     script      │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   Init Container│  ← Generates certificates (runs once)
│   (certgen)     │     • Checks if certs exist
└────────┬────────┘     • Creates them if missing
         │              • Self-signed or mkcert
         ↓
┌─────────────────┐
│  nginx (HTTPS)  │  ← Reverse proxy with SSL
│  Port 443       │     • Terminates SSL
└────────┬────────┘     • Proxies to app
         │
         ↓
┌─────────────────┐
│  TimeTracker    │  ← Your application
│  App (HTTP)     │     • Runs on port 8080
│  Port 8080      │     • Behind nginx
└─────────────────┘

Certificate Generation

The certgen init container:

• Runs before nginx starts
• Checks for existing certificates in nginx/ssl/
• If missing, generates new ones
• Exits (runs only once)
• nginx starts after successful completion

Persistence

Certificates are stored in nginx/ssl/ on your host machine:

• Persists across container restarts
• Regenerated only if deleted
• Valid for 10 years

---

File Structure

After automatic startup:

TimeTracker/
├── nginx/
│   ├── conf.d/
│   │   └── https.conf           # Auto-generated nginx config
│   └── ssl/
│       ├── cert.pem             # SSL certificate
│       ├── key.pem              # Private key
│       └── rootCA.pem           # CA cert (mkcert only)
├── docker-compose.yml           # Base config
├── docker-compose.https-auto.yml    # HTTPS with self-signed
├── docker-compose.https-mkcert.yml  # HTTPS with mkcert
├── start-https.sh               # Auto-start script (Linux/Mac)
├── start-https.bat              # Auto-start script (Windows)
└── .env                         # Config (auto-updated)

---

Commands

Start with HTTPS (Automatic)

bash start-https.sh     # Linux/Mac
start-https.bat         # Windows

Start with HTTPS (Manual)

# Self-signed certificates
docker-compose -f docker-compose.yml -f docker-compose.https-auto.yml up -d

# mkcert certificates (if mkcert installed)
docker-compose -f docker-compose.yml -f docker-compose.https-mkcert.yml up -d

View Logs

docker-compose logs -f
docker-compose logs nginx
docker-compose logs certgen

Stop Services

docker-compose down

Regenerate Certificates

# Delete existing certs
rm -rf nginx/ssl/*

# Restart - new certs will be generated
bash start-https.sh

---

Environment Variables

After automatic setup, your .env will include:

# HTTPS Security Settings (auto-configured)
WTF_CSRF_SSL_STRICT=true
SESSION_COOKIE_SECURE=true
CSRF_COOKIE_SECURE=true

These settings:

• ✅ Enable strict CSRF protection
• ✅ Require HTTPS for cookies
• ✅ Fix all CSRF cookie issues
• ✅ Provide production-grade security

---

Troubleshooting

nginx Won't Start

Check if certificates exist:

ls -la nginx/ssl/

Should see:

• cert.pem
• key.pem

If missing, check certgen logs:

docker-compose logs certgen

Browser Still Shows Warning (mkcert)

CA not installed or browser not restarted:

1. Install nginx/ssl/rootCA.pem (see instructions above)
2. Completely close and restart browser
3. Clear browser cache

Different IP Address

Update and restart:

export HOST_IP=192.168.1.XXX  # Your actual IP
bash start-https.sh

Port 443 Already in Use

Find what's using it:

# Windows
netstat -ano | findstr :443

# Linux/Mac
lsof -i :443

Stop the conflicting service or change port in nginx config

---

Access from Other Devices

Using Self-Signed Certificates

1. Access https://192.168.1.100 from device
2. Click through security warning
3. Done!

Using mkcert Certificates

1. Copy nginx/ssl/rootCA.pem to device
2. Install as trusted CA (see device-specific instructions)
3. Access https://192.168.1.100
4. No warnings! ✅

---

Production Deployment

For production with a real domain, use Let's Encrypt:

• See docs/HTTPS_SETUP_GUIDE.md for Caddy (automatic)
• Or use Traefik, nginx + certbot

---

Summary

🎉 What You Get

✅ One-command setup - bash start-https.sh
✅ Automatic certificate generation
✅ Auto-configuration of nginx and security settings
✅ Choice of certificate types
✅ Persistent certificates across restarts
✅ No manual steps for basic setup

🚀 Quick Reference

# Start everything with HTTPS
bash start-https.sh

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

# View logs
docker-compose logs -f

# Stop
docker-compose down

That's it! Enjoy automatic HTTPS! 🔒