Troubleshooting

Traefik Logs

The first place to look for routing or certificate issues:

docker logs wb-traefik --tail=100
docker logs wb-traefik --tail=100 | grep -i error
docker logs wb-traefik --tail=100 | grep -i acme

Certificate Not Issued

Symptom: Browser shows “certificate not valid” or Traefik logs show ACME errors.

Causes and fixes:

DNS not propagated yet. Check with dig docs.weekendbuilder.io +short. Wait for the VPS IP to appear before retrying.
Port 80 not reachable. Let’s Encrypt HTTP-01 challenge requires port 80 to be open. Check the firewall:
Terminal window
```
ufw status
# port 80 must be ALLOW
```
Rate limited. Let’s Encrypt allows 5 failed attempts per hour per domain. Wait 1 hour, then check logs for “too many certificates”.
Wrong email in traefik.yml. The ACME email must be a real address. Update infrastructure/traefik/traefik.yml and restart:
Terminal window
```
cd infrastructure/traefik
docker compose restart
```

Container Not Routing

Symptom: curl -I https://docs.weekendbuilder.io returns 404 or connection refused.

Check the container is running:
Terminal window
```
docker ps | grep wb-docs
```
Check it is on the web network:
Terminal window
```
docker network inspect web
```

Check Traefik logs for the service:

docker logs wb-traefik --tail=50 | grep docs

Verify the router name is unique — duplicate router names cause silent failures.

Build Fails in Docker

Symptom: docker compose up --build exits with a non-zero code.

docker compose build --no-cache 2>&1 | tail -30

Common cause: npm ci fails because package-lock.json is missing or out of sync. Run npm install locally first, commit package-lock.json, then rebuild on the VPS.

DNS Resolves Wrong IP

dig docs.weekendbuilder.io +short

If the IP is not the VPS, check Cloudflare for conflicting records. Orange-cloud (proxied) records can intercept traffic — set all records to DNS only (grey cloud).

Viewing All Running Containers

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"