# 🚀 Automatic HTTPS Setup

## One-Command HTTPS Startup

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

### Windows
```cmd
start-https.bat
```

### Linux/Mac
```bash
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:**
```bash
cp env.example .env
# Edit .env with your settings
```

**2. Start with HTTPS:**

**Windows:**
```cmd
start-https.bat
```

**Linux/Mac:**
```bash
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:**
```powershell
choco install mkcert
```

**macOS:**
```bash
brew install mkcert
```

**Linux:**
```bash
# 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:**
   ```bash
   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
bash start-https.sh     # Linux/Mac
start-https.bat         # Windows
```

### Start with HTTPS (Manual)
```bash
# 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
```bash
docker-compose logs -f
docker-compose logs nginx
docker-compose logs certgen
```

### Stop Services
```bash
docker-compose down
```

### Regenerate Certificates
```bash
# 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:

```bash
# 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:**
```bash
ls -la nginx/ssl/
```

**Should see:**
- `cert.pem`
- `key.pem`

**If missing, check certgen logs:**
```bash
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:**
```bash
export HOST_IP=192.168.1.XXX  # Your actual IP
bash start-https.sh
```

### Port 443 Already in Use

**Find what's using it:**
```bash
# 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

```bash
# 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! 🔒**