a440026701
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>
188 lines
3.5 KiB
Markdown
188 lines
3.5 KiB
Markdown
# 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
|
|
```
|