Joripo- Home
- Documentation
- Server administration
- Maintainers and their sign-in
Server administration
Maintainers and their sign-in
Who a maintainer is, adding one, the password-and-code sign-in, sessions, and what to do when a phone or the password is lost.
Joripo documentation · https://joripo.com/docs/server-administration/maintainers
On this page
Who a maintainer is
A maintainer is a person in the server's maintainers file, kept on the server machine outside the database, the data and the code. Nothing in the console, sign-up or People can add one. The file holds only a scrypt hash of each password, the authenticator secret and hashed recovery codes.
The maintainer cannot see anyone's password and cannot sign in as anyone else, by design.
Adding or rotating a maintainer
On the machine that runs Joripo, from the engine's folder:
python scripts\set_maintainer.py you@example.orgIt asks for the password twice (at least 12 characters) and never shows it. --name "Your Name" sets the name shown, --remove removes an entry, and --list shows each maintainer and whether two-step sign-in is set up, never a secret. On a host with no writable disk of its own, --hash prints an entry for the JORIPO_MAINTAINERS setting instead.
With no maintainer configured, the server logs a warning at every start and /admin does not exist.
Signing in
Sign in at /admin/login with the email and password, then a six-digit code from an authenticator app (Google Authenticator, Microsoft Authenticator, Authy, 1Password). The first sign-in shows a QR code to scan; once its code is typed, ten single-use recovery codes are shown, once: save them.
- A code works once, within ten minutes of the password. Wrong passwords and wrong codes are limited per email and per address, and wrong codes to 20 a day.
- The maintainer's session is its own: a cookie sent only to
/admin, ended after 30 minutes without use, 8 hours after sign-in, at Sign out, or at once when their entry is rotated or removed. Signing in or out of an organisation's console in the same browser never touches it. - Pages are never cached and never indexed, and no public or organisation page links to
/admin.
When something is lost
| Situation | What to do |
|---|---|
| Phone lost, recovery codes at hand | Sign in with the password and a recovery code, then Your sign-in › Reset two-step sign-in, and set up the new phone. |
| Running low on recovery codes | Your sign-in › Make new recovery codes (needs a current code). The old ones stop working. |
| Phone and codes both lost | On the server machine: python scripts\set_maintainer.py <email> --reset-2fa. The next sign-in sets up two-step again. There is deliberately no way to do this from the internet. |
| Password forgotten | On the server machine: python scripts\set_maintainer.py <email>, and choose a new one. |
| The maintainers file lost | Run the script again on the server. There is no other way in. |
For a monitoring service
/admin/health.json also answers a request carrying Authorization: Bearer <token>, with a token made by python scripts\set_maintainer.py --health-token (shown once; only its hash is kept), so an uptime monitor can read the server's health without a maintainer's sign-in.
Everything is recorded
Every sign-in attempt and every action in Server administration is recorded in the server's audit log, which nothing can edit or delete. What a maintainer does to an organisation appears in that organisation's activity log as Joripo server maintainer.