halkyon/docs/adr/0040-instance-console.md

ADR 0040: The Instance console: accounts, sign-up, assistants, regions and state in the apps

• Status: decided 8 Nov 2026 by the developer: D1 to D4 and D17 to D18 are their own choices, D5 to D16 the agent's recommendations, which they confirmed. Nothing is built yet.
• Builds on: Halkyon Learn's ADR 0021 (operators, approval, the assistants and their grants: InstanceOperatorEndpoint, AssistantOperatorEndpoint, the operator's card, badge and screen in halkyon_app), ADR 0016 (the register and INSTANCE_SECRET), ADR 0030, D44 and D50 (BRouter, the tiles and Photon for Train), ADR 0033, D32 (Todo's search on the same Photon), ADR 0039 (halkyon.li, whose regions come from here, D5, D19).

Context

An instance's operator already approves, refuses and suspends accounts, names operators and grants assistants with budgets, in every app (ADR 0021). Everything else about the instance is in files on its host, changed over SSH, each change followed by a restart:

• who may sign up (SIGN_UP in deploy/.env);
• which assistants and models are offered, with their keys (deploy/assistants.env);
• the regions of Train's map, routes and search: MAP_REGION and BROUTER_REGION (boxes in degrees) and PHOTON_REGION (a country of GraphHopper's dumps), Europe by default.

Nothing in the apps shows whether the sidecars run or when the last backup was made.

halkyon.li (ADR 0039) runs on a home machine with 7.2 GB of RAM and 150 GB of free disk, where Europe's tiles (45 GB, twice while cut) and Europe's Photon (8 GB of memory) don't fit. Its family needs a few areas, smaller than a country: Upper Bavaria, South, for instance. CoMaps (Organic Maps' fork) cuts the world into 1,159 such areas for its own downloads, each a polygon in data/borders/*.poly, named by its place in the hierarchy (Germany_Free State of Bavaria_Upper Bavaria_South, 500 KB). The repository is under Apache 2.0; the borders come from OpenStreetMap's boundaries, so they carry "© OpenStreetMap contributors", as the tiles do.

How each sidecar can be cut:

• Tiles: pmtiles extract takes a GeoJSON polygon (--region) instead of a box.
• BRouter: its segments are 5° by 5° and can't be cut. A region takes every segment its polygon touches.
• Photon: GraphHopper's dumps stop at countries. Anything smaller is an index of our own: an extract of OpenStreetMap cut to the polygon (osmium extract -p), imported into a Nominatim database, which Photon then imports from (ADR 0039, D19).

Decisions

The developer's (8 Nov 2026)

• D1 One row in Settings, a route of its own: operators alone see a single row, Instance, in every app's Settings, with the count of accounts waiting as its subtitle and badge (replacing today's This instance card). It opens the Instance route, with Accounts, Sign-up, Assistants, Regions and State. On a phone each opens a screen of its own; on a wide window the route shows the list and the chosen part side by side. The badge on the Settings cog stays. Not in Settings itself (too much there), not a web console, not Django: the module's endpoints and halkyon_app's screens, as for everything an operator does today.
• D2 The instance's settings are not backed up; what belongs to accounts is: sign-up, the assistants offered and the regions are kept in a file of their own (D5), outside the database and every backup. Approvals, operators, grants, budgets and figures stay in the database and so in the backups, since a restore without them would leave everyone waiting.
• D3 The assistants' keys stay in assistants.env: the console shows whether each assistant's key is set, never the key.
• D4 Regions are added and removed in the console, from CoMaps' polygons. halkyon.li starts with none, and Train's and Todo's map, routes and search with them.

Recommended by the agent, confirmed by the developer

• D5 The settings file: settings.json in a volume of its own, instance_settings, mounted into the register's server alone (Learn's, ADR 0016). It is written whole into a new file and moved over the old, so it is never read half written. backup.sh leaves the volume out. It holds no secret. Each setting comes from the file once the console has set it, otherwise from .env, as today. The console shows which applies (Set here or From the server's configuration) and can go back to .env's. A lost file thus returns the instance to its .env, and the regions to none.

• D6 The members ask the register: Todo's, Train's and Meditate's servers read the settings that concern them (sign-up, which every server enforces at sign-in, and the assistants, which Learn's server alone forwards today) from the register over the instance's own network, with INSTANCE_SECRET, as they ask it about accounts now. They cache an answer for a minute. A change thus takes at most a minute, with no restart.

• D7 Sign-up: Open, By approval or Closed, a choice on the screen, applied within a minute. Closing it leaves waiting accounts waiting; they are approved or refused under Accounts as before.

• D8 Assistants: each assistant's name, provider (protocol and host), model, efforts allowed, order and the ceilings of a request are kept in the file; its key stays ASSISTANT_<ID>_KEY in assistants.env. Adding an assistant in the console makes it Key missing until its key is in the file and the server restarted: the one restart left, as keys never pass through the app. Renaming an ID stays impossible (its grants hang on it); the console makes a new one instead. The grants and budgets move under Assistants as a second part, Granted.

• D9 Regions are CoMaps' polygons, named and fetched at a pinned commit: the register's image carries the list of the 1,159 names (some 60 KB) of one CoMaps commit (55846720, 8 Nov 2026; moved by hand). The console shows them as a tree to search (Germany › Free State of Bavaria › Upper Bavaria › South), from the names' parts. An added region's polygon is downloaded from that commit on Codeberg once, converted to GeoJSON and kept beside settings.json. Nothing of CoMaps' is in the repository but the list.

• D10 One list of regions for all three: a region added is covered by the tiles, the routes and the search together, as a family needs each where it goes; the console shows each service's state per region (confirmed by D17).

• D11 The sidecars bring themselves to what the register wants: no server ever gets Docker's socket. Each sidecar's refresher (map-tiles-refresh, brouter-segments, and Photon's builder, D12) asks the register every 10 minutes for the wanted regions, their union as one GeoJSON MultiPolygon and its hash, with INSTANCE_SECRET, over a network it shares with the register's server alone. When the hash differs from what it last built, or a month has passed, it builds anew beside what it serves and moves it over, as today. It reports its state back: building (with what), ready (with size and date), failed (with the reason in a line), and the free space of its volume. The .env variables stay for an instance without the console's regions: with none set there, nothing is built.

  • tiles: pmtiles extract --region=<the union>;
  • routes: every segment whose 5° square the union's polygons touch (E10_N45.rd5 for Upper Bavaria);
  • search: D12.

• D12 Photon's builder: one container, photon-build, replaces photon-data. It carries osmium, a PostgreSQL with Nominatim (mediagis/nominatim, pinned by digest) and Photon's jar. When the regions change or a month has passed:

  1. it picks the smallest of Geofabrik's extracts that covers each polygon, from Geofabrik's index (index-v1.json, each extract's own polygon);
  2. it downloads them and cuts them to the union;
  3. it imports the cut into its Nominatim, then that into a new Photon database;
  4. it stops its PostgreSQL, deletes Nominatim's database and marks the new Photon database ready for serve.sh, as data.sh does now.

  It is held to 3 GB of memory. While nothing is to be built, it holds nothing but its script. Photon's server then needs about 1 GB of heap for a few regions (PHOTON_HEAP), rather than 6.

• D13 Builds wait for the day: refreshers and the builder are among the sidecars ADR 0039, D6, stops during the CI window from 02:00 to 05:00. A build already running is interrupted there and starts again afterwards.

• D14 Room before a region: the console shows each volume's free space as reported. It warns, without refusing, when it is less than twice what the services take now, since a new cut is built beside the old.

• D15 State: State shows what the instance can know without Docker:

  • each sidecar's last report (D11) and whether it is within the nightly window;
  • the last backup, from a line backup.sh writes (state/backup.json under deploy/, mounted read-only into the register's server: when, how large, whether it succeeded);
  • the version each app's server runs.

  A sidecar that hasn't reported for two of its rounds shows as Silent.

• D16 Access: every new endpoint of the console is the operator's alone, with tests first asserting that a person who isn't an operator, someone signed out and a member service are refused. The sidecars' two endpoints (the wanted regions, the reports) take INSTANCE_SECRET alone, with tests asserting that a person's session, operator or not, and a wrong or missing secret are refused. Reports are kept in memory only (the register's server forgets them when it restarts, and the next round reports again), so nothing of them reaches the database.

Order of building

1. Regions (D9 to D14), which halkyon.li waits for.
2. Sign-up (D5 to D7), with the settings file and the members asking for it.
3. Assistants (D8).
4. State (D15).
5. The row in Settings and the route (D1), from step 1 on: Accounts is today's operator's screen.

Decided after the proposal (8 Nov 2026)

• D17 One list of regions (the developer's choice), as D10 has it, over a choice per service, which would have let a region have routes without its search.
• D18 A region is built whenever it is added or removed (the developer's choice), at any hour outside the CI window (D13), with no hours of its own.

Consequences

• The settings' file joins .env as where an instance's configuration lives; after a restore the operator sets again what was set in the console. Approvals, operators, grants and budgets come back with the database.
• A region costs disk and memory on its sidecars, which the console shows but does not refuse.
• The register's server gains an instance network shared with the refreshers, which have a way out to the internet (downloads). Only its two secret-bound endpoints are of use to them, as with the members today.
• Photon's builder brings Nominatim in, as an import step that leaves nothing running.
• sidecars/README.md and .env.example describe the console as the way to set regions, sign-up and assistants, .env as their defaults.