Roller Admin Account Runbook

Part of RollerHub. Background and the rest of the deployment: RollerOnDocker.

Availability: the admin tool ships in Roller 0.1.11 and later. Self-registration is removed, so on a fresh install this tool is the only way to get a first admin.

Why this is safe: it runs only where you can run docker compose on the host, which already gives access to .env and the database credentials. Nothing reachable over HTTP can create an admin or reset a password without the emailed token. The password is never accepted as an argument, never printed, and never appears on a process command line.

All commands run from the deploy directory. Set the shorthand once:

C="docker compose -f docker-compose.prod.yml"

1. Check for an admin

$C run --rm admin status

With at least one enabled admin, it exits 0:

enabled admin accounts:
  jake

With none, it exits 3:

no enabled admin account. Create one with:
  docker compose -f docker-compose.prod.yml run --rm admin create --username NAME --email ADDRESS

deploy.sh runs this same check after every deploy and, when there is no admin, prints the create command (the deploy still succeeds). If the check itself fails, deploy.sh warns and the deploy still succeeds.

2. Create the first admin

Interactive (prompts for the password twice, echo off):

$C run --rm admin create --username jake --email jake@example.com

Non-interactive, for scripts and agents. The password goes in on stdin, one line, and -T is required:

printf '%s\n' "$PW" | $C run --rm -T admin create --username jake --email jake@example.com --password-stdin

Expected: exit 0 and

created admin account jake (roles: admin, editor)

Use an address you actually read: password-reset links are sent there.

Refusals exit 1, print admin-account: <reason> on stderr, and change nothing: a username that is not 1-255 ASCII letters and digits, one that already exists (any case, enabled or disabled), a malformed email, an email address longer than 255 characters, a password under 8 characters, a prompt confirmation that does not match, empty stdin, or a database where the Roller schema is not installed yet (run deploy.sh first).

3. Verify

Either log in with the new account at /roller-ui/login.rol, or run status again and confirm the username is listed. Then, in Admin -> Global Config, set Absolute URL to site (if required) and Site Administrator's email address so recovery by email works. On 0.1.12 and earlier that save fails ("Property site.frontpage.weblog.handle is null") until a weblog exists; upgrade to 0.1.13 or create a weblog first.

4. Recover a forgotten password (preferred)

Use Forgot your password? on the login page and enter the username or email address. The emailed link is built from the site's absolute URL, lasts 1 hour and works once. It needs mail working:

the SMTP settings in .env. For Brevo: ROLLER_MAIL_CONFIGURATIONTYPE=properties, ROLLER_MAIL_HOSTNAME=smtp-relay.brevo.com, ROLLER_MAIL_PORT=587, ROLLER_MAIL_USERNAME, ROLLER_MAIL_PASSWORD, with ROLLER_MAIL_SECURITY left at its default starttls; and
a non-blank Site Administrator's email address in Admin -> Global Config. It is the From address, so it must be a sender or domain verified at the relay.

Until both are set, the forgot-password page says the server has no outgoing mail configured (or no site email address set). A change to .env needs $C up -d --force-recreate app; a plain restart does not re-read .env.

5. Last resort: reset the password from the host

When mail is broken or unavailable:

$C run --rm admin reset-password --username jake
$C restart app

reset-password prompts twice (or takes --password-stdin with run -T), refuses an unknown account (exit 1), and changes only that account's password hash. If the account is disabled it warns on stderr, because a disabled account still cannot log in. When it finishes it prints:

password reset for jake.
The running app caches accounts it has loaded; restart it so the new password takes effect:
  docker compose -f docker-compose.prod.yml restart app

Run that restart. Until app restarts, the old password may still work and the new one may not.

Exit codes

Code	Meaning
0	Success (`status`: at least one enabled admin)
1	A validation refusal, an unknown account for `reset-password`, a missing schema, or a failed write; stderr says why
2	Usage error: no subcommand, an unknown one, or bad options (usage is printed on stderr)
3	`status` only: no enabled admin account