HTTPS and installing as an app - dvnkln/hdtracker GitHub Wiki

HTTPS is recommended in general – also when you only use hdtracker at home. Without it, your password and login travel unencrypted through your network (see Privacy and security), and browsers do not install hdtracker as an app.

hdtracker itself speaks plain HTTP and expects a reverse proxy in front of it for HTTPS – for example Nginx Proxy Manager, Caddy or Traefik.

1. Point the proxy at the container (http://<server>:3000).
2. Put the HTTPS address into ORIGIN in your .env, e.g. ORIGIN=https://tracker.example.com.
3. Restart: docker compose up -d.
4. Open hdtracker through the proxy and confirm the proxy: Settings → Server → Connection (see below).

After several wrong passwords, hdtracker blocks the address they came from for a while. Behind a reverse proxy every request reaches hdtracker from the proxy, so all visitors look like one and the same address: a stranger guessing passwords would block you as well.

• The proxy passes the visitor's real address along (header X-Forwarded-For – Nginx Proxy Manager, Caddy and Traefik do this by default).
• Anybody could send such a header, though, so hdtracker only believes it once the proxy is confirmed.
• Someone who opens hdtracker directly, past the proxy, cannot pretend to be somebody else – port 3000 does not have to be closed for this.

The Connection box shows how your request arrived and offers the way that works in your set-up:

• Reverse proxy not confirmed, with the proxy's address shown: press Confirm reverse proxy. hdtracker then trusts requests coming from that address. If the proxy runs in a container, its address can change when it is recreated – enter the range of its Docker network under Advanced instead (e.g. 172.18.0.0/16).
• Reverse proxy not confirmed, with three numbered steps: in some set-ups Docker forwards all connections itself, and every request seems to come from the same address (rootless Docker, a proxy on the Docker host itself, IPv6). The proxy then proves itself with a key: create the key, add the line shown there to your proxy, reload the page.

Nothing breaks without this step: login works either way, only the block after wrong passwords is less precise.

The box shows the line with your key filled in (hidden as dots until you press the eye; Copy always copies the real line).

Nginx Proxy Manager

1. Hosts → Proxy Hosts, open your hdtracker host with Edit.

2. Tab Custom Locations → Add Location.

3. Location: / – and Scheme, Forward Hostname / IP and Forward Port exactly as on the Details tab (yes, a second time).

4. Press the gear button next to the Location field and paste the line:

   proxy_set_header X-Hdtracker-Proxy-Key "<key>";

5. Save.

The host's own settings box (the gear at the top right of the tabs, called Advanced in older versions) does not work for this line: Nginx Proxy Manager ignores it there without a warning.

Caddy – inside the reverse_proxy block of your Caddyfile:

tracker.example.com {
	reverse_proxy 192.168.1.50:3000 {
		header_up X-Hdtracker-Proxy-Key "<key>"
	}
}

Traefik – two more labels on the hdtracker container (use the name of your own router instead of hdtracker):

labels:
  - traefik.http.middlewares.hdtracker-key.headers.customrequestheaders.X-Hdtracker-Proxy-Key=<key>
  - traefik.http.routers.hdtracker.middlewares=hdtracker-key

nginx – inside the location block that has proxy_pass:

location / {
	proxy_pass http://192.168.1.50:3000;
	proxy_set_header Host $http_host;
	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Hdtracker-Proxy-Key "<key>";
}

Then reload the Connection box through the proxy: it should say Reverse proxy confirmed and name the address of your own device or internet connection. Treat the key like a password; New key replaces it (the proxy then needs the new line).

With several proxies in a row (for example Cloudflare in front of your own proxy), also enter the outer ones under Advanced, so hdtracker skips them when reading the visitor's address.

If you open hdtracker under more than one address (for example at home via IP and on the road via your domain), list all of them, comma-separated. The first one is the main address:

ORIGIN=https://tracker.example.com,http://192.168.1.50:3000

If the address in the browser is not in this list, logging in and every form fail with a 403 error.

hdtracker can be added to your home screen and then opens full screen with its own icon.

• Android (Chrome, Edge): menu → Install app / Add to Home screen
• iPhone, iPad (Safari): Share → Add to Home Screen
• Computer (Chrome, Edge): install icon in the address bar

Browsers only install web apps from HTTPS addresses. On plain http:// Safari still adds hdtracker to the home screen; Chrome only creates a bookmark.

Once hdtracker runs over HTTPS, it can send push messages straight to your devices when something from your library comes out.

How to set that up – and the alternatives that work without HTTPS: Pushover, ntfy and webhooks – is on its own page: Notifications.