fix(geo): make GEOLITE2_DIR reachable and tell self-hosters what they can do

The runtime has always read GEOLITE2_DIR, but the variable was absent
from the compose `environment:` whitelist, from both env examples, and
from the docs. A variable that is not on that whitelist never reaches
the container even when the operator's `.env` sets it, so the override
existed in code and was unreachable from the documented path.

Put it on the whitelist, document it in both examples and the manifest,
and add `docs/self-hosting/geolite2.md`: fetch the databases with a free
MaxMind account, mount the directory read-only, point the variable at
it. The compose file carries the bind-mount line commented out beside
the app service.

The admin notification told the reader to set MAXMIND_LICENSE_KEY in
this repository's Actions secrets — something nobody running the
published image can do, about a fallback that sends their sign-in
addresses to a third party. It now names the mount, names the online
provider it is actually querying, and links the runbook. Six locales.
It also no longer claims the carrier column stays empty; the online
tier has filled the carrier from the ISP field since v1.25.8.

A blank GEOLITE2_DIR now resolves to the default instead of the process
working directory: compose substitutes an unset variable to the empty
string, which is not nullish.

Refs #659

scripts/__tests__/check-env.test.ts

@@ -289,4 +289,46 @@ describe("environment inventory", () => {
       expect(manifestNames).toContain(variableName);
     }
   });
+
+  it("forwards GEOLITE2_DIR through the compose whitelist and documents it", () => {
+    // issue #659 — `src/lib/geo.ts` has always read this variable, but it
+    // was absent from the compose `environment:` block, and a variable
+    // that is not on that whitelist never reaches the container even when
+    // the operator's `.env` sets it. The override existed in code and was
+    // unreachable from the documented path.
+    const repositoryRoot = join(__dirname, "../..");
+    const compose = readFileSync(
+      join(repositoryRoot, "docker-compose.yml"),
+      "utf8",
+    );
+    const manifest = JSON.parse(
+      readFileSync(join(repositoryRoot, "scripts/env-manifest.json"), "utf8"),
+    ) as { groups: Array<{ variables: Array<{ name: string }> }> };
+
+    // The compose line must SUBSTITUTE the operator's own value — a
+    // hardcoded literal would list the key and still ignore `.env`.
+    expect(compose).toMatch(
+      /^\s*GEOLITE2_DIR: "\$\{GEOLITE2_DIR(:-[^}]*)?\}"$/m,
+    );
+    // ...and the container needs a place to read the files from.
+    expect(compose).toMatch(/geolite2:ro$/m);
+
+    for (const exampleFile of [".env.example", ".env.production.example"]) {
+      const example = readFileSync(join(repositoryRoot, exampleFile), "utf8");
+      expect(example, `${exampleFile} does not document GEOLITE2_DIR`).toMatch(
+        /^# GEOLITE2_DIR=/m,
+      );
+    }
+
+    expect(
+      manifest.groups.flatMap((group) =>
+        group.variables.map((variable) => variable.name),
+      ),
+    ).toContain("GEOLITE2_DIR");
+
+    // The runbook the admin notification and both examples point at.
+    expect(() =>
+      readFileSync(join(repositoryRoot, "docs/self-hosting/geolite2.md")),
+    ).not.toThrow();
+  });
 });

scripts/env-manifest.json

@@ -132,6 +132,17 @@
         }
       ]
     },
+    {
+      "name": "Offline geolocation",
+      "description": "Optional offline GeoLite2 tier for the admin login overview. Unset, the runtime reads /opt/geolite2 (the path the image bakes its own copy into) and falls back to the online provider when the databases are absent.",
+      "required": false,
+      "variables": [
+        {
+          "name": "GEOLITE2_DIR",
+          "purpose": "Directory holding GeoLite2-City.mmdb + GeoLite2-ASN.mmdb. Point it at a read-only mount to bring your own databases. Default /opt/geolite2."
+        }
+      ]
+    },
     {
       "name": "APNs (iOS push)",
       "description": "All four core APNS_* vars together. Missing any disables APNs silently — the v1.4.40 AP-2 gap that motivated this manifest. allOrNone trips the synthetic <all-or-none> required row whenever 1-3 of the 4 are set.",