# 🔒 One-Time HTTPS Setup for Xero (Local Development Only)

## 🎯 **mkcert: Perfect One-Time Solution**

**✅ One-time setup, works forever**  
**✅ No production impact whatsoever**  
**✅ Trusted certificates, no browser warnings**

---

## 🚀 **Step 1: Install mkcert (One-Time)**

```bash
# Windows (Run as Administrator)
choco install mkcert

# Alternative: Download directly
# Go to: https://github.com/FiloSottile/mkcert/releases
# Download mkcert-v1.4.4-windows-amd64.exe
# Rename to mkcert.exe and put in PATH
```

## 🛡️ **Step 2: Setup Local Certificate Authority (One-Time)**

```bash
# This installs a local CA in your browser/system trust store
# ONLY affects your local machine, not production!
mkcert -install
```

## 📜 **Step 3: Generate Localhost Certificate (One-Time)**

```bash
# In your project root
mkdir ssl
cd ssl
mkcert localhost 127.0.0.1 ::1

# This creates:
# - localhost+2.pem (certificate)
# - localhost+2-key.pem (private key)
```

## 🐳 **Step 4: Update Docker for HTTPS (One-Time)**

### **Create nginx SSL config:**

Create `docker/nginx/ssl.conf`:
```nginx
server {
    listen 443 ssl http2;
    server_name localhost;
    
    ssl_certificate /etc/nginx/ssl/localhost+2.pem;
    ssl_certificate_key /etc/nginx/ssl/localhost+2-key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    root /var/www/public;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS on;
        include fastcgi_params;
    }
}

# Keep HTTP working too
server {
    listen 80;
    server_name localhost;
    
    root /var/www/public;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

### **Update docker-compose.yml:**

Add HTTPS port and mount certificates:
```yaml
services:
  nginx:
    # ... existing config ...
    ports:
      - "8000:443"     # HTTPS on familiar port 8000
    volumes:
      # ... existing volumes ...
      - ./ssl:/etc/nginx/ssl:ro                               # Mount SSL certificates
      - ./docker/nginx/ssl.conf:/etc/nginx/conf.d/ssl.conf:ro # Mount SSL config
```

## ⚙️ **Step 5: Update Environment (One-Time)**

```env
# Update .env - use HTTPS on same familiar port
APP_URL=https://localhost:8000
XERO_REDIRECT_URI=https://localhost:8000/api/v1/xero/callback
```

## 🔄 **Step 6: Restart Docker (One-Time)**

```bash
docker-compose down
docker-compose up -d
```

## ✅ **Test It Works**

1. **HTTPS now works**: https://localhost:8000 (same port!)
2. **No browser warnings** (green padlock!)
3. **Same familiar URL** with SSL security
4. **Ready for Xero OAuth2**

---

## 🔒 **Security Notes**

### **✅ What This Does:**
- Creates trusted certificates **ONLY on your local machine**
- Adds HTTPS support to your **local Docker environment**
- **Zero impact** on production servers

### **✅ What This Doesn't Do:**
- **No changes** to production nginx
- **No changes** to live server configuration  
- **No security risks** to production environment
- **No external dependencies** once set up

### **✅ Production Separation:**
- Local: `https://localhost:8000` (development)
- Production: `https://seraph.computerassistance.co.uk` (unchanged)

---

## 🎯 **Why This is Perfect:**

1. **One-time setup** - do it once, works forever
2. **No browser warnings** - trusted certificates
3. **Same familiar port** - https://localhost:8000
4. **Zero production impact** - purely local
5. **Perfect for Xero** - meets HTTPS requirement
6. **No external dependencies** - works offline

## 🚀 **Ready to Use!**

After setup:
- **Development**: https://localhost:8000/admin/xero
- **Xero redirect**: https://localhost:8000/api/v1/xero/callback
- **Production**: Completely unaffected! 

Perfect for Xero OAuth2 integration! 🎯 