Initial commit: complete WebsiteBox project

Docker-based self-hosted WordPress deployment system with: - Four-container stack (nginx, wordpress/php-fpm, mariadb, certbot) - Automatic SSL via Let's Encrypt with self-signed fallback - First-boot WordPress setup via WP-CLI (GeneratePress + child theme, plugins) - Interactive setup wizard and one-line install script - Backup, update, healthcheck, and SSL renewal scripts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 15:24:23 -07:00
commit a440026701
32 changed files with 3397 additions and 0 deletions
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,187 @@
+# Troubleshooting
+
+## Check Container Health
+
+```bash
+./scripts/healthcheck.sh
+```
+
+Or individually:
+
+```bash
+docker compose ps
+docker compose logs -f nginx
+docker compose logs -f wordpress
+docker compose logs -f db
+```
+
+## SSL Certificate Issues
+
+### "Setting up SSL..." page persists
+
+Your DNS is not pointing to this server yet.
+
+1. Verify DNS: `dig yourdomain.com`
+2. The A record should show your server's IP
+3. Once DNS is correct, restart nginx:
+   ```bash
+   docker compose restart nginx
+   ```
+
+### Certificate renewal fails
+
+Check certbot logs:
+
+```bash
+docker compose logs certbot
+```
+
+If you've hit Let's Encrypt rate limits, wait and retry. For testing, you can use the staging environment by editing `nginx/entrypoint.sh` and adding `--staging` to the certbot command.
+
+### Force certificate re-acquisition
+
+```bash
+rm -rf websitebox-data/certs/live/yourdomain.com
+docker compose restart nginx
+```
+
+## WordPress Issues
+
+### WordPress first-boot setup failed partially
+
+The admin dashboard will show a warning banner if setup was incomplete.
+
+To retry:
+
+```bash
+docker compose restart wordpress
+```
+
+The setup will re-run idempotently — it's safe to run multiple times.
+
+### Force a clean WordPress setup
+
+To re-run the entire first-boot setup from scratch:
+
+```bash
+docker compose exec wordpress rm /var/www/html/.websitebox-setup-complete /var/www/html/.websitebox-setup-partial
+docker compose restart wordpress
+```
+
+### WordPress shows "Error establishing a database connection"
+
+1. Check that the database container is healthy:
+   ```bash
+   docker compose ps db
+   docker compose logs db
+   ```
+2. Verify `.env` database credentials match what MariaDB was initialized with
+3. If you changed database passwords after first run, you'll need to reset the database:
+   ```bash
+   docker compose down
+   rm -rf websitebox-data/database
+   docker compose up -d
+   ```
+
+### Can't upload files / upload size limit
+
+The default upload limit is 64MB. If you need larger uploads, edit `wordpress/uploads.ini`:
+
+```ini
+upload_max_filesize = 128M
+post_max_size = 128M
+```
+
+Also update `nginx/nginx.conf`:
+
+```nginx
+client_max_body_size 128M;
+```
+
+Then rebuild:
+
+```bash
+docker compose up -d --build
+```
+
+## Database Issues
+
+### MariaDB won't start
+
+Check logs:
+
+```bash
+docker compose logs db
+```
+
+Common causes:
+- Corrupted data: `rm -rf websitebox-data/database && docker compose up -d` (WARNING: destroys all data)
+- Disk full: `df -h`
+
+### Connect to database directly
+
+```bash
+docker compose exec db mariadb -u websitebox -p websitebox
+```
+
+## Docker Issues
+
+### "permission denied" when running docker commands
+
+```bash
+sudo usermod -aG docker $USER
+# Log out and back in, or run:
+newgrp docker
+```
+
+### Containers won't start after VPS reboot
+
+```bash
+sudo systemctl start docker
+docker compose up -d
+```
+
+### Port 80 or 443 already in use
+
+Find what's using the port:
+
+```bash
+sudo ss -tlnp | grep ':80 '
+sudo ss -tlnp | grep ':443 '
+```
+
+Common culprits: Apache (`sudo systemctl stop apache2`), another nginx instance, or Caddy.
+
+## Backup Issues
+
+### UpdraftPlus backup fails
+
+Check that the backup directory is writable:
+
+```bash
+docker compose exec wordpress ls -la /var/backups/websitebox/
+```
+
+### Manual backup fails
+
+```bash
+./scripts/backup.sh
+```
+
+If this fails, check that the WordPress and database containers are running:
+
+```bash
+docker compose ps
+```
+
+## Resetting Everything
+
+To completely reset WebsiteBox (WARNING: destroys all site data):
+
+```bash
+docker compose down
+rm -rf websitebox-data/
+rm .env .credentials
+./setup.sh
+docker compose up -d
+```