Platform administration

A self-hosted instance has an operator layer that sits above the businesses on it. A platform admin is a cross-tenant role - separate from the owner / member roles inside any one business - for whoever runs the server. It exists only on self-hosted instances; on Clerq Cloud this is our job, and none of the UI below appears.

Make yourself a platform admin

The System Administration area requires an existing platform admin, and the first person to sign up cannot be one - so you bootstrap the first admin from the command line. Create your account in the app the normal way, then, from the host running the stack:

docker compose exec app node grant-admin.mjs [email protected]

The command is idempotent, so running it twice is harmless. Once you are in, you can promote anyone else from System Administration -> Users without touching the shell again.

Running from a source checkout instead of the published image? Use pnpm admin:grant [email protected]. Either way the account must already exist and DATABASE_URL must be set.

The System Administration area

Platform admins get a System Administration entry in the navigation, at /system-admin. It has three parts:

• Overview - instance-wide, non-identifying stats: how many users and businesses exist, invoiced and expensed totals aggregated by currency, and total tracked time. Enough to see the shape of the instance, not to read anyone's books.
• Users - a searchable, paginated list. Open a user to suspend or reactivate them, or to grant/revoke platform-admin rights.
• Businesses - the same for businesses: search the list, open one, and suspend or reactivate it.

Suspension is enforced on every request, not just hidden in the UI. A suspended user sees a notice instead of the app; suspending a business locks out everyone in it until you reactivate it.

Update notifications

A self-hosted instance can tell you when a newer Clerq release is available. It checks the public container registry at most once every six hours, times out quietly if the host has no internet access, and shows a dismissible banner in the app header when the running version is behind.

• Checks are on by default and can be toggled under Settings -> System (the "Check for updates" control), which is gated behind the settings.manageUpdates permission. The System tab, like this whole area, appears only on self-hosted instances.
• The running version is baked into released images at build time via the CLERQ_VERSION build argument, so official ghcr.io/punterdigital/clerq images know which release they are. Local and development builds carry no version and skip the check entirely.
• The managed cloud host (app.useclerq.net) never checks or prompts - it is kept current for you.

When a check reports a newer version, upgrade with the steps in Backups & upgrades.