Gansey
Features
Modules
Docs
Licences
Running a site

Updates and licences

A site updates itself from a hub: another Gansey site that publishes core releases and answers licence checks. Leave [updates].hub_url unset and the site never contacts one. Set it, add the licence key (in Updates, or [updates].licence_key), and the site checks the hub one minute after it starts and then every check_interval_hours.

[updates]
hub_url = "https://hub.example.test"
licence_key = "GSY-XXXX-XXXX-XXXX-XXXX"
channel = "stable"
auto_patch = false
check_interval_hours = 6

What a check does

A check sends the licence key, the core version and the platform to the hub's licence check, then asks for the newest release this site may have, for its platform and channel. The request carries the licence key, because the hub rolls a release out to its own sites first and to everyone after. A site on our hosting also sends a short statement from its server (X-Gansey-Hosting), asked for over GANSEY_HOSTING_ATTEST with only a hash of the licence key; the hub uses it to tell hosted sites from ones that have moved. Elsewhere nothing extra is sent. The Updates screen shows the answer: the current and latest versions, the changelog, and whether the licence is valid and why not. It reuses a check up to 30 minutes old unless you ask it to check again. The dashboard's Core health area shows the same summary.

The channel is stable, beta or nightly; any other value in the file falls back to stable. Which channels a site may download from is the licence's business: a hosted licence may use all three, a self-hosted one the channels listed on it.

After an update

The first time the new version starts, it tells the hub how the update went, once: POST /api/v1/updates/report with the licence key, the versions it came from and went to, and ok. A start that fails (a migration, the port) reports failed with the error, and gansey self-update --rollback reports rolled_back. The report waits in data/update-pending.json until the hub has it, and is sent again at the next check if the hub was unreachable. The hub uses these to pause a release whose updates are failing; nothing else is sent, and the site runs the same whether the hub answers or not.

Installing an update

Install from Updates, run gansey self-update, or let auto_patch do it. Installing:

  1. checks again and stops if the release is not newer, or (from the admin) if the licence answer says it is not valid;
  2. downloads the release from the hub, sending the licence key, which the hub can refuse;
  3. verifies the file's SHA-256 against the hub's listing and its ed25519 signature against the hub's pinned signing key, and discards a file that fails either check;
  4. takes a backup marked pre-update, and stops if that backup fails;
  5. writes the new executable beside the current one, renames the current one to gansey.previous, and renames the new one into place;
  6. restarts with --migrate so the new version applies its migrations.

The last step happens on its own after an install from the admin or an automatic one. gansey self-update stops after the swap and asks you to restart the service.

auto_patch installs only patch releases (the same major and minor version, a higher patch number, no pre-release tag), and only while the licence answer is valid.

gansey self-update reads gansey.toml and the environment only. A licence key or channel saved in the Updates screen is not seen by it, so a site that updates from the command line needs them in the file or the environment.

The hub's signing key

The first time a site needs the hub's signing key it fetches it, stores it in data/hub-public-key, and logs a warning. From then on every release and every registry package must verify against that key. To pin it from the start, set [updates].public_key to the hex key the hub's operator gives you. If the hub ever signs with a different key, the site refuses its releases until the pinned key is changed by hand.

Rolling back

gansey self-update --rollback

This puts gansey.previous back in place of the current executable; restart the service afterwards. It does not undo the migrations the newer version ran. If the older version cannot work with the database, restore the pre-update backup as well (see Backups).

When the hub cannot be reached

Each licence answer is saved in data/licence-check.json. When the hub cannot be reached at all, the site uses the saved answer if it was valid and is no older than the grace period the hub set with it (grace_hours, 0 to 720, chosen by the hub's operator; 0 means no grace). The Updates screen says when it is relying on a saved answer. A hub that answers with an error does not count as unreachable.

Licences and lapsed subscriptions

A licence decides which updates a site may install, and nothing else. Whatever a licence says, the site keeps serving pages and the admin keeps working.

What is settled: hosted with us, Gansey core is free; self-hosted, core updates are paid for. Prices, what comes with modules, and moving between the two are still being decided, so the rules below are how the hub behaves today and may change.

  • A hosted licence is covered while it is active, on every channel.
  • A self-hosted licence is covered while it is active and its update subscription runs to today or later.
  • A suspended or revoked licence is never covered.
  • When a self-hosted subscription lapses, the check reports the licence as not valid ("update subscription has lapsed"). The site can still download releases on its channels published up to the last day it was covered: the end of its subscription, or the day it left hosting, whichever is later. Newer releases need the subscription renewed.
  • A site that leaves hosting becomes self-hosted with no subscription: it keeps running, and new updates need a subscription.