xamxam/nginx/PRODUCTION_DEPLOYMENT.md

# Production Deployment Guide - Post-ERG

This guide will help you deploy the production nginx configuration with proper security and permissions.

## 🎯 Overview

Your current setup:
- **Server IP**: 192.168.6.125 (internal)
- **PHP Version**: 8.4
- **SSL/TLS**: Handled by reverse proxy (already working)
- **Issue**: File permissions preventing nginx from reading files

## 🚀 Quick Deployment

From your local machine:

```bash
# Deploy the production config and deployment script
just deploy-nginx-production

# SSH to the server and run the deployment
ssh posterg
sudo /tmp/deploy-production.sh
```

## 📋 Step-by-Step Deployment

### 1. Set Up Admin Password (First Time Only)

```bash
ssh posterg
sudo htpasswd -c /etc/nginx/.htpasswd-posterg admin
# Enter a strong password when prompted
```

**💡 Tip**: Generate a strong password:
```bash
openssl rand -base64 32
```

### 2. Deploy Configuration

From your local machine:

```bash
# Upload nginx config and deployment script
rsync -vur ./nginx/posterg-production.conf posterg:/tmp/posterg.conf
rsync -vur ./nginx/deploy-production.sh posterg:/tmp/deploy-production.sh
```

### 3. Run Deployment Script

On the server:

```bash
ssh posterg
sudo chmod +x /tmp/deploy-production.sh
sudo /tmp/deploy-production.sh
```

The script will:
- ✅ Fix file permissions (set to posterg group)
- ✅ Install nginx configuration
- ✅ Test nginx configuration
- ✅ Reload nginx
- ✅ Check PHP-FPM status

## 🔧 Manual Deployment (Alternative)

If you prefer to do it manually:

### Step 1: Fix Permissions

```bash
ssh posterg

# Set correct ownership (posterg group)
sudo chown -R theophile:posterg /var/www/html/

# Set directory permissions
sudo find /var/www/html -type d -exec chmod 755 {} \;

# Set file permissions (group readable)
sudo find /var/www/html -type f -exec chmod 640 {} \;

# Make upload directories writable
sudo chmod 775 /var/www/html/formulaire/data/theses
sudo chmod 775 /var/www/html/formulaire/data/covers

# Protect database
sudo chmod 640 /var/www/html/database/posterg.db
sudo chown www-data:posterg /var/www/html/database/posterg.db
```

### Step 2: Deploy Nginx Config

```bash
# Copy config
sudo cp /tmp/posterg.conf /etc/nginx/sites-available/posterg

# Enable site
sudo ln -sf /etc/nginx/sites-available/posterg /etc/nginx/sites-enabled/posterg

# Disable default site
sudo rm -f /etc/nginx/sites-enabled/default

# Test configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx
```

### Step 3: Verify PHP-FPM

```bash
# Check PHP-FPM is running
sudo systemctl status php8.4-fpm

# If not running, start it
sudo systemctl start php8.4-fpm
sudo systemctl enable php8.4-fpm
```

## 🧪 Testing

### Test Public Site

```bash
# Should return 200 OK
curl -I http://localhost/

# Should return 200 OK with HTML
curl http://localhost/index.php
```

### Test Admin Protection

```bash
# Should return 401 Unauthorized
curl -I http://localhost/formulaire/

# Should return 200 OK with credentials
curl -u admin:your_password http://localhost/formulaire/
```

### Test File Protection

```bash
# These should all return 403 Forbidden
curl -I http://localhost/database/posterg.db
curl -I http://localhost/README.md
curl -I http://localhost/shared/Database.php
curl -I http://localhost/.git/config
```

### Test Security Headers

```bash
curl -I http://localhost/ | grep -E "X-Frame|X-Content|X-XSS"
```

### From Your Browser

Visit https://posterg.erg.be/ - should work now!

## 🔍 Troubleshooting

### Still Getting 403 Forbidden

**Check file permissions:**
```bash
ls -la /var/www/html/index.php
# Should show: -rw-r----- 1 theophile posterg ...
```

**Check nginx user is in posterg group:**
```bash
groups www-data
# Should show: www-data : www-data posterg
```

**Check directory permissions:**
```bash
ls -lad /var/www/html
# Should show: drwxr-xr-x ... posterg
```

### 502 Bad Gateway

**Check PHP-FPM:**
```bash
sudo systemctl status php8.4-fpm
sudo systemctl restart php8.4-fpm
```

**Check socket file:**
```bash
ls -la /var/run/php/php8.4-fpm.sock
# Should exist and be writable by www-data
```

### Admin Password Not Working

**Reset password:**
```bash
sudo htpasswd /etc/nginx/.htpasswd-posterg admin
```

**Check file exists:**
```bash
ls -la /etc/nginx/.htpasswd-posterg
# Should show: -rw-r--r-- 1 root root ...
```

### Database Not Accessible to PHP

**Fix database permissions:**
```bash
sudo chown www-data:posterg /var/www/html/database/posterg.db
sudo chmod 640 /var/www/html/database/posterg.db
sudo chmod 755 /var/www/html/database/
```

### Can't Write Uploaded Files

**Fix upload directory permissions:**
```bash
sudo chmod 775 /var/www/html/formulaire/data/theses
sudo chmod 775 /var/www/html/formulaire/data/covers
sudo chown -R theophile:posterg /var/www/html/formulaire/data/
```

## 📊 Monitoring

### Watch Logs

```bash
# Access logs
sudo tail -f /var/log/nginx/posterg_access.log

# Error logs
sudo tail -f /var/log/nginx/posterg_error.log

# PHP errors
sudo tail -f /var/log/php8.4-fpm.log
```

### Check Nginx Status

```bash
sudo systemctl status nginx
sudo nginx -t
```

### Check Resource Usage

```bash
# Nginx processes
ps aux | grep nginx

# PHP-FPM processes
ps aux | grep php-fpm

# Disk usage
df -h /var/www/html
```

## 🔒 Security Checklist

After deployment, verify:

- [ ] ✅ Public site accessible at https://posterg.erg.be/
- [ ] ✅ Admin panel requires password
- [ ] ✅ Database files return 403 Forbidden
- [ ] ✅ Sensitive files (.md, .sql) return 403 Forbidden
- [ ] ✅ Shared directory returns 403 Forbidden
- [ ] ✅ Security headers present in responses
- [ ] ✅ PHP-FPM running and accessible
- [ ] ✅ File uploads work in admin panel
- [ ] ✅ Search functionality works
- [ ] ✅ Logs are being written

## 🔄 Updating the Site

For future updates:

```bash
# Deploy code changes
just deploy

# Reload nginx if config changed
ssh posterg "sudo systemctl reload nginx"

# Clear PHP opcache if needed
ssh posterg "sudo systemctl reload php8.4-fpm"
```

## 🆘 Emergency Recovery

If something goes wrong:

### Restore Default Config

```bash
ssh posterg
sudo rm /etc/nginx/sites-enabled/posterg
sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default
sudo systemctl reload nginx
```

### Reset Permissions

```bash
ssh posterg
sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;
sudo systemctl reload nginx
```

## 📞 Support Resources

- **Nginx docs**: https://nginx.org/en/docs/
- **PHP-FPM docs**: https://www.php.net/manual/en/install.fpm.php
- **Let's Encrypt**: https://letsencrypt.org/
- **Security headers**: https://securityheaders.com/

## 🎉 Success Criteria

You know the deployment is successful when:

1. ✅ Visit https://posterg.erg.be/ - shows homepage
2. ✅ Visit https://posterg.erg.be/formulaire/ - asks for password
3. ✅ Search works correctly
4. ✅ Individual thesis pages load
5. ✅ Admin can upload files
6. ✅ No 403 or 502 errors in logs
7. ✅ Security headers present (check with curl -I)

---

**Need help?** Check the error logs first:
```bash
sudo tail -f /var/log/nginx/posterg_error.log
```