xamxam/nginx/docs/QUICK_REFERENCE.md

Nginx Quick Reference — XAMXAM

Command reference for the XAMXAM nginx configuration.

Deploy the config

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

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
sudo nginx -t && sudo systemctl reload nginx

Admin authentication

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.

To reset the password from the shell, store a bcrypt hash in the DB:

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

# Test configuration
sudo nginx -t

# Reload configuration (no downtime)
sudo systemctl reload nginx

# Restart nginx (brief downtime)
sudo systemctl restart nginx

# Check status
sudo systemctl status nginx

Logs

The nginx config writes app-specific logs (paths set in the server block):

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/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

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

# File protection: expect 404/403
curl -I https://xamxam.erg.be/storage/xamxam.db
curl -I https://xamxam.erg.be/src/Database.php
curl -I https://xamxam.erg.be/.env

Troubleshooting

502 Bad Gateway

# 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

Configuration errors

sudo nginx -t
sudo tail -50 /var/log/nginx/error.log

403 Forbidden / permission issues

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).

Rate limits (current settings)

Zone	Rate
general	30 r/min
search	30 r/min
admin	300 r/min (burst 30)

To adjust, edit the limit_req_zone / limit_req lines in nginx/xamxam.conf:

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=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