mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 19:19:19 +02:00
Consolidate nginx docs and scripts, update paths
This commit is contained in:
Pontoporeia
275
nginx/docs/ADMIN_USERS.md
Normal file
275
nginx/docs/ADMIN_USERS.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Managing Admin Users - Post-ERG
|
||||
|
||||
Quick guide to manage admin users for the Post-ERG admin panel.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Commands
|
||||
|
||||
### Interactive Menu (Recommended)
|
||||
|
||||
```bash
|
||||
# From your local machine
|
||||
just manage-admin-users
|
||||
|
||||
# Then on the server
|
||||
ssh posterg
|
||||
sudo bash /tmp/manage-admin-users.sh
|
||||
```
|
||||
|
||||
This gives you an interactive menu to:
|
||||
1. List all users
|
||||
2. Add new user
|
||||
3. Change user password
|
||||
4. Delete user
|
||||
5. Reset all (start fresh)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Manual Commands
|
||||
|
||||
### List Current Users
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo cut -d: -f1 /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
### Change Password for Existing User
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg username_here
|
||||
```
|
||||
|
||||
You'll be prompted to enter the new password twice.
|
||||
|
||||
### Add New User
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg new_username
|
||||
```
|
||||
|
||||
### Delete User
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd -D /etc/nginx/.htpasswd-posterg username_to_delete
|
||||
```
|
||||
|
||||
### Reset Everything (Start Fresh)
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd -c /etc/nginx/.htpasswd-posterg new_username
|
||||
```
|
||||
|
||||
⚠️ **Warning:** The `-c` flag creates a new file, deleting all existing users!
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deploy Management Script
|
||||
|
||||
To upload the interactive management script to the server:
|
||||
|
||||
```bash
|
||||
# From your local machine
|
||||
just manage-admin-users
|
||||
|
||||
# Or manually:
|
||||
rsync -v scripts/manage-admin-users.sh posterg:/tmp/manage-admin-users.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Current Setup
|
||||
|
||||
After deployment, your admin panel has:
|
||||
- **URL:** https://posterg.erg.be/admin/
|
||||
- **Current user:** `test_posterg_22@`
|
||||
- **Password:** Set during initial deployment
|
||||
|
||||
---
|
||||
|
||||
## 💡 Common Scenarios
|
||||
|
||||
### Scenario 1: Change Current Password
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg test_posterg_22@
|
||||
# Enter new password when prompted
|
||||
```
|
||||
|
||||
### Scenario 2: Change Username
|
||||
|
||||
Since you can't rename users, you need to:
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
# Add new user
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg new_username
|
||||
# Delete old user
|
||||
sudo htpasswd -D /etc/nginx/.htpasswd-posterg test_posterg_22@
|
||||
```
|
||||
|
||||
### Scenario 3: Forgot Username
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo cut -d: -f1 /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
### Scenario 4: Multiple Admins
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
# Add second admin
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg admin2
|
||||
# Add third admin
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg admin3
|
||||
```
|
||||
|
||||
All users can log into `/admin/` with their own credentials.
|
||||
|
||||
### Scenario 5: Start Over with New Username
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
# This will DELETE ALL existing users and create a new one
|
||||
sudo htpasswd -c /etc/nginx/.htpasswd-posterg new_admin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
After changing users/passwords:
|
||||
|
||||
```bash
|
||||
# Test that password is required
|
||||
curl -I https://posterg.erg.be/admin/
|
||||
# Should return: 401 Unauthorized
|
||||
|
||||
# Test with credentials
|
||||
curl -u username:password https://posterg.erg.be/admin/
|
||||
# Should return: 200 OK
|
||||
```
|
||||
|
||||
No nginx reload needed - changes take effect immediately!
|
||||
|
||||
---
|
||||
|
||||
## 📊 Password File Details
|
||||
|
||||
**Location:** `/etc/nginx/.htpasswd-posterg`
|
||||
|
||||
**Format:** Standard Apache htpasswd format
|
||||
```
|
||||
username:$apr1$encrypted_password_hash
|
||||
```
|
||||
|
||||
**Permissions:**
|
||||
```bash
|
||||
-rw-r--r-- root root /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Tips
|
||||
|
||||
1. **Use Strong Passwords**
|
||||
```bash
|
||||
# Generate a strong password
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
2. **Avoid Common Usernames**
|
||||
- ❌ Bad: `admin`, `administrator`, `root`
|
||||
- ✅ Good: `posterg_admin`, `erg_webmaster`
|
||||
|
||||
3. **Regular Password Changes**
|
||||
- Change passwords every 3-6 months
|
||||
- Change immediately if compromised
|
||||
|
||||
4. **Monitor Access**
|
||||
```bash
|
||||
# Check who's accessing the admin panel
|
||||
ssh posterg
|
||||
sudo grep "admin" /var/log/nginx/posterg_access.log
|
||||
```
|
||||
|
||||
5. **Backup Password File**
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo cp /etc/nginx/.htpasswd-posterg /etc/nginx/.htpasswd-posterg.backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### "401 Unauthorized" even with correct password
|
||||
|
||||
**Check file exists:**
|
||||
```bash
|
||||
ssh posterg
|
||||
ls -la /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
**Verify user exists:**
|
||||
```bash
|
||||
sudo cat /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
**Check nginx config:**
|
||||
```bash
|
||||
sudo grep -A 5 "auth_basic" /etc/nginx/sites-available/posterg
|
||||
```
|
||||
|
||||
### Can't change password - "command not found"
|
||||
|
||||
**Install apache2-utils:**
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo apt update
|
||||
sudo apt install apache2-utils
|
||||
```
|
||||
|
||||
### Password file got deleted
|
||||
|
||||
**Recreate it:**
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd -c /etc/nginx/.htpasswd-posterg new_admin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Quick Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| **Interactive menu** | `sudo bash /tmp/manage-admin-users.sh` |
|
||||
| **List users** | `sudo cut -d: -f1 /etc/nginx/.htpasswd-posterg` |
|
||||
| **Change password** | `sudo htpasswd /etc/nginx/.htpasswd-posterg username` |
|
||||
| **Add user** | `sudo htpasswd /etc/nginx/.htpasswd-posterg newuser` |
|
||||
| **Delete user** | `sudo htpasswd -D /etc/nginx/.htpasswd-posterg username` |
|
||||
| **Reset all** | `sudo htpasswd -c /etc/nginx/.htpasswd-posterg newuser` |
|
||||
| **Generate password** | `openssl rand -base64 32` |
|
||||
|
||||
---
|
||||
|
||||
## ✅ After Making Changes
|
||||
|
||||
No action needed! Changes to the password file take effect immediately.
|
||||
|
||||
You can verify with:
|
||||
```bash
|
||||
curl -u username:password https://posterg.erg.be/admin/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Store passwords securely using a password manager! 🔐
|
||||
38
nginx/docs/HTACCESS_TO_NGINX.md
Normal file
38
nginx/docs/HTACCESS_TO_NGINX.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# `.htaccess` → nginx migration
|
||||
|
||||
> **Problem:** `public/admin/.htaccess` contained Apache-specific security
|
||||
> directives that nginx **silently ignores**. None of the rules were active
|
||||
> in production.
|
||||
|
||||
> **Status:** Migrated into `nginx/posterg.conf`
|
||||
|
||||
---
|
||||
|
||||
## Rules migrated into `nginx/posterg.conf`
|
||||
|
||||
| Apache `.htaccess` rule | nginx equivalent | Location |
|
||||
|---|---|---|
|
||||
| `Header always set X-Frame-Options "SAMEORIGIN"` | `add_header X-Frame-Options "SAMEORIGIN" always;` | main `server` block (already present) |
|
||||
| `Header always set X-Content-Type-Options "nosniff"` | `add_header X-Content-Type-Options "nosniff" always;` | main `server` block (already present) |
|
||||
| `Header always set X-XSS-Protection "1; mode=block"` | **Intentionally omitted** — deprecated & counterproductive; see `SECURITY_HEADERS.md` | — |
|
||||
| `Header always set Referrer-Policy "strict-origin-when-cross-origin"` | `add_header Referrer-Policy "strict-origin-when-cross-origin" always;` | main `server` block (already present) |
|
||||
| `Header always set Content-Security-Policy "..."` | `add_header Content-Security-Policy "..." always;` | `/admin/` location block (**added**) |
|
||||
| `Options -Indexes` | `autoindex off;` | `/admin/` location block (**added**; nginx default is off, explicit for clarity) |
|
||||
| `<FilesMatch "^\."> Require all denied` | `location ~ /\.(?!well-known).*` deny | main `server` block (already present) |
|
||||
| `<FilesMatch "(composer\.(json\|lock)\|error\.log)$"> Require all denied` | `location ~* \.(md\|txt\|sql\|sh\|json\|gitignore)$` deny + `location ~* \.log$` deny | main `server` block (`log` rule **added**) |
|
||||
| `php_flag display_errors Off` | Handled by `config/bootstrap.php` (`ini_set('display_errors', '0')`) | PHP |
|
||||
| `php_flag log_errors On` | Handled by `config/bootstrap.php` (`ini_set('log_errors', '1')`) | PHP |
|
||||
| `php_value error_log error.log` | Handled by `config/bootstrap.php`; should use absolute path (item #9) | PHP |
|
||||
|
||||
---
|
||||
|
||||
## Status of `public/admin/.htaccess`
|
||||
|
||||
The file is now **dead code** on this nginx server. It has been left in place
|
||||
(harmless) so it would still work if the project were ever tested behind Apache
|
||||
(e.g., `php -S` built-in server doesn't read it either). All security rules it
|
||||
previously attempted to set are now enforced by nginx directly.
|
||||
|
||||
---
|
||||
|
||||
*Added: 2026-02-08 — security item #6*
|
||||
114
nginx/docs/PHP_AUTH_LAYER.md
Normal file
114
nginx/docs/PHP_AUTH_LAYER.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# PHP Session Auth Layer — Admin Panel
|
||||
|
||||
> Addresses: **TODO item #2** (No PHP-level authentication in admin panel — 🔴 CRITICAL)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The admin panel uses **two independent authentication layers** with a single UX prompt:
|
||||
|
||||
| Layer | Mechanism | Configured by |
|
||||
|-------|-----------|---------------|
|
||||
| **1st** | nginx HTTP Basic Auth | `/etc/nginx/.htpasswd-posterg` (see `ADMIN_USERS.md`) |
|
||||
| **2nd** | PHP session guard (`src/AdminAuth.php`) | `config/admin_credentials.php` |
|
||||
|
||||
The user only sees **one prompt** (the browser Basic Auth dialog). PHP reads the
|
||||
same password from `$_SERVER['PHP_AUTH_PW']` and validates it independently with
|
||||
`password_verify`. On success it creates a session so subsequent requests skip
|
||||
the `password_verify` call.
|
||||
|
||||
---
|
||||
|
||||
## Why two layers?
|
||||
|
||||
nginx Basic Auth alone is a **single point of failure**:
|
||||
|
||||
- Reverse-proxy misconfiguration could expose admin routes directly.
|
||||
- Local development without the proxy leaves admin unprotected.
|
||||
- A misconfigured `auth_basic off` block (e.g., in a nested location) could bypass it.
|
||||
|
||||
The PHP session guard (`AdminAuth::requireLogin()`) is ~100 lines of PHP stdlib
|
||||
(`password_verify` + `session_regenerate_id`) with negligible attack surface.
|
||||
|
||||
## Authentication flow
|
||||
|
||||
```
|
||||
Browser → nginx Basic Auth dialog (username + password)
|
||||
│
|
||||
▼
|
||||
nginx validates against .htpasswd ──✗──▶ 401
|
||||
│ ✓
|
||||
▼
|
||||
PHP: AdminAuth::requireLogin()
|
||||
├─ session already live? ──✓──▶ proceed
|
||||
├─ $_SERVER['PHP_AUTH_PW'] set?
|
||||
│ └─ password_verify(PHP_AUTH_PW, ADMIN_PASSWORD_HASH)
|
||||
│ ├─ ✓ → create session → proceed (normal path)
|
||||
│ └─ ✗ → redirect to login form
|
||||
└─ neither → redirect to login form (proxy bypass)
|
||||
```
|
||||
|
||||
The login form (`/admin/login.php`) is a **fallback** for when the reverse proxy
|
||||
is absent. In normal production use the user never sees it.
|
||||
|
||||
---
|
||||
|
||||
## PHP auth setup (production)
|
||||
|
||||
1. Generate a bcrypt hash for the admin password:
|
||||
```bash
|
||||
php -r "echo password_hash('your-secret-password', PASSWORD_DEFAULT);"
|
||||
```
|
||||
|
||||
2. Create `config/admin_credentials.php` (outside the webroot, never committed):
|
||||
```php
|
||||
<?php
|
||||
define('ADMIN_PASSWORD_HASH', '$2y$12$<paste-hash-here>');
|
||||
```
|
||||
|
||||
3. The `bootstrap.php` auto-loads this file if it exists.
|
||||
|
||||
If `ADMIN_PASSWORD_HASH` is not defined (development / cli-server), the PHP
|
||||
auth layer is a **no-op** — nginx Basic Auth remains the sole guard.
|
||||
|
||||
---
|
||||
|
||||
## Session cookie hardening (TODO item #8)
|
||||
|
||||
`AdminAuth::startSession()` calls `session_set_cookie_params()` before
|
||||
`session_start()`, applying:
|
||||
|
||||
| Attribute | Value |
|
||||
|-----------|-------|
|
||||
| `HttpOnly` | `true` |
|
||||
| `SameSite` | `Strict` |
|
||||
| `Secure` | `true` (disabled on cli-server for dev) |
|
||||
| `Path` | `/admin` |
|
||||
| `Lifetime` | `0` (session cookie, expires on browser close) |
|
||||
|
||||
This replaces all direct `session_start()` calls in admin PHP files.
|
||||
|
||||
---
|
||||
|
||||
## Logout
|
||||
|
||||
A **Déconnexion** button is shown in the admin nav when `ADMIN_PASSWORD_HASH`
|
||||
is defined. It hits `/admin/logout.php` which destroys the PHP session.
|
||||
nginx Basic Auth invalidation requires closing the browser tab / window.
|
||||
|
||||
---
|
||||
|
||||
## Files changed
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `src/AdminAuth.php` | New — auth guard class |
|
||||
| `config/admin_credentials.php` | New — credential store (gitignored) |
|
||||
| `config/admin_credentials.example.php` | New — example / template |
|
||||
| `config/bootstrap.php` | Load credentials on startup |
|
||||
| `public/admin/*.php` | Replace `session_start()` with `AdminAuth::requireLogin()` |
|
||||
| `public/admin/actions/*.php` | Same |
|
||||
| `public/admin/login.php` | New — login form |
|
||||
| `public/admin/logout.php` | New — logout handler |
|
||||
| `public/admin/inc/head.php` | Logout button in nav |
|
||||
210
nginx/docs/PRODUCTION_DEPLOYMENT.md
Normal file
210
nginx/docs/PRODUCTION_DEPLOYMENT.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Production Deployment Guide - Post-ERG
|
||||
|
||||
This guide covers deploying the production nginx configuration with proper security and permissions.
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
- **Server**: posterg.erg.be (internal IP: 192.168.6.125)
|
||||
- **PHP Version**: 8.4
|
||||
- **SSL/TLS**: Handled by upstream reverse proxy
|
||||
- **Document Root**: `/var/www/posterg/public/`
|
||||
|
||||
## 🚀 Quick Deployment
|
||||
|
||||
From your local machine:
|
||||
|
||||
```bash
|
||||
# Deploy nginx config and upload deployment script
|
||||
just deploy-nginx
|
||||
|
||||
# Then on the server:
|
||||
ssh posterg
|
||||
sudo bash /tmp/deploy-server.sh
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
This uploads:
|
||||
- `nginx/posterg.conf` → `/tmp/posterg.conf`
|
||||
- `scripts/deploy-server.sh` → `/tmp/deploy-server.sh`
|
||||
|
||||
## 📋 Step-by-Step Deployment
|
||||
|
||||
### 1. Set Up Admin Password (First Time Only)
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo htpasswd -c /etc/nginx/.htpasswd-posterg admin
|
||||
# Enter a strong password when prompted
|
||||
```
|
||||
|
||||
**💡 Tip**: Generate a strong password:
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### 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:posterg)
|
||||
- ✅ Install nginx configuration
|
||||
- ✅ Test nginx configuration
|
||||
- ✅ Check PHP-FPM status
|
||||
|
||||
## 🔧 Manual Deployment (Alternative)
|
||||
|
||||
### Step 1: Fix Permissions
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
|
||||
# Set correct ownership
|
||||
sudo chown -R www-data:posterg /var/www/posterg/
|
||||
|
||||
# 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/posterg/storage
|
||||
|
||||
# Protect database
|
||||
sudo chmod 660 /var/www/posterg/storage/test.db
|
||||
sudo chown www-data:posterg /var/www/posterg/storage/test.db
|
||||
```
|
||||
|
||||
### Step 2: Deploy Nginx Config
|
||||
|
||||
```bash
|
||||
# Copy config
|
||||
sudo cp /tmp/posterg.conf /etc/nginx/sites-available/posterg
|
||||
|
||||
# Enable site and disable default
|
||||
sudo ln -sf /etc/nginx/sites-available/posterg /etc/nginx/sites-enabled/posterg
|
||||
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://posterg.erg.be/
|
||||
```
|
||||
|
||||
### Test Admin Protection
|
||||
|
||||
```bash
|
||||
# Should return 401 Unauthorized
|
||||
curl -I https://posterg.erg.be/admin/
|
||||
|
||||
# With credentials
|
||||
curl -u admin:your_password https://posterg.erg.be/admin/
|
||||
```
|
||||
|
||||
### Test File Protection
|
||||
|
||||
```bash
|
||||
# Should return 403 Forbidden
|
||||
curl -I https://posterg.erg.be/storage/test.db
|
||||
curl -I https://posterg.erg.be/src/Database.php
|
||||
curl -I https://posterg.erg.be/config/bootstrap.php
|
||||
```
|
||||
|
||||
### Test Security Headers
|
||||
|
||||
```bash
|
||||
curl -I https://posterg.erg.be/ | grep -E "X-Frame|X-Content|Strict-Transport"
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Still Getting 403 Forbidden
|
||||
|
||||
**Check file permissions:**
|
||||
```bash
|
||||
ls -la /var/www/posterg/public/index.php
|
||||
groups www-data # Should include posterg
|
||||
```
|
||||
|
||||
### 502 Bad Gateway
|
||||
|
||||
**Check PHP-FPM:**
|
||||
```bash
|
||||
sudo systemctl status php8.4-fpm
|
||||
sudo systemctl restart php8.4-fpm
|
||||
```
|
||||
|
||||
### Admin Password Not Working
|
||||
|
||||
```bash
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg admin
|
||||
```
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
```bash
|
||||
# Watch logs
|
||||
sudo tail -f /var/log/nginx/posterg_access.log
|
||||
sudo tail -f /var/log/nginx/posterg_error.log
|
||||
|
||||
# Check status
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
## 🔒 Security Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
- [ ] Public site accessible at https://posterg.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 posterg "sudo systemctl reload nginx"
|
||||
```
|
||||
|
||||
## 🆘 Emergency Recovery
|
||||
|
||||
```bash
|
||||
# Restore default nginx config
|
||||
ssh posterg
|
||||
sudo rm /etc/nginx/sites-enabled/posterg
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Reset permissions
|
||||
sudo chown -R www-data:posterg /var/www/posterg/
|
||||
sudo find /var/www/posterg -type d -exec chmod 755 {} \;
|
||||
sudo find /var/www/posterg -type f -exec chmod 644 {} \;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**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
|
||||
242
nginx/docs/QUICK_REFERENCE.md
Normal file
242
nginx/docs/QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Nginx Quick Reference - Post-ERG
|
||||
|
||||
## Setup Commands
|
||||
|
||||
```bash
|
||||
# Copy nginx config
|
||||
sudo cp nginx/posterg.conf /etc/nginx/sites-available/posterg
|
||||
sudo ln -s /etc/nginx/sites-available/posterg /etc/nginx/sites-enabled/
|
||||
sudo rm -f /etc/nginx/sites-enabled/default
|
||||
|
||||
# Test and reload
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Password Management
|
||||
|
||||
```bash
|
||||
# Interactive menu (recommended)
|
||||
sudo bash /tmp/manage-admin-users.sh
|
||||
|
||||
# Or manual commands:
|
||||
# Add new user
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg username
|
||||
|
||||
# Change password for existing user
|
||||
sudo htpasswd /etc/nginx/.htpasswd-posterg username
|
||||
|
||||
# Remove user
|
||||
sudo htpasswd -D /etc/nginx/.htpasswd-posterg username
|
||||
|
||||
# List all users
|
||||
sudo cut -d: -f1 /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
### Nginx Control
|
||||
|
||||
```bash
|
||||
# Test configuration
|
||||
sudo nginx -t
|
||||
|
||||
# Reload configuration (no downtime)
|
||||
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
|
||||
|
||||
```bash
|
||||
# Public site access log
|
||||
sudo tail -f /var/log/nginx/posterg_access.log
|
||||
|
||||
# Public site errors
|
||||
sudo tail -f /var/log/nginx/posterg_error.log
|
||||
|
||||
# SSL access log
|
||||
sudo tail -f /var/log/nginx/posterg_ssl_access.log
|
||||
|
||||
# Search for specific pattern
|
||||
sudo grep "404" /var/log/nginx/posterg_access.log
|
||||
|
||||
# Count requests by IP
|
||||
sudo awk '{print $1}' /var/log/nginx/posterg_access.log | sort | uniq -c | sort -nr | head
|
||||
```
|
||||
|
||||
### SSL/HTTPS
|
||||
|
||||
```bash
|
||||
# Get SSL certificate (Let's Encrypt)
|
||||
sudo certbot --nginx -d posterg.erg.be -d www.posterg.erg.be
|
||||
|
||||
# Renew certificates
|
||||
sudo certbot renew
|
||||
|
||||
# Check certificate expiry
|
||||
sudo certbot certificates
|
||||
|
||||
# Test auto-renewal
|
||||
sudo certbot renew --dry-run
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Admin Authentication
|
||||
|
||||
```bash
|
||||
# Should require password (returns 401)
|
||||
curl -I https://posterg.erg.be/admin/
|
||||
|
||||
# With authentication
|
||||
curl -u admin:password https://posterg.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://posterg.erg.be/
|
||||
done
|
||||
```
|
||||
|
||||
### Test File Protection
|
||||
|
||||
```bash
|
||||
# Should return 403
|
||||
curl -I https://posterg.erg.be/storage/posterg.db
|
||||
curl -I https://posterg.erg.be/shared/Database.php
|
||||
curl -I https://posterg.erg.be/.env
|
||||
```
|
||||
|
||||
### Test Security Headers
|
||||
|
||||
```bash
|
||||
# Check all security headers
|
||||
curl -I https://posterg.erg.be/ 2>&1 | grep -E "X-|Strict-Transport|Referrer|Permissions"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**403 Forbidden on admin**
|
||||
```bash
|
||||
# Check htpasswd file exists
|
||||
sudo ls -l /etc/nginx/.htpasswd-posterg
|
||||
|
||||
# Check permissions
|
||||
sudo chmod 644 /etc/nginx/.htpasswd-posterg
|
||||
```
|
||||
|
||||
**502 Bad Gateway**
|
||||
```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
|
||||
|
||||
```bash
|
||||
# Disable password protection temporarily
|
||||
sudo nano /etc/nginx/sites-available/posterg
|
||||
# Comment out these lines in /admin/ location:
|
||||
# auth_basic "Admin Access - Post-ERG";
|
||||
# auth_basic_user_file /etc/nginx/.htpasswd-posterg;
|
||||
|
||||
# Reload nginx
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## Performance Monitoring
|
||||
|
||||
```bash
|
||||
# Check active connections
|
||||
sudo ss -tulpn | grep nginx
|
||||
|
||||
# Monitor nginx processes
|
||||
watch -n 1 'ps aux | grep nginx'
|
||||
|
||||
# Check request rate
|
||||
sudo tail -f /var/log/nginx/posterg_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/posterg /etc/nginx/sites-available/posterg.backup.$(date +%Y%m%d)
|
||||
|
||||
# Backup password file
|
||||
sudo cp /etc/nginx/.htpasswd-posterg /etc/nginx/.htpasswd-posterg.backup.$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] Admin password set: `sudo ls -l /etc/nginx/.htpasswd-posterg`
|
||||
- [ ] SSL enabled: `curl -I https://posterg.erg.be/`
|
||||
- [ ] Database blocked: `curl -I https://posterg.erg.be/storage/posterg.db`
|
||||
- [ ] Shared directory blocked: `curl -I https://posterg.erg.be/shared/Database.php`
|
||||
- [ ] Rate limiting working: Test with curl loop
|
||||
- [ ] Security headers present: `curl -I https://posterg.erg.be/ | grep X-`
|
||||
- [ ] Logs accessible: `sudo tail /var/log/nginx/posterg_access.log`
|
||||
|
||||
## Configuration Paths
|
||||
|
||||
- **Nginx config**: `/etc/nginx/sites-available/posterg`
|
||||
- **Password file**: `/etc/nginx/.htpasswd-posterg`
|
||||
- **SSL certificates**: `/etc/letsencrypt/live/posterg.erg.be/`
|
||||
- **Access logs**: `/var/log/nginx/posterg_access.log`
|
||||
- **Error logs**: `/var/log/nginx/posterg_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;
|
||||
```
|
||||
43
nginx/docs/SECURITY_HEADERS.md
Normal file
43
nginx/docs/SECURITY_HEADERS.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Security Headers — nginx/posterg.conf
|
||||
|
||||
## Headers in use (main server block — all pages)
|
||||
|
||||
| Header | Value | Purpose |
|
||||
|--------|-------|---------|
|
||||
| `X-Frame-Options` | `SAMEORIGIN` | Prevent clickjacking |
|
||||
| `X-Content-Type-Options` | `nosniff` | Prevent MIME-type sniffing |
|
||||
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer leakage |
|
||||
| `Permissions-Policy` | `geolocation=(), microphone=(), camera=()` | Disable unused browser APIs |
|
||||
|
||||
## Headers in use (`/admin/` location block)
|
||||
|
||||
| Header | Value | Purpose |
|
||||
|--------|-------|---------|
|
||||
| `Content-Security-Policy` | `default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none';` | Restrict resource origins; block embedding |
|
||||
| `X-Robots-Tag` | `noindex, nofollow` | Prevent search-engine indexing of admin |
|
||||
|
||||
These were previously declared in `public/admin/.htaccess` as Apache
|
||||
`mod_headers` directives, which nginx silently ignores. They are now
|
||||
properly configured in `nginx/posterg.conf`.
|
||||
enforced directly; see `HTACCESS_TO_NGINX.md` for the full migration log.
|
||||
|
||||
## Intentionally omitted headers
|
||||
|
||||
### `X-XSS-Protection`
|
||||
|
||||
This header was **removed** (was `"1; mode=block"`).
|
||||
|
||||
**Why:** `X-XSS-Protection` is deprecated and removed from all modern browsers
|
||||
(Chrome 78+, Firefox never implemented it, Edge dropped it). Worse, the
|
||||
`mode=block` behaviour can be [actively exploited](https://portswigger.net/daily-swig/xss-protection-header-is-no-longer-supported-in-any-major-browser)
|
||||
to expose response bodies that would otherwise be blocked. Sending it provides
|
||||
no protection and may introduce risk.
|
||||
|
||||
**Correct mitigation:** a proper `Content-Security-Policy` header (now done for
|
||||
`/admin/`; public-page CSP is todo item #11).
|
||||
|
||||
## Pending headers
|
||||
|
||||
| Header | Scope | Status |
|
||||
|--------|-------|--------|
|
||||
| `Content-Security-Policy` | Public pages (non-admin) | ⏳ todo item #11 |
|
||||
152
nginx/docs/TEST_DATABASE_SETUP.md
Normal file
152
nginx/docs/TEST_DATABASE_SETUP.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Test Database Setup - Post-ERG
|
||||
|
||||
Guide for deploying the test database to production server.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Deploy
|
||||
|
||||
```bash
|
||||
just deploy-db
|
||||
```
|
||||
|
||||
This automatically:
|
||||
1. ✅ Checks remote DB doesn't exist (safety check)
|
||||
2. ✅ Uploads `storage/test.db` to the server
|
||||
3. ✅ Sets correct permissions (660, www-data:posterg)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Prerequisites (One-Time Setup)
|
||||
|
||||
### 1. Install PHP SQLite Extension
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo apt update
|
||||
sudo apt install php8.4-sqlite3
|
||||
sudo systemctl restart php8.4-fpm
|
||||
```
|
||||
|
||||
### 2. Verify Installation
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
php -m | grep sqlite3
|
||||
# Should output: pdo_sqlite, sqlite3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Complete Testing Workflow
|
||||
|
||||
### 1. Create Test Data Locally
|
||||
|
||||
```bash
|
||||
# Create empty test database from schema
|
||||
just init-db
|
||||
|
||||
# Or create with sample fixtures
|
||||
just fixtures
|
||||
```
|
||||
|
||||
### 2. Deploy Test Database
|
||||
|
||||
```bash
|
||||
just deploy-db
|
||||
```
|
||||
|
||||
### 3. Test the Site
|
||||
|
||||
Visit: https://posterg.erg.be/
|
||||
|
||||
### 4. Check What Database is Being Used
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
php -r "require_once '/var/www/posterg/src/Database.php'; echo 'Using: ' . Database::getInstance()->getDatabasePath() . PHP_EOL;"
|
||||
```
|
||||
|
||||
### 5. Switch Back to Production
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
rm /var/www/posterg/storage/test.db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Permissions Explained
|
||||
|
||||
```
|
||||
/var/www/posterg/storage/
|
||||
drwxrwxr-x www-data posterg # 775 - group writable
|
||||
|
||||
/var/www/posterg/storage/test.db
|
||||
-rw-rw---- www-data posterg # 660 - owner/group read/write
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "could not find driver"
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
sudo apt install php8.4-sqlite3
|
||||
sudo systemctl restart php8.4-fpm
|
||||
```
|
||||
|
||||
### "unable to open database file"
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
chown www-data:posterg /var/www/posterg/storage/test.db
|
||||
chmod 660 /var/www/posterg/storage/test.db
|
||||
chmod 775 /var/www/posterg/storage/
|
||||
```
|
||||
|
||||
### "attempt to write a readonly database"
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
chmod 775 /var/www/posterg/storage/
|
||||
rm -f /var/www/posterg/storage/test.db-*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
### Production Safety
|
||||
|
||||
`just deploy` **excludes all `.db` files** by default. Only `just deploy-db` uploads the test database.
|
||||
|
||||
### Backup Production Database
|
||||
|
||||
```bash
|
||||
ssh posterg
|
||||
cp /var/www/posterg/storage/posterg.db /var/www/posterg/storage/posterg.db.backup.$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `just init-db` | Create empty test database |
|
||||
| `just fixtures` | Create test database with sample data |
|
||||
| `just deploy-db` | Deploy test database to server |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Deployment Checklist
|
||||
|
||||
After running `just deploy-db`, verify:
|
||||
|
||||
- [ ] Database file exists: `ssh posterg "ls -la /var/www/posterg/storage/test.db"`
|
||||
- [ ] Correct permissions: `-rw-rw---- www-data posterg`
|
||||
- [ ] Site loads: Visit https://posterg.erg.be/
|
||||
- [ ] No errors in logs: `ssh posterg "tail /var/log/nginx/posterg_error.log"`
|
||||
Reference in New Issue
Block a user