Troubleshooting

Common Issues

No WordPress image found

Build the images first:

bash scripts/build-wp-image.sh

Product dropdown is empty

Create at least one product configuration:

bash scripts/create-product.sh

Site not accessible after creation

• Check Traefik is running: docker compose ps traefik
• Check the site container is running: docker ps --filter "label=wpl.site"
• Check Traefik logs: wpl logs traefik

Port 80 already in use

# Find what's using port 80
sudo lsof -i :80
# Stop the conflicting service, then restart
wpl restart

Out of memory

# Check memory usage
free -h

# Add swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Or reduce container memory in .env
CONTAINER_MEMORY=128m

wp-admin redirect loop

Usually caused by incorrect siteurl or home values. Fix via WP-CLI:

wpl wp <subdomain> option update siteurl "http://<subdomain>.localhost"
wpl wp <subdomain> option update home "http://<subdomain>.localhost"

Email Issues

Connection timeout on SMTP

Many VPS providers block ports 25, 465, and 587. Test connectivity:

timeout 5 bash -c 'cat < /dev/tcp/smtp.example.com/587'

If blocked, switch to Brevo HTTP API which uses port 443 (always open).

SMTP_SECURE misconfiguration

SSL Issues

Error 525 (Cloudflare)

You're using HTTP challenge with Cloudflare proxy enabled. Either switch to DNS challenge or disable Cloudflare proxy (grey cloud).

Certificates not issuing

• Verify DNS records point to your server: dig yourdomain.com
• Check Traefik logs: docker compose logs traefik
• Ensure ports 80/443 are open: sudo ufw status

ERR_SSL_UNRECOGNIZED_NAME

Set ENABLE_TLS=true in your .env and restart.

Let's Encrypt rate limit

Let's Encrypt limits 50 certificates per registered domain per week. If hit, wait 7 days or use DNS challenge for a single wildcard cert.

Admin Login Issues

Access Denied

Your user isn't an admin. Promote yourself:

wpl admin:promote [email protected]

No admin account exists

Set ADMIN_EMAIL in .env and restart, then register with that email. Or use the API_KEY from .env for direct API access.

API Endpoints Reference