Skip to main content
Version: Next

Complete first-time setup

On a fresh data directory, BeaRust accepts exactly one setup request. The request creates the first enabled administrator and then initialization is closed.

Check initialization status​

The default control plane is local to the host at 127.0.0.1:8081:

curl http://127.0.0.1:8081/api/setup/status

Before setup, expect {"initialized":false}. After a first administrator exists, expect {"initialized":true}.

Create the first administrator​

Use the generated setup token or the deterministic value configured in BEARUST_SETUP_TOKEN. This example deliberately uses placeholders; use a unique password of at least 12 characters and do not save the command with real credentials in shared history.

curl -i -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"<administrator-password-at-least-12-characters>","setup_token":"<setup-token>"}' \
  http://127.0.0.1:8081/api/setup/initialize

On success, expect 201 Created and an enabled admin user response. When session creation succeeds, the response sets the bearust_session HttpOnly cookie and the bearust_csrf cookie. Both are marked Secure, so cookies.txt records them but curl and browsers do not replay them to the plain http://127.0.0.1:8081 control listener. The setup request and unauthenticated status check remain usable over that local HTTP listener; authenticated browser or API use requires an HTTPS gateway that terminates TLS and forwards to the loopback control plane. An invalid token returns 403, invalid email or a password shorter than 12 characters returns 400, and a second setup attempt returns 409 already_initialized.

The default loopback-only mapping is a safety boundary, not a public login endpoint. Keep it local or place a deliberately secured HTTPS gateway in front of it; do not make port 8081 internet-facing as a shortcut.