Phase 8 — Seed the first admin

By default Polaris Express has no admins. The first person to sign up is just a regular user — they can’t reach /admin, can’t promote others, and can’t see the operations surface. This phase walks you through promoting that first user to an admin so you can finish configuring the deployment from inside the UI.

After this phase you’ll have a working operator account that can manage ChargeBoxes, tariffs, user mappings, and feature flags.

Prerequisites

• Phase 6 — Bring up the web app completed; the app is reachable.
• Phase 7 — Configure email delivery completed; magic link sign-in works end-to-end.
• You have shell access to the host running the db container (or direct psql access to the Postgres instance).
• You know which email address you want to be the first admin.

Steps

1. Sign up as the first user

   Open the web app in a browser and sign in with the email you want to promote. BetterAuth will send a magic link; click it to complete sign-in.

   This creates a row in the user table with role = 'user'. The user is fully functional — they just can’t reach the admin surface.

   Note

   If sign-in fails, return to Phase 7 and verify the email worker is delivering. Don’t try to seed an admin row directly; you want BetterAuth to create the user record cleanly so its session and account tables stay consistent.

2. Open a psql session

   From the host running Docker Compose:

   promote-admin.sh

   docker compose exec db psql -U polaris -d polaris

   Substitute the user and database name from your .env if you overrode them. You should land at a polaris=# prompt.

3. Confirm the user exists

   SELECT id, email, role, "emailVerified"
   FROM "user"
   WHERE email = '[email protected]';

   You should see exactly one row with role = 'user' and emailVerified = true. If emailVerified is false, click the magic link again before continuing — an unverified user shouldn’t be promoted.

4. Promote to admin

   UPDATE "user"
   SET role = 'admin'
   WHERE email = '[email protected]';

   The expected output is UPDATE 1. If you see UPDATE 0, you typed the email wrong or the user hasn’t completed sign-in yet.

   Caution

   Polaris Express uses a single admin role for the operator surface. There is no superadmin / staff tier; anyone with role = 'admin' can promote or demote other users from the admin console. Treat the seed admin account accordingly.

5. Exit psql

   \q

6. Re-authenticate

   Sign out of the web app and sign back in with the same magic link flow. The role is read into the session at sign-in time, so an already-signed-in tab will not pick up the promotion until the session refreshes.

Configure environment variables

This phase doesn’t introduce new env vars; it only mutates the database. The values you set in earlier phases — notably the database credentials — are what docker compose exec db psql uses.

Variable	Default	Required	Source
POSTGRES_USER	polaris	yes	.env (root)
POSTGRES_DB	polaris	yes	.env (root)
POSTGRES_PASSWORD	—	yes	.env (root)

Verify

1. Navigate to /admin in the web app. You should see the admin dashboard instead of a 404 or redirect.
2. Open /admin/users. Your account should appear with the admin badge.
3. Open /admin/feature-flags. You should be able to toggle a feature flag and see the change persist on reload.

If all three checks pass, the seed is complete.

If something goes wrong

/admin redirects to / or shows “Forbidden”. The session predates the promotion. Sign out fully (clear the session cookie if necessary) and sign in again.

docker compose exec db psql errors with “database does not exist”. Your POSTGRES_DB value differs from polaris. Run docker compose exec db psql -U polaris -l to list databases and use the correct name.

UPDATE 0 even though the user signed in. Email comparison is case-sensitive in the user table. Try:

SELECT email FROM "user" WHERE lower(email) = lower('[email protected]');

and use the exact stored form in your UPDATE.

You promoted the wrong account. Demote it with:

UPDATE "user" SET role = 'user' WHERE email = '[email protected]';

Danger

Never leave a deployment with zero admins. If you demote your only admin account, you’ll have to re-promote it via psql exactly as in this phase. There is no “recover admin” flow in the UI.

Next phase

Continue to Phase 9 — Register your first ChargeBox to connect a SteVe-managed ChargeBox and run an end-to-end charging session.