weikio-backend
Weik.io 2026.2The operations an operator runs on a hub server with the backend image: first setup, checks, backups, restores, break-glass access, upgrades and the storage budget.
On this page
weikio-backend is the backend image of a hub run as a command on the hub server itself. Its verbs do what must never be reachable over the API: they create the hub’s storage, hold the master key or mint the hub’s operator identity. They need a shell on a hub server and no sign-in. The verbs that change records, such as backup, restore and breakglass enable, are written to the audit log as the operator, system:operator, and each says so in one line, Audited <action> on <target>: <outcome>, record <seq>.
The weikio CLI is the other tool, and it reaches the hub over the API from anywhere. The two have different commands named init: weikio-backend init sets up a hub, and weikio init scaffolds an integration folder.
How to run the verbs#
init runs once from the release’s backend image with docker run, before the stack exists. Every other verb runs in the stack’s folder through the stack’s infra service, which has the keys and the configuration mounted:
$ cd /opt/weikio/deploy/compose/single
$ docker compose run --rm infra weikio-backend doctorThe verbs exit 0 on success, 1 when a write was refused or failed, 2 for a usage error or a configuration that isn’t valid and 6 when the hub’s message server can’t be reached.
init#
weikio-backend init sets up a new hub. It never asks anything, so every choice is a flag. It writes the stack’s compose file and configuration, the keys, the first signing key, the seeded roles, the local admin user and the first platform administrator API key. It prints the operator seed and the API key once, so save the seed and a copy of the master key outside the server and apart from the backups, because a restore needs both.
$ install -d -o 1654 -g 1654 -m 0700 /opt/weikio
$ head -c 32 /dev/urandom > /opt/weikio/master.key && chown 1654:1654 /opt/weikio/master.key && chmod 0400 /opt/weikio/master.key
$ docker run --rm -u 1654:1654 -v /opt/weikio:/opt/weikio -e WEIKIO_HOME=/opt/weikio -e Weikio__Keys__Dir=/opt/weikio/keys \
-e WEIKIO_MASTER_KEY_FILE=/opt/weikio/master.key -e Weikio__Nats__Urls__0=nats://nats:4222 -e WEIKIO_BACKEND_IMAGE=$IMG \
$IMG weikio-backend init --public-base-url https://acme.example --public-leaf-url wss://nats.acme.example:443 --disk-budget 40GiB$IMG is the backend image of the release with its digest, taken from the release’s images.env. Install a hub on one server gives the whole first start, with the checksum check of images.env.
| Flag | What it does |
|---|---|
-- |
The hub’s address for the admin UI, the API and the sites’ telemetry, which every hub needs. |
-- |
The address sites link to, on its own DNS name, such as wss://. |
-- |
The standby hub’s link address, which sites try after the published one. |
-- |
The message server’s own address on the hub’s network, for a site on the same server, such as nats://. Give it on the first run, because a later run refuses it. |
-- |
The certificate of a private authority that signed the published addresses’ certificate, which every site bundle then trusts. |
-- |
Writes a stack to try the platform on, with the dev agent, the project sandbox and the environment devtest, and no backup service. |
-- |
Writes a hub of N servers, with one folder for each server. |
-- |
How many copies of the storage the hub keeps, 3 by default on several servers. |
-- |
The servers’ zones in order, so each copy of the storage goes to another zone. |
-- |
The number of APIM instances, one on each server. A later run with a higher number adds the missing instances. |
-- |
The storage budget of each data server, at most 80 % of the disk under the message server, such as 40GiB. Without it the storage has no cap. |
-- |
The image registry the stacks pull from, Docker Hub by default. |
-- |
A Maven repository the builder resolves dependencies from, repeated for each. ,mirror marks one that mirrors everything. |
-- |
Leaves Maven Central out, for an air-gapped hub. |
-- |
Writes the stack without the log, metric and trace stores. |
-- |
How often the backup service takes an archive, from 1h to 365d. |
-- |
How many archives the server keeps. |
-- |
Where each archive is copied, an s3:// address or an rclone remote. |
-- |
Limits the platform’s own certificate authority to these name suffixes, such as internal. They’re fixed once the authority is made. |
-- |
Gives the installation its first DNS connection, with -- and --, so names in the zone are proved through DNS. |
init runs again at every docker compose up -d and writes only what is missing. It keeps the choices of the first run in weikio-install.json beside the stack, takes every choice it isn’t given from there and refuses a flag that differs from the record.
doctor#
weikio-backend doctor checks the hub and changes nothing. It prints one line per check that starts with the result and the name of the check, and a warn or fail line ends with fix: and the command that fixes it. Any fail makes it exit with an error.
$ docker compose run --rm infra weikio-backend doctorThe checks cover the message servers and the storage budget, the public address through the load balancer with TLS 1.2 or later, the hub’s link addresses, the site bundles, the backups, the log, metric and trace stores and the disks under them, and the revocations of agents. -o json prints the same checks for a script.
weikio-backend doctor --hub-certificates runs no check and prints one sentence for each of the hub’s names: the certificate the hub serves for it and its days left, with Warning: in front when a renewal is due and hasn’t happened or an upload has less than 30 days left.
infra plan and infra apply#
weikio-backend infra plan compares the hub’s storage, its buckets, streams and project stores, with what the release needs, and lists what is missing or different. weikio-backend infra apply creates what is missing and updates what the backend owns. The stack runs infra apply before the backend starts, so you run these by hand only to check a hub:
$ docker compose run --rm infra weikio-backend infra planbackup#
weikio-backend backup --to <folder> takes a backup archive of the hub’s records, sealed with the master key, into a folder or an s3:// address. The stack’s backup service runs the same verb on the schedule of the installation’s settings and keeps the newest archives, so you run it by hand before a risky change or when the problem A backup is overdue shows:
$ docker compose run --rm infra weikio-backend backup --to s3://backups-eu/weikio/backup-20260916T020000ZAn archive has neither the master key nor the operator seed. --reason stores a reason with the audit record.
restore#
weikio-backend restore --from <folder> restores a hub from an archive, on the same host or on a new one. The archive opens only with the master key it was sealed with, given in WEIKIO_MASTER_KEY_FILE, and the restore also needs the operator seed in the keys folder. Every file is checked against the archive’s sealed index before anything is written, and --verify-only runs that check alone.
weikio-backend restore document --from <archive> <kind>/<name>[@<environment>] restores one document, such as one variable, from an archive or from a folder weikio export wrote. A record of that name is replaced with the archive’s copy and keeps its ID, so its history and figures stay with it.
Backups and restore gives the whole procedure.
agents repoint#
weikio-backend agents repoint --hub wss://<host>:<port> is for a hub restored at a new address. It makes the new address the first one sites link to and writes a new bundle for every agent into --out DIR, one folder per agent. Each agent is offline until its folder is copied to its site and installed there with sudo sh ./setup.sh.
breakglass#
Break-glass accounts are emergency accounts that can sign in only while a break-glass window is open, from the address ranges the window names. The window is opened on a hub server, so it works when single sign-on doesn’t:
$ docker compose run --rm infra weikio-backend breakglass enable --hours 4 --cidr 203.0.113.7/32 --reason "identity provider down"enable opens the window for 1 to 72 hours, ends every break-glass session and prints a one-time set-password link for each break-glass account that has no password yet. breakglass disable ends the window early and breakglass status shows whether a window is open, until when, from which ranges and how often it was used. Each use is written to the audit log.
networks#
weikio-backend networks add RANGE... adds address ranges to the hub’s allowed networks, and weikio-backend networks clear removes the list so every address can reach the hub. They are the way back in when the allowed networks leave out your own address, because they change the list without signing in. Each server applies the change within seconds.
secrets rotate#
weikio-backend secrets rotate --new-key-file <path> seals every secret, password and signing key again under a new master key. Run it on one server, then put the new key where WEIKIO_MASTER_KEY_FILE points on every backend server and restart the backends one at a time. Keep the old key for the backups taken before the rotation, because they open only with it.
upgrade and upgrade.sh#
A hub is upgraded with upgrade.sh, which init writes beside every stack. Run it as root in the stack’s folder with the release’s images.env:
$ sudo sh ./upgrade.sh https://weik.io/downloads/releases/2026.2.1/images.envIt takes a backup, runs the new release’s weikio-backend upgrade, which writes the stack’s files again for the release and keeps the previous ones, brings the stack up, waits for the message server and the backend and ends with doctor. --check shows what would change, and upgrade.sh --rollback goes back to the release before while it keeps every stored record. On a hub of several servers it runs on one server at a time, and each server leaves the load balancer’s pool before its services restart.
weikio-backend upgrade --describe FROM TO lists the upgrade steps between two releases.
raise-budget and raise-budget.sh#
Once the disk under the message server has grown, raise-budget.sh raises the storage budget while the message server runs. Run it as root in the stack’s folder:
$ sudo sh ./raise-budget.sh 80GiBServer 1 raised to 80 GiB. The hub's storage is 80 GiB.A size above 80 % of the disk is refused with the largest budget the disk can take, and a budget is never lowered. On a hub of several servers, run it on each data server, because the hub’s storage follows the smallest budget among them.