Reaching it from outside¶

Ferrule serves plain HTTP on port 8090, for your own network. To reach it from anywhere else, put something in front of it that adds HTTPS and keeps strangers out: a reverse proxy, a Cloudflare Tunnel, or a VPN.

Without sign-in, anyone who reaches the page sees everything on it. Before the dashboard is reachable from outside, set ADMIN_PASSWORD (Sign-in, users and roles), or put it behind Cloudflare Access, or both. Settings → Access warns you while there's no sign-in.

Pick a way in¶

Way in	Good for
A VPN, such as WireGuard or Tailscale	The simplest: nothing is exposed, and the dashboard stays at `http://<docker host>:8090`
A reverse proxy you already run	A name like `https://ferrule.example.com` with your own certificate
HMS-Docker's Traefik	Docker hosts already running HMS-Docker
A Cloudflare Tunnel	No port opened on your router, with Cloudflare Access in front if you like

With a VPN there's nothing more to do here. For the others, read on.

A reverse proxy¶

Point the proxy at http://<docker host>:8090, or at http://ferrule:8080 if the proxy is a container on the same Docker network as Ferrule. Let the proxy handle HTTPS. Then:

Pass the original host name (the Host or X-Forwarded-Host header). Ferrule refuses a button click whose page came from a different address, so without it buttons fail with cross-site request refused.
Send X-Forwarded-Proto: https. Ferrule then marks its sign-in cookie as HTTPS-only.

Most proxies, such as Nginx Proxy Manager, Caddy and Traefik, send both already.

Set DASHBOARD_URL¶

Add the address people use, with no / at the end:

DASHBOARD_URL=https://ferrule.example.com

Tapping a notification then opens the right tab, and single sign-on with OIDC returns there after signing in.

HMS-Docker or Traefik¶

For Docker hosts running HMS-Docker, whose Traefik and hms-docker_proxy_net network already exist. An extra compose file, docker-compose.hms-docker.yml, routes Ferrule through Traefik by host name, behind the same internal-ipallowlist@file middleware HMS-Docker uses.

Add docker-compose.hms-docker.yml under the stack's Additional paths in Portainer, beside docker-compose.yml. With Docker Compose, add -f docker-compose.hms-docker.yml after -f docker-compose.yml.
Set the host names. Each must resolve to your Traefik:
```
TELEMETRY_HOSTNAME=ferrule.example.com
GOTIFY_HOSTNAME=gotify.example.com
IGOTIFY_HOSTNAME=igotify.example.com
```
The Gotify and iGotify names only matter if you run the bundled ones. TRAEFIK_MIDDLEWARES replaces internal-ipallowlist@file if your Traefik names its middleware differently.
Set DASHBOARD_URL to the dashboard's address, and redeploy.

A Cloudflare Tunnel¶

Ferrule doesn't include a tunnel. If you already run cloudflared, add a public host name to that tunnel in the Cloudflare dashboard (Zero Trust → Networks → Tunnels → your tunnel → Public Hostname):

Host name	Service
`ferrule.example.com`	`http://<docker host>:8090`
`gotify.example.com`	`http://<docker host>:8091`, if you run the bundled Gotify
`igotify.example.com`	`http://<docker host>:8092`, if you run the bundled iGotify

If cloudflared runs as a container on the same Docker network, use http://ferrule:8080, http://ferrule-gotify:80 and http://ferrule-igotify:8080 instead.

To add Cloudflare Access, create an Access application for ferrule.example.com with a policy for your own email addresses. Don't put Gotify or iGotify behind Access: the phone apps can't get past its sign-in page. Gotify has its own sign-in, and iGotify only relays.

If something's wrong¶

What you see	What to do
`cross-site request refused` when you sign in or click a button	The proxy isn't passing the original host name
Notifications open the wrong address	Set `DASHBOARD_URL`
`network hms-docker_proxy_net declared as external, but could not be found`	This host doesn't run HMS-Docker. Remove the extra compose file