Marc-André Bombeck
13db7935f6
The password-reset runbook tells an operator to run `docker compose exec app node scripts/reset-password.mjs`, and the intake-repair runbook runs `healthlog-tsx scripts/repair-intake-anomalies.ts` inside the container. The runner stage copied nothing from scripts/, so both failed with "Cannot find module", the reset at the moment an admin is locked out. The runner stage now copies both scripts and the Argon2 parameter module the reset imports, and proves at build time that each reaches its own first check with every import resolved. A structural test holds every in-container command in docs/ and the Dockerfile copies in step. Key rotation is documented the way it works on the published image: the Rotate now button under Admin > Encryption is the primary path. The rotation script imports the application graph and runs from a source checkout of the same release; the runbook, the admin hint in all seven languages and the decrypt error now say so.
3.0 KiB
Password reset (operator)
A self-hosted operator can reset a single user's password from inside the
running container. This is an operator-only maintenance path — there is no
self-service reset route for users, and it bypasses the normal
account-recovery flow. Admins do have an in-app alternative:
POST /api/admin/users/{id}/reset-password (cookie-admin only) sets a new
password and destroys the user's sessions, tokens, and trusted devices. The
CLI remains the path when no admin can log in. Use it only for an account you
administer (for example, after a forgotten password on a single-user
instance).
Operator-only. The script writes directly to the
userstable and is intended to be run by the host operator with database access. Treat the new password like any other secret: pass it on stdin (it is read without echoing) rather than as a shell argument where it would land in shell history and the process list.
Run it
The reset CLI ships in the image from v1.39.3 on. It runs under plain node
against the built runtime: a .mjs file that uses the in-image pg and
@node-rs/argon2 directly and reuses the app's exact Argon2id parameters.
Images up to and including v1.39.2 did not contain the script, so on those
the command below fails with "Cannot find module"; use the source-checkout
form at the end of this page instead.
docker compose exec app node scripts/reset-password.mjs <username-or-email>
The script prompts for the new password without echoing it, then prints a confirmation that names only the user — never the password:
New password (input hidden):
reset-password: password updated for "alice"; revoked 2 sessions, 0 API tokens, 1 refresh tokens, 0 trusted devices, and 0 step-up elevations
You can also pass the password as a second argument for non-interactive use, but prefer the stdin prompt so the secret stays out of shell history:
docker compose exec app node scripts/reset-password.mjs alice 'a-strong-passphrase'
Behaviour
- The identifier is matched case-insensitively against
usernameoremail, mirroring the login lookup. - The match must resolve to exactly one user. Zero matches exits non-zero with
no user matches "<id>"; multiple matches exits non-zero and refuses to guess. - The new password must be at least 12 characters (the app's minimum).
- The password is hashed with Argon2id using the same cost parameters as the
application (
src/lib/auth/argon2-params.mjs), so the stored hash is identical to one the app would mint. DATABASE_URLis read from the environment — the same variable the app uses, honouring anysslmode=in the connection string.
Source checkout
From a source checkout of the same release (after pnpm install) the same
script runs under Node directly. It needs a DATABASE_URL that reaches the
database; the bundled db service publishes no port, so on a stock compose
stack run it inside the compose network or publish the port temporarily:
DATABASE_URL='postgres://…' node scripts/reset-password.mjs <username-or-email>