docs: align deployment/setup docs with current code

- nginx/docs/PRODUCTION_DEPLOYMENT.md: drop stale htpasswd/Basic-auth model, manual server-side deploy step, /var/www/posterg paths and hardcoded IP; describe the PHP-layer AdminAuth, automated 📋 Deploying nginx configuration… xamxam.conf sent 145 bytes received 125 bytes 540.00 bytes/sec total size is 10,012 speedup is 37.08 deploy-server.sh sent 143 bytes received 113 bytes 512.00 bytes/sec total size is 8,519 speedup is 33.28, and what deploy-server.sh actually does. - nginx/docs/QUICK_REFERENCE.md: replace htpasswd user management with AdminAuth guidance; fix php8.2->php8.4, log paths, admin rate limit (300r/m), socket path. - nginx/README.md, nginx/SETUP.md: note 📋 Deploying nginx configuration… xamxam.conf sent 145 bytes received 125 bytes 540.00 bytes/sec total size is 10,012 speedup is 37.08 deploy-server.sh sent 143 bytes received 113 bytes 170.67 bytes/sec total size is 8,519 speedup is 33.28 automates deploy-server.sh (no manual ssh/sudo step). - docs/deployment.md: correct deploy-code scope (code-only, no --chown), fix the /var/log/xamxam provisioning step (deploy-server.sh via deploy-nginx, not deploy-code), document the setup-server.sh prerequisite and fresh-box caveat. - README.md: replace the incomplete manual first-time setup snippet with the real setup-server.sh + provision-server flow and a fresh-box caveat.
2026-09-25 01:53:03 +02:00 · 2026-09-18 16:26:49 +02:00
parent 64fd92b913
commit 0e009c49d4
6 changed files with 220 additions and 393 deletions
@@ -1,210 +1,102 @@
-# Production Deployment Guide - Post-ERG
+# Production Deployment Guide

-This guide covers deploying the production nginx configuration with proper security and permissions.
+Deploying the XAMXAM production nginx configuration and administering the site.

-## 🎯 Overview
+## Overview

- **Server**: xamxam.erg.be (internal IP: 192.168.6.125)
+- **Host**: `xamxam` (SSH alias), app root `/var/www/xamxam/`
 - **PHP Version**: 8.4
- **SSL/TLS**: Handled by upstream reverse proxy
- **Document Root**: `/var/www/xamxam/public/`
+- **SSL/TLS**: Terminated by an upstream reverse proxy (nginx itself listens on 80)
+- **Document Root**: `/var/www/xamxam/public/` (deployed flat, not under `app/`)
+- **Web / FPM user**: `www-data`, app group: `xamxam`

-## 🚀 Quick Deployment
+## Quick deployment (recommended)

-From your local machine:
+Everything is orchestrated from your local machine through the justfile. `just deploy-nginx`
+uploads both `nginx/xamxam.conf` and `scripts/deploy-server.sh` to the server, runs the
+latter as root (installing the config, fixing permissions, testing and reloading nginx and
+php-fpm), then cleans up the remote temp files:

 ```bash
-# Deploy nginx config and upload deployment script
 just deploy-nginx
-
-# Then on the server:
-ssh xamxam
-sudo bash /tmp/deploy-server.sh
-sudo systemctl reload nginx
 ```

-This uploads:
- `nginx/xamxam.conf` → `/tmp/xamxam.conf`
- `scripts/deploy-server.sh` → `/tmp/deploy-server.sh`
+No manual server-side step is needed — the recipe already does it. For a full
+code + dependencies + migrations deploy, run `just deploy` (which includes
+`deploy-nginx`). See [`../../docs/deployment.md`](../../docs/deployment.md).

-## 📋 Step-by-Step Deployment
+What `scripts/deploy-server.sh` does (as root):

-### 1. Set Up Admin Password (First Time Only)
+- Fixes ownership to `www-data:xamxam` across `/var/www/xamxam/`
+- Sets directory permissions to **2775** (setgid) and files to **664**
+- Locks SQLite databases (and WAL/SHM sidecars) to **660**; `.env` to **640**
+- Creates writable cache / upload-tmp / `var/{cache,logs,tmp}` dirs for php-fpm
+- Provisions `/var/log/xamxam/` (app log dir) and `/var/backups/xamxam/` (backups)
+- Installs a php-fpm session-GC tuning file (`zz-xamxam-session.ini`)
+- Installs `nginx/xamxam.conf` into `sites-available`, symlinks it, backs up old
+  uploads, prunes old backups, validates with `nginx -t`, and reloads nginx + php-fpm
+
+## Admin authentication
+
+The admin panel is protected by the application's **PHP session auth layer**
+(`src/AdminAuth.php`), **not** by nginx `htpasswd`/Basic-auth. The user supplies a
+single password on `/admin/login.php`; no username, no `/etc/nginx/.htpasswd`.
+
+Configure the admin password in the admin panel at `/admin/parametres` → Account
+tab (a fresh DB starts unauthenticated until a password is set). See
+[`PHP_AUTH_LAYER.md`](PHP_AUTH_LAYER.md) for the full authentication details.
+
+## Verification
+
+After a successful deploy:

 ```bash
-ssh xamxam
-sudo htpasswd -c /etc/nginx/.htpasswd-xamxam admin
-# Enter a strong password when prompted
+curl -I https://xamxam.erg.be/               # expect 200
+curl -I https://xamxam.erg.be/admin/         # expect 200 (login page / 302 to it)
+curl -I https://xamxam.erg.be/storage/xamxam.db   # expect 404 / 403 (blocked)
+curl -I https://xamxam.erg.be/src/Database.php    # expect 404 / 403 (blocked)
+just deploy-verify-permissions               # expect "All permissions OK"
 ```

-**💡 Tip**: Generate a strong password:
-```bash
-openssl rand -base64 32
-```
+Security headers (`X-Frame-Options`, `X-Content-Type-Options`,
+`Strict-Transport-Security`, `Referrer-Policy`, `Permissions-Policy`,
+`Content-Security-Policy`) are emitted by the nginx config; see
+[`SECURITY_HEADERS.md`](SECURITY_HEADERS.md).

-### 2. Deploy Configuration
-
-```bash
-# From your local machine
-just deploy-nginx
-
-# On the server
-sudo bash /tmp/deploy-server.sh
-sudo systemctl reload nginx
-```
-
-The script will:
- ✅ Fix file permissions (set to www-data:xamxam)
- ✅ Install nginx configuration
- ✅ Test nginx configuration
- ✅ Check PHP-FPM status
-
-## 🔧 Manual Deployment (Alternative)
-
-### Step 1: Fix Permissions
-
-```bash
-ssh xamxam
-
-# Set correct ownership
-sudo chown -R www-data:xamxam /var/www/xamxam/
-
-# Set directory permissions
-sudo find /var/www/posterg -type d -exec chmod 755 {} \;
-
-# Set file permissions
-sudo find /var/www/posterg -type f -exec chmod 644 {} \;
-
-# Make storage writable
-sudo chmod 775 /var/www/xamxam/storage
-
-# Protect database
-sudo chmod 660 /var/www/xamxam/storage/test.db
-sudo chown www-data:xamxam /var/www/xamxam/storage/test.db
-```
-
-### Step 2: Deploy Nginx Config
-
-```bash
-# Copy config
-sudo cp /tmp/xamxam.conf /etc/nginx/sites-available/xamxam
-
-# Enable site and disable default
-sudo ln -sf /etc/nginx/sites-available/xamxam /etc/nginx/sites-enabled/xamxam
-sudo rm -f /etc/nginx/sites-enabled/default
-
-# Test and reload
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-## 🧪 Testing
-
-### Test Public Site
-
-```bash
-# Should return 200 OK
-curl -I https://xamxam.erg.be/
-```
-
-### Test Admin Protection
-
-```bash
-# Should return 401 Unauthorized
-curl -I https://xamxam.erg.be/admin/
-
-# With credentials
-curl -u admin:your_password https://xamxam.erg.be/admin/
-```
-
-### Test File Protection
-
-```bash
-# Should return 403 Forbidden
-curl -I https://xamxam.erg.be/storage/test.db
-curl -I https://xamxam.erg.be/src/Database.php
-curl -I https://xamxam.erg.be/config/bootstrap.php
-```
-
-### Test Security Headers
-
-```bash
-curl -I https://xamxam.erg.be/ | grep -E "X-Frame|X-Content|Strict-Transport"
-```
-
-## 🔍 Troubleshooting
-
-### Still Getting 403 Forbidden
-
-**Check file permissions:**
-```bash
-ls -la /var/www/xamxam/public/index.php
-groups www-data  # Should include xamxam
-```
+## Troubleshooting

 ### 502 Bad Gateway

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

-### Admin Password Not Working
+### Nginx config error

 ```bash
-sudo htpasswd /etc/nginx/.htpasswd-xamxam admin
-```
-
-## 📊 Monitoring
-
-```bash
-# Watch logs
-sudo tail -f /var/log/nginx/xamxam_access.log
-sudo tail -f /var/log/nginx/xamxam_error.log
-
-# Check status
-sudo systemctl status nginx
-```
-
-## 🔒 Security Checklist
-
-After deployment, verify:
-
- [ ] Public site accessible at https://xamxam.erg.be/
- [ ] Admin panel requires password
- [ ] Database files return 403 Forbidden
- [ ] Source files return 403 Forbidden
- [ ] Security headers present
- [ ] PHP-FPM running
-
-## 🔄 Updating the Site
-
-```bash
-# Deploy code changes
-just deploy
-
-# Reload nginx if config changed
-ssh xamxam "sudo systemctl reload nginx"
-```
-
-## 🆘 Emergency Recovery
-
-```bash
-# Restore default nginx config
 ssh xamxam
-sudo rm /etc/nginx/sites-enabled/xamxam
-sudo systemctl reload nginx
-
-# Reset permissions
-sudo chown -R www-data:xamxam /var/www/xamxam/
-sudo find /var/www/posterg -type d -exec chmod 755 {} \;
-sudo find /var/www/posterg -type f -exec chmod 644 {} \;
+sudo nginx -t
 ```

---
+### Still getting 403 Forbidden

-**See also:**
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command reference
- [ADMIN_USERS.md](ADMIN_USERS.md) - User management
- [SECURITY_HEADERS.md](SECURITY_HEADERS.md) - Security headers
+Check ownership/group and that `www-data` is a member of the `xamxam` group:
+
+```bash
+ls -la /var/www/xamxam/public/index.php
+groups www-data          # should include xamxam
+```
+
+If permissions are wrong, re-run the permission-fixing deploy script:
+
+```bash
+just deploy-nginx        # re-applies deploy-server.sh (perms + config)
+```
+
+## See also
+
+- [`QUICK_REFERENCE.md`](QUICK_REFERENCE.md) — command reference
+- [`PHP_AUTH_LAYER.md`](PHP_AUTH_LAYER.md) — admin authentication
+- [`SECURITY_HEADERS.md`](SECURITY_HEADERS.md) — security headers
+- [`../../docs/deployment.md`](../../docs/deployment.md) — full deployment, backups, rollback