websitebox/docs/TROUBLESHOOTING.md

Troubleshooting

Check Container Health

./scripts/healthcheck.sh

Or individually:

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:

   docker compose restart nginx
   

Certificate renewal fails

Check certbot logs:

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

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:

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:

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:

   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:

   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:

upload_max_filesize = 128M
post_max_size = 128M

Also update nginx/nginx.conf:

client_max_body_size 128M;

Then rebuild:

docker compose up -d --build

Database Issues

MariaDB won't start

Check logs:

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

docker compose exec db mariadb -u websitebox -p websitebox

Docker Issues

"permission denied" when running docker commands

sudo usermod -aG docker $USER
# Log out and back in, or run:
newgrp docker

Containers won't start after VPS reboot

sudo systemctl start docker
docker compose up -d

Port 80 or 443 already in use

Find what's using the port:

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:

docker compose exec wordpress ls -la /var/backups/websitebox/

Manual backup fails

./scripts/backup.sh

If this fails, check that the WordPress and database containers are running:

docker compose ps

Resetting Everything

To completely reset WebsiteBox (WARNING: destroys all site data):

docker compose down
rm -rf websitebox-data/
rm .env .credentials
./setup.sh
docker compose up -d