Docs / Running the platform

Running the platform

For whoever runs the installation itself: the person who put it on a machine, holds its keys, and is above every tenant on it.

Installing is not on this page. There are two guides that instruct, and they are the only place a command is written down:

• Running it locally — the three processes on one machine, and the complete list of every setting the platform reads.
• Installing on one box — a real installation in containers, behind a proxy, with backups and the procedure for retiring a key.

This page is what those guides cannot be: the short list of decisions that are yours rather than a tenant’s, and where each one is made.

The profile you run under

The installation runs in one of two profiles, and the difference is not a matter of degree. In production the platform fails closed: it refuses to start on a placeholder key ring, refuses without the key its records are chained under, refuses without the credential its own two halves talk to each other with, and refuses to talk to a browser over an unencrypted connection. It also requires a second factor of everybody by default, and marks its cookies so a browser will only send them encrypted.

In the other profile the platform starts regardless, because a laptop is not a threat model — with one exception: the half that runs your scripts needs its key ring in either profile, so a laptop is given one too. The configuration half falls back to a placeholder key ring and says so; a missing chain key and a missing credential are each a warning in the log; the rest is simply not asked for — plain http goes unremarked, nobody needs a second factor unless you require one, and cookies travel over any connection. That is the whole of it: nothing is slightly on. Choosing the production profile is how you tell the platform to stop being helpful about things that are not safe.

The profile the installation is running under is shown on its own status panel, so the answer to “is this really production” is never a guess.

Two addresses only you can set

The platform has one mail account of its own, separate from anything a tenant configures, and it is where invitations and password resets come from. Beside it are two decisions:

Where the platform reports about the machine. Not about anybody’s integration — about the box: a node that stopped pulling or accepting work, or that cannot read one of the gauges it decides that by, a request whose configuration never arrived, a shutdown, a node paused by hand and reminded every hour it stays paused — and its housekeeping: a pass that failed or has fallen behind, none completing at all, archived runs it cannot judge and so never deletes, and a disk that will be full within a week — and its load: run slots held while the work grows, a dispatcher that stopped taking waiting work, and a lane about to fill to its cap, named with its tenant, each said when it begins and again when it ends. Give it an address and those reach somebody. Leave it blank and they stay in the node’s own log, which is what the platform will tell you it did rather than going quiet.

Whether the platform’s address may carry a tenant’s bad news. A tenant environment with no mail account of its own normally reaches nobody with its notification rules — and there is a switch that lets the platform send those alerts from its own address instead. It is off unless you turn it on, deliberately: this is the installation’s identity sending mail about somebody else’s failure. Turned on, the platform’s address carries tenants’ alerts under the platform’s own limits on recipients and on mails, because every tenant shares that address; a tenant’s own account has neither limit. The numbers are in the installation guide’s numbers this build fixes.

It covers exactly one case. A rule naming an account that does not resolve, naming none where the environment has several, or reaching an account that is switched off, still refuses — those are the tenant’s to resolve, and the platform does not send in their place. A tenant reading Reacting to failures is told the switch exists and told to ask you.

Both live on the same screen as the mailbox itself, and both are yours alone: no tenant administrator sees them.

What you hold that nobody else does

• Creating tenants, and deleting one. A tenant is created with its two environments and no control adds a third.
• Taking an environment grant away, and deciding who administers a tenant. A tenant administrator gives access and changes it; removing it, and naming another administrator, are yours — see Administering a tenant.
• The key ring, and retiring a key from it. The procedure is in the installation guide, including the one thing about it that is easy to get wrong: take the backup after the retirement, not before.
• The whole record. Each environment’s changes are on its Logs page (Audit, Config changes), the tenant’s own acts for its administrators. What belongs to no tenant — sign-ins, users, the platform’s own acts — is in the same trail with no page yet. Whether either trail was touched behind the platform’s back is checked on the box: make verify-audit (the installation guide, Backups).
• What the box says about itself. The status panel tells you alone what housekeeping did last: when it ran, whether it is keeping up or how far behind it is, how old the oldest thing in its archive is against the window that should have collected it, how large its own database files are and how much of that is in use, and how much disk is free — with where that is heading, in days, once it has a day of readings. A tenant administrator reading the same panel sees the installation’s facts without any of this; the box’s disk is yours to watch, and nothing about it is a tenant’s.
• Housekeeping by hand. The same panel lists what housekeeping has in front of it — the archive by age and outcome with its bytes, as the last pass read it, with the reading’s age; parked runs and dead letters against their windows — and gives you three acts over it: a pass now, a collection pulled forward, a drain until done. What each does, what none of them will touch, and what a drain costs are on When the work jams.

The installation’s usage

Administration → Usage shows what the tenants ran, called and authored, by day, kept for over a year. Each tab is its own link (#admin/usage/volume and so on). The five tabs before Storage read the range you pick — the last week, month, quarter or year of days that are over, or a from and a to — and narrow to one tenant with the Tenant filter, except the language and the people, which are the installation’s.

A few numbers read differently from what their names suggest:

• Today is not in the record until it is over: the record is written once a day, an hour after midnight UTC.
• Dormancy says “not known yet” until the runtime has recorded a month.
• Tokens used counts token-days, not distinct tokens.
• A time shown as more than a minute means past the last timing bucket.

The export (the Export box under the five tabs before Storage) takes every tenant’s day rows of the range as CSV or JSON, whatever the Tenant filter shows. It can pseudonymise the tenants, the entity names, or both, one way: the same name gets the same pseudonym on every export of this installation, and a different one on any other installation. Library names, codes and kinds are never replaced. Nothing is sent anywhere — the file is yours to pass on — and each export is recorded in the trail.

A tenant’s administrator sees that tenant’s own consumption on its page (Administering a tenant).

Where a number lives

Every setting the platform reads is in one table, in the local guide’s environment reference, and it is held against the platform in both directions: a setting the platform reads and the table does not list fails the build, and so does a row naming a setting nothing reads.

That is deliberately not repeated here. A second copy of a table like that is wrong the first time somebody changes a default, and this page would have no way of knowing.