xamxam/docs/COMPLETE_DEPLOYMENT_GUIDE.md

# Complete Deployment Guide - New Structure

## Overview

This guide walks you through deploying the new secure directory structure:
- **Old:** `/var/www/html/` (everything exposed)
- **New:** `/var/www/posterg/` with `public/` subdirectory (only public/ exposed)

## Step-by-Step Deployment

### ⚠️ IMPORTANT: Do NOT delete /var/www/html/ yet!

Keep it as a backup until you confirm the new structure works.

---

### Step 1: Setup Server Directory (Manual - One Time)

SSH to server and create the new directory:

```bash
ssh posterg

# Backup current site
sudo cp -r /var/www/html /var/www/html.backup

# Create new directory
sudo mkdir -p /var/www/posterg

# Set ownership (www-data = web server user)
sudo chown www-data:posterg /var/www/posterg

# Set permissions
sudo chmod 775 /var/www/posterg

# Verify
ls -ld /var/www/posterg
# Should show: drwxrwxr-x 2 www-data posterg ...

# Exit server
exit
```

---

### Step 2: Deploy Application Files

From your local machine:

```bash
just deploy
```

This will:
- Upload all files to `/var/www/posterg/`
- Exclude unnecessary files (tests, docs, etc.)
- Set initial ownership to `www-data:posterg`

You should see:
```
sending incremental file list
public/index.php
public/search.php
public/memoire.php
...
```

---

### Step 3: Deploy Nginx Configuration

```bash
just deploy-nginx
```

This will:
1. Check that nginx config has correct DocumentRoot (`/var/www/posterg/public`)
2. Upload `posterg.conf` to `/tmp/` on server
3. Upload `deploy-production-new.sh` to `/tmp/` on server

Expected output:
```
✅ nginx config looks correct
✅ Files uploaded to /tmp/ on server
```

---

### Step 4: Apply Nginx Configuration on Server

SSH to server and run the deployment script:

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

The script will:
1. Fix file permissions on `/var/www/posterg/`
2. Backup existing nginx config
3. Install new nginx config
4. Test nginx configuration
5. Show you the reload command

Expected output:
```
🚀 Post-ERG Production Deployment (NEW STRUCTURE)
==================================================

📋 Step 1: Fixing file permissions...
✓ Changed ownership to www-data:posterg
✓ Set directory permissions to 755
✓ Set file permissions to 644
✓ Made database directory group-writable (775)
✓ Fixed database file permissions (660)

📋 Step 2: Deploying nginx configuration...
✓ Backed up existing config
✓ Installed new nginx config

📋 Step 3: Testing nginx configuration...
✓ Nginx configuration is valid

📋 Step 4: Summary...
✓ Permissions fixed
✓ Nginx config installed
✓ Configuration validated

Ready to reload nginx!

Run: sudo systemctl reload nginx
```

---

### Step 5: Reload Nginx

Still on the server:

```bash
sudo systemctl reload nginx
```

If successful, you'll see no output (which is good!).

Check status:
```bash
sudo systemctl status nginx
# Should show "active (running)"
```

Exit server:
```bash
exit
```

---

### Step 6: Verify Deployment

From your local machine:

```bash
just server-status
```

Expected output:
```
🔍 Server Status
================
✓ Nginx running
✓ PHP-FPM running

Site check:
  • Public: 200 ✓
  • Admin:  200 ✓
```

---

### Step 7: Security Verification

Test these URLs in your browser or with curl:

```bash
# Should work (200 OK):
curl -I https://posterg.erg.be/
curl -I https://posterg.erg.be/admin/

# Should be 404 (SECURITY - private files):
curl -I https://posterg.erg.be/storage/test.db
curl -I https://posterg.erg.be/config/bootstrap.php
curl -I https://posterg.erg.be/includes/header.php
curl -I https://posterg.erg.be/lib/Database.php
```

**All private files must return 404!** If they don't, nginx is not configured correctly.

---

### Step 8: Deploy Database (If Needed)

If you need to update the database:

```bash
just deploy-database
```

This will warn you before overwriting.

---

### Step 9: Test Thoroughly

- [ ] Visit https://posterg.erg.be/
- [ ] Browse thesis list
- [ ] Open a thesis detail page
- [ ] Try search functionality
- [ ] Access admin panel (should require login)
- [ ] Verify private files return 404

---

### Step 10: Keep Backup for a While

**Do NOT delete `/var/www/html/` immediately!**

Keep it for a few days to ensure everything works. If you need to rollback:

```bash
ssh posterg
sudo nano /etc/nginx/sites-available/posterg
# Change: root /var/www/posterg/public;
# Back to: root /var/www/html;
sudo systemctl reload nginx
```

Your old site will work immediately.

---

## After Confirming Everything Works

A few days later, once you're confident:

```bash
ssh posterg
sudo rm -rf /var/www/html.backup
sudo rm -rf /var/www/html
```

---

## What Changed?

### Directory Structure

```
OLD:                          NEW:
/var/www/html/               /var/www/posterg/
├── index.php                ├── public/              ← DocumentRoot
├── search.php               │   ├── index.php
├── admin/                   │   ├── search.php
├── assets/                  │   ├── memoire.php
├── database/ ❌ exposed     │   ├── admin/
├── lib/ ❌ exposed          │   └── assets/
└── ...                      ├── includes/ ✅ private
                             ├── config/ ✅ private
                             ├── database/ ✅ private
                             └── lib/ ✅ private
```

### Nginx Configuration

```nginx
# OLD
root /var/www/html;
location ^~ /formulaire/ { ... }

# NEW
root /var/www/posterg/public;
location ^~ /admin/ { ... }
```

### Security Impact

| Resource | Old | New |
|----------|-----|-----|
| Database | ❌ Accessible if nginx misconfigured | ✅ Physically outside web root |
| Config files | ❌ One deny rule away | ✅ Physically private |
| Source code | ❌ Exposed | ✅ Physically private |
| Admin panel | /formulaire/ | /admin/ |

---

## Troubleshooting

### Site returns 404 for everything

**Cause:** Nginx still pointing to old location or wrong DocumentRoot

**Fix:**
```bash
ssh posterg
sudo cat /etc/nginx/sites-available/posterg | grep "root "
# Should show: root /var/www/posterg/public;
```

If wrong:
```bash
sudo nano /etc/nginx/sites-available/posterg
# Fix the root directive
sudo systemctl reload nginx
```

### Database errors

**Cause:** Wrong permissions on database file

**Fix:**
```bash
ssh posterg
sudo chown www-data:posterg /var/www/posterg/storage/test.db
sudo chmod 660 /var/www/posterg/storage/test.db
```

### Admin upload errors

**Cause:** Upload directories not writable

**Fix:**
```bash
ssh posterg
sudo chmod 775 /var/www/posterg/public/admin/data
sudo find /var/www/posterg/public/admin/data -type d -exec chmod 775 {} \;
```

### Private files still accessible

**Cause:** Nginx serving from wrong directory

**Fix:** Verify nginx DocumentRoot and reload

---

## Rollback Procedure

If you need to go back to the old structure:

```bash
# 1. SSH to server
ssh posterg

# 2. Restore old nginx config
sudo nano /etc/nginx/sites-available/posterg
# Change: root /var/www/posterg/public;
# To:     root /var/www/html;
# Change: location ^~ /admin/
# To:     location ^~ /formulaire/

# 3. Reload nginx
sudo systemctl reload nginx

# 4. Verify
curl -I https://posterg.erg.be/
```

Your old site should work immediately (as long as you didn't delete `/var/www/html/`).

---

## Quick Reference

| Task | Command |
|------|---------|
| Deploy files | `just deploy` |
| Deploy nginx | `just deploy-nginx` |
| Deploy database | `just deploy-database` |
| Check status | `just server-status` |
| View logs | `just server-logs` |

---

## Success Checklist

- [ ] `/var/www/posterg/` created with correct permissions
- [ ] Files deployed with `just deploy`
- [ ] Nginx config deployed with `just deploy-nginx`
- [ ] Permissions fixed with `deploy-production.sh`
- [ ] Nginx reloaded successfully
- [ ] Site accessible at https://posterg.erg.be/
- [ ] Admin accessible at https://posterg.erg.be/admin/
- [ ] Private files return 404 (security verified)
- [ ] Database working (can view theses)
- [ ] Search working
- [ ] Old `/var/www/html/` kept as backup

---

**After deployment, your site will be significantly more secure!** 🔒