Phase 1 — Generate credentials

This phase is purely local: you generate every secret, key, and shared HMAC that the rest of the install will need. Doing this up front means you can paste values into .env files as you go, rather than stopping mid-install to mint a random string.

Phase 1 produces credentials only. Nothing is deployed yet, no DNS is configured, and no external accounts (Cloudflare, Apple, Pocket ID) are touched here — those come in later phases.

Prerequisites

Phase 0 complete — you have the repo cloned and a web/.env file copied from web/.env.example.
openssl available on the host you’re running this from (any recent Linux or macOS shell qualifies).
A password manager or secret store you trust. Treat this phase’s output the same way you’d treat a production database password — because some of it is a production database password.

Steps

Generate the Postgres password
Pick a long, random password for the application database. This goes into both POSTGRES_PASSWORD and the password segment of DATABASE_URL .
Terminal window
```
1
openssl rand -base64 32
```
Paste the result into web/.env:
web/.env
```
1
POSTGRES_USER=ocpp_user
2
POSTGRES_PASSWORD=&lt;paste-here&gt;
3
POSTGRES_DB=ocpp_billing
4
DATABASE_URL=postgresql://ocpp_user:&lt;paste-here&gt;@postgres:5432/ocpp_billing
```
The hostname in DATABASE_URL is postgres (the Docker Compose service name) when the web container talks to the database over the internal network. If you’re running Postgres on the host, use localhost instead.
Generate the BetterAuth session secret
BetterAuth signs session cookies and magic-link tokens with AUTH_SECRET required . It must be at least 32 bytes of real entropy.
Terminal window
```
1
openssl rand -base64 48
```
web/.env
```
1
AUTH_SECRET=&lt;paste-here&gt;
```
Rotating AUTH_SECRET invalidates every existing customer session and every outstanding magic link. Generate it once at install and keep it stable.
Generate the SteVe API key
SteVe authenticates REST API calls with HTTP Basic auth (since SteVe 3.8). The username matches SteVe’s auth.user; the API key matches webapi.value. You’ll wire both sides up in the SteVe phase — for now just generate the key:
Terminal window
```
1
openssl rand -hex 32
```
web/.env
```
1
STEVE_API_USERNAME=admin
2
STEVE_API_KEY=&lt;paste-here&gt;
```
Keep this value somewhere you can retrieve it — you’ll paste the same string into SteVe’s main.properties later.
Generate the Email Worker shared secret
The Polaris Express web app and the Cloudflare Email Worker authenticate to each other by HMAC. The Worker calls it POLARIS_SECRET_A; the web app calls it CF_EMAIL_WORKER_SECRET . They must hold the same value.
Terminal window
```
1
openssl rand -base64 32
```
web/.env
```
1
CF_EMAIL_WORKER_SECRET=&lt;paste-here&gt;
```
Save the same value to your secret store under a name like polaris/email-worker/POLARIS_SECRET_A. You’ll need it again when you deploy the Worker (see the Email Worker phase) via npx wrangler secret put POLARIS_SECRET_A.

The Worker supports a two-secret rolling rotation (POLARIS_SECRET_A + POLARIS_SECRET_B). You only need one secret to start; the second slot is for zero-downtime rotation later.
Generate the SteVe webhook HMAC keys
SteVe posts pre-authorize and meter-value webhooks to ExpresSync. Each webhook channel has its own HMAC secret so you can rotate them independently:
Terminal window
```
1
# STEVE_PREAUTH_HMAC_KEY
2
openssl rand -hex 32
3

4
# STEVE_METERVALUE_HMAC_KEY
5
openssl rand -hex 32
```
web/.env
```
1
STEVE_PREAUTH_HMAC_KEY=&lt;paste-first-value&gt;
2
STEVE_METERVALUE_HMAC_KEY=&lt;paste-second-value&gt;
```
You’ll paste the same two values into SteVe’s configuration in the SteVe phase.
Record the Lago API key
Lago is the only credential in this phase that you don’t generate yourself — you copy it from a Lago instance.
- Lago Cloud: log in at app.getlago.com → Developers → API keys.
- Self-hosted Lago: copy the API key from your Lago install’s admin UI.
web/.env
```
1
LAGO_API_URL=https://api.getlago.com
2
LAGO_DASHBOARD_URL=https://app.getlago.com
3
LAGO_API_KEY=&lt;paste-from-lago&gt;
4
LAGO_METRIC_CODE=ev_charging_kwh
```
Self-hosted Lago users: set LAGO_API_URL to your Lago API host (without /api/v1 — the client appends that) and LAGO_DASHBOARD_URL to wherever your Lago UI lives. LAGO_METRIC_CODE must match the code of the kWh billable metric you’ve already created in Lago. If you haven’t created it yet, do so before Phase 5.
Stage the optional credentials
These don’t need values yet, but it’s worth noting now whether you plan to use them so you can leave the corresponding lines commented in .env:
- Pocket ID OIDC (admin SSO): generate the client secret in your Pocket ID instance during the admin-auth phase. Leave ADMIN_OIDC_CLIENT_SECRET commented for now.
- APNs (iOS push, Wave 2): you need an Apple Developer account and a .p8 key from App Store Connect. Skip if you’re not deploying the iOS app. APNS_KEY_BASE64 , APNS_KEY_ID , APNS_TEAM_ID , and APNS_TOPIC can all stay unset — the push send will just return {ok:false,reason:"JwtSignFailed"} and the SSE fallback takes over.
Back up your `.env` file
Copy the completed web/.env to your password manager or secret store. If you lose it, you cannot recover existing customer sessions, magic-link tokens in flight, or in-progress sync state without regenerating values and reconciling by hand.
Terminal window
```
1
# Verify the file is gitignored before doing anything else.
2
cd polaris-express
3
git check-ignore -v web/.env
4
# Expected: web/.gitignore prints, confirming the file is ignored.
```
If git check-ignore returns nothing, .env is not ignored. Stop, fix .gitignore, and git rm --cached web/.env before you ever commit.

Configure environment variables

This is the full list of secrets you should have populated by the end of Phase 1. Hostnames, URLs, and TTLs come in later phases — only secret material is in scope here.

Name	Source	Required	Notes
`POSTGRES_PASSWORD`	`openssl rand`	Yes	Embedded in `DATABASE_URL` as well
`DATABASE_URL`	Composed	Yes	`postgresql://user:pass@host:5432/db`
`AUTH_SECRET`	`openssl rand`	Yes	≥ 32 chars; rotating logs every user out
`STEVE_API_KEY`	`openssl rand`	Yes	Mirrored into SteVe’s `main.properties`
`CF_EMAIL_WORKER_SECRET`	`openssl rand`	Yes	Mirrored into Worker as `POLARIS_SECRET_A`
`STEVE_PREAUTH_HMAC_KEY`	`openssl rand`	Yes	Mirrored into SteVe’s pre-auth webhook config
`STEVE_METERVALUE_HMAC_KEY`	`openssl rand`	Yes	Mirrored into SteVe’s meter-value webhook config
`LAGO_API_KEY`	Lago dashboard	Yes	From Lago → Developers → API keys
`ADMIN_OIDC_CLIENT_SECRET`	Pocket ID	Optional	Only if you’re using Pocket ID admin SSO
`APNS_KEY_BASE64`	App Store Connect	Optional	Only if shipping the iOS app

Verify

You can’t curl anything in Phase 1 — nothing’s running yet. Verify locally instead:

1
# Every required secret should be at least 32 characters.
2
cd web
3
grep -E '^(POSTGRES_PASSWORD|AUTH_SECRET|STEVE_API_KEY|CF_EMAIL_WORKER_SECRET|STEVE_PREAUTH_HMAC_KEY|STEVE_METERVALUE_HMAC_KEY|LAGO_API_KEY)=' .env \
4
  | awk -F= '{ if (length($2) < 32) print "TOO SHORT: " $1 " (" length($2) " chars)" }'

Expected output: nothing. Anything printed means that secret is shorter than 32 characters and should be regenerated.

Also confirm:

.env does not appear in git status.
git check-ignore web/.env confirms it’s ignored.
Your secret-store entries match the values in .env exactly (whitespace and all — a trailing newline is a real bug here).

If something goes wrong

openssl: command not found Install OpenSSL (apt install openssl, brew install openssl, or your distro’s equivalent). On Windows, use WSL or Git Bash.

You committed .env to git. Treat every secret in that file as compromised. Regenerate all of them, force-push the history rewrite, and rotate the Lago API key from Lago’s UI. Cleaning the commit out of origin is not enough — assume mirrors exist.

You lost your .env and have nothing running yet. Easy: regenerate the file from scratch. No data has been written anywhere, so there’s nothing to reconcile.

You lost your .env and services are already deployed. Stop. Do not regenerate AUTH_SECRET blindly — it will log out every customer and invalidate every magic link. Recover from your secret store if you can. If you can’t, plan a maintenance window: rotate each secret one at a time, redeploying the dependent service (database, SteVe, Email Worker, Lago) between rotations.

Next phase

Continue to Phase 2 — Provision DNS and TLS to set up the hostnames you’ll bind to AUTH_URL , ADMIN_BASE_URL , and COOKIE_DOMAIN in later phases.

Phase 1 — Generate credentials

Prerequisites

Steps

Generate the Postgres password

Generate the BetterAuth session secret

Generate the SteVe API key

Generate the Email Worker shared secret

Generate the SteVe webhook HMAC keys

Record the Lago API key

Stage the optional credentials

Back up your `.env` file

Configure environment variables

Verify

If something goes wrong

Next phase