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