harly.config.json, and doctor validates only its expected services.
After reading this
- You will know the three proxy modes and when to use each
- You will know which ports each mode publishes
- You will know how to point an existing reverse proxy at Harly
Available modes
Caddy is never started in
external or local mode.
Using an external reverse proxy
If another proxy already owns ports 80 and 443, keep it and selectexternal mode during install. Forward the hostname to 127.0.0.1:3000.
Example Nginx server block:
The Nginx block above is a standard reverse-proxy pattern, not a file shipped by Harly. Adapt it to your existing proxy configuration.
Troubleshooting
doctor reports the wrong services as unhealthy
Symptom: doctor checks for Caddy even though you selected external mode.
Cause: harly.config.json still records the previous mode.
Solution: re-run the installer’s management menu (npx @harly/cli) and confirm the proxy mode, or edit harly.config.json directly to match your actual topology.
502 from the external proxy
Symptom: the reverse proxy returns a 502 for every request. Cause: Harly is not listening on127.0.0.1:$HARLY_PORT, or the proxy is forwarding to the wrong port.
Solution: confirm docker compose ps shows the app container healthy, then check HARLY_PORT in .env matches the proxy’s upstream port.
Related pages
Self-hosting overview
VPS requirements and DNS setup.
Operations
Health checks, the scheduler, backups, and upgrades.