TimeTracker/docs/security/README_HTTPS.md

🔒 HTTPS Setup for TimeTracker

Quick Start with mkcert

1. Install mkcert

Windows:

choco install mkcert

macOS:

brew install mkcert

Linux:

# See HTTPS_MKCERT_GUIDE.md for detailed instructions

2. Run Setup Script

Windows:

setup-https-mkcert.bat

Linux/Mac:

bash setup-https-mkcert.sh

3. Start with HTTPS

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

4. Access Your App

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

✅ No certificate warnings! ✅ Works with IP addresses! ✅ Secure HTTPS!

---

What the Script Does

1. ✅ Installs local Certificate Authority (trusted by your browser)
2. ✅ Generates SSL certificates for localhost + your IP
3. ✅ Creates nginx reverse proxy configuration
4. ✅ Creates docker-compose.https.yml
5. ✅ Updates .env with secure HTTPS settings:
   • WTF_CSRF_SSL_STRICT=true
   • SESSION_COOKIE_SECURE=true
   • CSRF_COOKIE_SECURE=true

---

Benefits

Solves CSRF Cookie Issues

• ✅ CSRF cookies work correctly with IP addresses
• ✅ Strict security settings enabled
• ✅ No more "CSRF token missing or invalid" errors

Secure Communication

• ✅ All traffic encrypted
• ✅ Trusted certificates (no warnings)
• ✅ Modern TLS 1.2/1.3

Easy Management

• ✅ One command setup
• ✅ Valid for 10 years
• ✅ No renewal needed

---

Access from Other Devices

To access from your phone, tablet, or other computers without warnings:

1. Find CA location:

   mkcert -CAROOT
   

2. Copy rootCA.pem to device

3. Install certificate on device:

   • iOS: Settings → Profile → Install
   • Android: Settings → Security → Install certificate
   • See HTTPS_MKCERT_GUIDE.md for details

4. Access from device:

   https://192.168.1.100
   

---

File Structure

After running the setup:

TimeTracker/
├── nginx/
│   ├── conf.d/
│   │   └── https.conf          # nginx HTTPS config
│   └── ssl/
│       ├── cert.pem            # SSL certificate (gitignored)
│       └── key.pem             # Private key (gitignored)
├── docker-compose.yml          # Base configuration
├── docker-compose.https.yml    # HTTPS override (auto-generated)
├── setup-https-mkcert.sh      # Linux/Mac setup script
├── setup-https-mkcert.bat     # Windows setup script
└── .env                        # Updated with HTTPS settings

---

Verification

Check Certificate

1. Navigate to https://localhost
2. Click padlock icon in browser
3. View certificate → Should show "mkcert" with no warnings

Check Cookies

1. Open DevTools (F12) → Application → Cookies
2. Verify session and XSRF-TOKEN cookies have Secure flag

Test Application

1. Login
2. Create a project
3. Log time
4. Should work without any CSRF errors ✅

---

Stopping HTTPS

To return to HTTP:

# Stop HTTPS setup
docker-compose -f docker-compose.yml -f docker-compose.https.yml down

# Start normally
docker-compose up -d

---

Troubleshooting

Certificate Warning Appears

# Reinstall CA
mkcert -install

# Restart browser completely

nginx Won't Start

# Check if port is in use
netstat -ano | findstr :443     # Windows
lsof -i :443                    # Linux/Mac

# Check logs
docker-compose logs nginx

IP Address Not Working

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

# Restart
docker-compose restart nginx

---

Complete Documentation

For detailed instructions, see:

• HTTPS_MKCERT_GUIDE.md - Complete mkcert guide
• CSRF_IP_ACCESS_FIX.md - CSRF troubleshooting

---

Summary

One command to HTTPS:

bash setup-https-mkcert.sh
docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

Result: ✅ Secure HTTPS
✅ No certificate warnings
✅ Works with IP addresses
✅ CSRF cookies work perfectly
✅ Production-grade security settings

Enjoy secure TimeTracker! 🔒