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:

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:

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

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:

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:

sudo systemctl reload nginx

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

Check status:

sudo systemctl status nginx
# Should show "active (running)"

Exit server:

exit

---

Step 6: Verify Deployment

From your local machine:

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:

# 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:

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:

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:

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

# 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:

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

If wrong:

sudo nano /etc/nginx/sites-available/posterg
# Fix the root directive
sudo systemctl reload nginx

Database errors

Cause: Wrong permissions on database file

Fix:

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:

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:

# 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! 🔒