Deployment

Deployment troubleshooting

Work from the process outward: database, Web Fleet health endpoint, private proxy connection, DNS, then public TLS.

502 or 504 from the proxy

systemctl status webfleet
curl -i http://127.0.0.1:7336/healthz
journalctl -u webfleet --since "15 minutes ago"

If the private health endpoint fails, fix Web Fleet or its database before changing Caddy/nginx. If it succeeds, inspect the proxy upstream address and service permissions.

DNS does not resolve

dig webfleet.company.com A
dig webfleet.company.com AAAA

Confirm the record points at the public reverse proxy and allow for DNS TTL/propagation.

TLS certificate problems

Confirm ports 80/443 reach the proxy, the hostname resolves to that proxy and the certificate configuration names the exact Web Fleet hostname.

PostgreSQL connection failures

Test network reachability from the Web Fleet host, database credentials, database existence and TLS requirements. The first-run setup flow will test the URL before accepting PostgreSQL.

Service permissions

The Web Fleet service user needs access to its configured data directory but should not run with broad filesystem privileges. SQLite deployments also require write access to the directory containing the database and WAL files.