PostERG/xamxam
1
0
Fork 0
mirror of https://codeberg.org/PostERG/xamxam.git synced 2026-09-25 01:53:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: align deployment/setup docs with current code

Browse Source 
- 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.
This commit is contained in:
Pontoporeia
2026-09-18 16:26:49 +02:00
parent 64fd92b913
commit 0e009c49d4
6 changed files with 220 additions and 393 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nginx/docs/QUICK_REFERENCE.md
+78 -181
View File
@@ -1,41 +1,40 @@
# Nginx Quick Reference - Post-ERG
# Nginx Quick Reference — XAMXAM
## Setup Commands
Command reference for the XAMXAM nginx configuration.
## Deploy the config
```bash
# Copy nginx config
sudo cp nginx/xamxam.conf /etc/nginx/sites-available/xamxam
sudo ln -s /etc/nginx/sites-available/xamxam /etc/nginx/sites-enabled/
# From your local machine: uploads nginx/xamxam.conf + scripts/deploy-server.sh,
# installs the config, fixes permissions, validates (nginx -t) and reloads.
just deploy-nginx
```
Manual alternative (on the server, as root):
```bash
sudo cp /tmp/xamxam.conf /etc/nginx/sites-available/xamxam
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
sudo nginx -t && sudo systemctl reload nginx
```
## Common Operations
## Admin authentication
### Password Management
The admin panel is protected by the application's **PHP session auth**
(`src/AdminAuth.php`), **not** by nginx Basic-auth/htpasswd. There is no
`.htpasswd` file — manage the admin password in the admin panel at
`/admin/parametres` → Account tab. See [`PHP_AUTH_LAYER.md`](PHP_AUTH_LAYER.md).
To reset the password from the shell, store a bcrypt hash in the DB:
```bash
# Interactive menu (recommended)
sudo bash /tmp/manage-admin-users.sh
# Or manual commands:
# Add new user
sudo htpasswd /etc/nginx/.htpasswd-xamxam username
# Change password for existing user
sudo htpasswd /etc/nginx/.htpasswd-xamxam username
# Remove user
sudo htpasswd -D /etc/nginx/.htpasswd-xamxam username
# List all users
sudo cut -d: -f1 /etc/nginx/.htpasswd-xamxam
ssh xamxam
HASH=$(sudo -u www-data php -r "echo password_hash('NEWPASSWORD', PASSWORD_DEFAULT);")
# then insert into site_settings.admin_password_hash (see PHP_AUTH_LAYER.md)
```
### Nginx Control
## Nginx control
```bash
# Test configuration
@@ -47,196 +46,94 @@ sudo systemctl reload nginx
# Restart nginx (brief downtime)
sudo systemctl restart nginx
# Stop nginx
sudo systemctl stop nginx
# Start nginx
sudo systemctl start nginx
# Check status
sudo systemctl status nginx
```
### View Logs
## Logs
The nginx config writes app-specific logs (paths set in the server block):
```bash
# Public site access log
sudo tail -f /var/log/nginx/xamxam_access.log
# Public site errors
sudo tail -f /var/log/nginx/xamxam_error.log
# SSL access log
sudo tail -f /var/log/nginx/xamxam_ssl_access.log
# Search for specific pattern
sudo grep "404" /var/log/nginx/xamxam_access.log
# Count requests by IP
sudo awk '{print $1}' /var/log/nginx/xamxam_access.log | sort | uniq -c | sort -nr | head
sudo tail -f /var/log/nginx/xamxam-nginx-access.log
sudo tail -f /var/log/nginx/xamxam-nginx-error.log
sudo tail -f /var/log/nginx/xamxam-ssl_access.log
```
### SSL/HTTPS
## SSL / HTTPS
```bash
# Get SSL certificate (Let's Encrypt)
sudo certbot --nginx -d xamxam.erg.be -d www.xamxam.erg.be
# Renew certificates
sudo certbot renew
# Check certificate expiry
sudo certbot certificates
# Test auto-renewal
sudo certbot renew --dry-run
```
SSL/TLS is terminated by an **upstream reverse proxy**; this nginx listens on
HTTP (port 80) and `Strict-Transport-Security` is set by the config. No
Let's Encrypt/certbot step is needed here. (Only relevant if you later serve
TLS directly.)
## Testing
### Test Admin Authentication
```bash
# Should require password (returns 401)
# Public site: expect 200
curl -I https://xamxam.erg.be/
# Admin: expect 200 (login page, PHP-layer auth) or 302 to /admin/login.php
curl -I https://xamxam.erg.be/admin/
# With authentication
curl -u admin:password https://xamxam.erg.be/admin/
```
### Test Rate Limiting
```bash
# Should show increasing 429 responses after limit
for i in {1..50}; do
curl -s -o /dev/null -w "%{http_code}\n" https://xamxam.erg.be/
done
```
### Test File Protection
```bash
# Should return 403
# File protection: expect 404/403
curl -I https://xamxam.erg.be/storage/xamxam.db
curl -I https://xamxam.erg.be/shared/Database.php
curl -I https://xamxam.erg.be/src/Database.php
curl -I https://xamxam.erg.be/.env
```
### Test Security Headers
```bash
# Check all security headers
curl -I https://xamxam.erg.be/ 2>&1 | grep -E "X-|Strict-Transport|Referrer|Permissions"
```
## Troubleshooting
### Common Issues
### 502 Bad Gateway
**403 Forbidden on admin**
```bash
# Check htpasswd file exists
sudo ls -l /etc/nginx/.htpasswd-xamxam
# Check permissions
sudo chmod 644 /etc/nginx/.htpasswd-xamxam
# Check / restart PHP-FPM (8.4)
sudo systemctl status php8.4-fpm
sudo systemctl restart php8.4-fpm
sudo tail /var/log/php8.4-fpm.log
```
**502 Bad Gateway**
### Configuration errors
```bash
# Check PHP-FPM status
sudo systemctl status php8.2-fpm
# Restart PHP-FPM
sudo systemctl restart php8.2-fpm
# Check PHP-FPM logs
sudo tail /var/log/php8.2-fpm.log
```
**Configuration errors**
```bash
# Test config and show errors
sudo nginx -t
# Check nginx error log
sudo tail -50 /var/log/nginx/error.log
```
### Emergency Recovery
### 403 Forbidden / permission issues
```bash
# Disable password protection temporarily
sudo nano /etc/nginx/sites-available/xamxam
# Comment out these lines in /admin/ location:
# auth_basic "Admin Access - Post-ERG";
# auth_basic_user_file /etc/nginx/.htpasswd-xamxam;
The nginx config blocks sensitive paths by design (`.db`, `.env`, `src/`,
`storage/`, `templates/`, etc.). If something legitimately 403s, check the file
ownership/group and that `www-data` is in the `xamxam` group, then re-apply
perms with `just deploy-nginx` (runs `deploy-server.sh`).
# Reload nginx
sudo nginx -t && sudo systemctl reload nginx
```
## Rate limits (current settings)
## Performance Monitoring
| Zone | Rate |
|------|------|
| `general` | 30 r/min |
| `search` | 30 r/min |
| `admin` | 300 r/min (burst 30) |
```bash
# Check active connections
sudo ss -tulpn | grep nginx
To adjust, edit the `limit_req_zone` / `limit_req` lines in `nginx/xamxam.conf`:
# Monitor nginx processes
watch -n 1 'ps aux | grep nginx'
# Check request rate
sudo tail -f /var/log/nginx/xamxam_access.log | pv -l -r > /dev/null
# Disk usage of logs
sudo du -sh /var/log/nginx/*
```
## Maintenance
```bash
# Rotate logs manually
sudo nginx -s reopen
# Clear old logs (keep last 7 days)
sudo find /var/log/nginx -name "*.log" -mtime +7 -delete
# Backup configuration
sudo cp /etc/nginx/sites-available/xamxam /etc/nginx/sites-available/xamxam.backup.$(date +%Y%m%d)
# Backup password file
sudo cp /etc/nginx/.htpasswd-xamxam /etc/nginx/.htpasswd-xamxam.backup.$(date +%Y%m%d)
```
## Security Checklist
- [ ] Admin password set: `sudo ls -l /etc/nginx/.htpasswd-xamxam`
- [ ] SSL enabled: `curl -I https://xamxam.erg.be/`
- [ ] Database blocked: `curl -I https://xamxam.erg.be/storage/xamxam.db`
- [ ] Shared directory blocked: `curl -I https://xamxam.erg.be/shared/Database.php`
- [ ] Rate limiting working: Test with curl loop
- [ ] Security headers present: `curl -I https://xamxam.erg.be/ | grep X-`
- [ ] Logs accessible: `sudo tail /var/log/nginx/xamxam_access.log`
## Configuration Paths
- **Nginx config**: `/etc/nginx/sites-available/xamxam`
- **Password file**: `/etc/nginx/.htpasswd-xamxam`
- **SSL certificates**: `/etc/letsencrypt/live/xamxam.erg.be/`
- **Access logs**: `/var/log/nginx/xamxam_access.log`
- **Error logs**: `/var/log/nginx/xamxam_error.log`
- **PHP-FPM config**: `/etc/php/8.2/fpm/pool.d/www.conf`
- **PHP-FPM socket**: `/var/run/php/php8.2-fpm.sock`
## Rate Limits (Current Settings)
- **General requests**: 30 requests/minute
- **Search endpoint**: 30 requests/minute (burst: 10)
- **Admin panel**: 10 requests/minute (burst: 5)
To adjust, edit these lines in nginx config:
```nginx
limit_req_zone $binary_remote_addr zone=general:10m rate=30r/m;
limit_req_zone $binary_remote_addr zone=search:10m rate=30r/m;
limit_req_zone $binary_remote_addr zone=admin:10m rate=10r/m;
limit_req_zone $binary_remote_addr zone=admin:10m rate=300r/m;
```
## Configuration paths
- **Nginx config**: `/etc/nginx/sites-available/xamxam` → `sites-enabled/xamxam`
- **PHP-FPM pool**: `/etc/php/8.4/fpm/pool.d/www.conf`
- **PHP-FPM socket**: `/var/run/php/php8.4-fpm.sock`
## Security checklist
- [ ] Admin password set (in `/admin/parametres`, by default set only once / fresh DB is open)
- [ ] Public site reachable: `curl -I https://xamxam.erg.be/`
- [ ] DB / source blocked: `curl -I https://xamxam.erg.be/storage/xamxam.db`
- [ ] Rate limiting working (curl loop yields 429 after limit)
- [ ] Security headers present: `curl -I https://xamxam.erg.be/ | grep X-`
- [ ] Logs exist: `sudo tail /var/log/nginx/xamxam-nginx-error.log`