# Nginx Quick Reference — XAMXAM

Command reference for the XAMXAM nginx configuration.

## Deploy the config

```bash
# 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
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`](PHP_AUTH_LAYER.md).

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

```bash
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

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

```bash
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

```bash
# 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

```bash
# 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

```bash
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`:

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