[Feature] Allow self-hosters to set MAXMIND_LICENSE_KEY at runtime, not just as a CI build secret

[mathewcsims]

Problem

Self-hosted deployments pulling the published ghcr.io/mbombeck/healthlog image can never enable the offline GeoLite2-City/ASN databases. The in-app warning ("Online (ipwho.is) — set MAXMIND_LICENSE_KEY in CI") points to GitHub Actions secrets in HealthLog's own repo — not something a self-hoster running the published image can influence at all. So every self-hosted instance is permanently stuck on the ipwho.is online fallback, sending login IPs to a third party on every sign-in, even though a MaxMind GeoLite2 license itself is free.

Proposed solution

Support MAXMIND_LICENSE_KEY (and an account ID, if MaxMind's web service requires one) as a runtime environment variable the running container reads — e.g. downloading/refreshing the GeoLite2-City + GeoLite2-ASN .mmdb files on startup (or lazily on first use) when it's present, falling back to the current ipwho.is behavior otherwise. This would let any self-hoster supply their own free MaxMind credentials without forking and rebuilding the image.

Alternatives considered

The only current workaround is forking the repo and doing a full custom Docker build with a MaxMind key wired into a local CI-equivalent step — real effort, and it means no longer tracking the published image/release cadence. Just ignoring the warning works functionally, but means every self-hosted instance leaks login IPs to a third party for no reason, given a free first-party alternative exists.

Affected surface

Self-hosting / Docker, Admin

Additional context

Confirmed by grepping the bundled i18n strings inside the running image itself — the message explicitly reads "set MAXMIND_LICENSE_KEY in GitHub Actions secrets ... and redeploy", confirming this is CI-build-time only today, not a runtime-configurable setting, from a self-hosted deployment's perspective.

[MBombeck]

Thanks for this, @mathewcsims, and thanks for checking it inside the running image before writing it up. You are right on every point, and it is worse than the warning text suggests.

I went through it against main:

scripts/fetch-geolite2.sh runs in docker-publish.yml and the Dockerfile copies the result into /opt/geolite2/, so the databases are decided when the image is built and never again. src/lib/geo.ts does read a GEOLITE2_DIR override, so in principle you could mount your own .mmdb files and point at them. But that variable is not in the environment: whitelist in docker-compose.yml, and a variable that is not on that list never reaches the container even if your .env has it. It is also not in .env.production.example or the self-hosting docs. So the escape hatch exists in the code and is unreachable from the documented path, which is arguably the least useful place for it to be.

And the string you found is simply wrong for the audience reading it. Someone running the published image cannot set a secret in this repository's Actions, so the message tells them to do something they cannot do, about a fallback that sends their sign-in addresses to a third party.

Two separate things to fix, and I would rather do both than only the easy one:

The short one is to make the existing override real. Add GEOLITE2_DIR to the compose whitelist and to .env.production.example, document mounting a directory of .mmdb files, and change the admin message so it says what a self-hoster can actually do rather than what I can do. That works today with a free MaxMind account and geoipupdate, and it keeps the download out of the app.

The one you asked for is a runtime fetch, and it is the better answer for most people. It needs a few things settled first: MaxMind moved the download endpoint to account-id plus licence-key authentication, so the current query-parameter form in the script may not be the shape a runtime fetch should use. The download also has to go through this project's outbound wrapper rather than a bare fetch, and the files need somewhere writable and persistent to live, which means naming a volume rather than writing into the image. Refresh cadence matters too, since a stale city database is quietly wrong rather than loudly broken.

I am putting this in the backlog rather than closing it. Is that all right with you? If you would rather have something now, say so and I will pull the compose and documentation half forward, because that part is small and unblocks you without waiting on the rest.

[mathewcsims]

Happy for this to go into the backlog; it's (in my opinion) a nice to have rather than an essential feature so shouldn't be prioritised to be done immediately.
Thanks

[MBombeck]

Understood, @mathewcsims, and thank you for saying so plainly. Backlog it is, and I will leave this open until it actually ships rather than closing it as acknowledged.

For what it is worth, I do not fully agree that it is only a nice to have. The feature itself is optional, but the message pointing self-hosters at a secret in a repository they do not control is a small piece of dishonesty in the product, and that part I would like to correct sooner. It will come with the compose and documentation half rather than waiting for the runtime download.

Thanks again for reading the strings inside the running image. That is a level of checking most reports do not come with, and it meant I could confirm the whole thing against the source in one pass instead of asking you three follow-up questions.

[MBombeck]

v1.33.1 is live, @mathewcsims, and part of this is fixed. I want to be exact about which part, because it is not the one you asked for.

What shipped: GEOLITE2_DIR now actually reaches the container. The code read that variable all along, but it was missing from the compose whitelist, so setting it did nothing and there was no way to tell from outside. If you already hold GeoLite2 databases, you can point the running container at them and the offline lookup works. The admin message that told self-hosters to set a secret in this repository is gone too. You were right that it pointed at something no self-hoster can influence, and it should never have read that way.

What did not ship: the runtime licence key with the container fetching and refreshing the .mmdb files itself. That is the actual request, and it is recorded rather than quietly folded into the sentence above. It needs a download path, a refresh schedule and a failure story of its own, and I would rather it arrive properly than half-built.

So the honest position is that self-hosters are no longer locked out, but they still have to bring the databases themselves. If the GEOLITE2_DIR route is workable for you in the meantime, I would like to know, and equally if it is not.

Finding this by reading the strings inside a running container was a good catch. The gap between what the code read and what the container received is exactly the kind of thing that survives every test in the suite.