Admin backend onboarding and local synthetic data
How to get the admin backend running on your machine and create test data to work against. Doesn't cover the Pengu admin surface — that's a separate system.
If something here doesn't work, it's worth reporting rather than working around quietly. Setup docs rot faster than any other kind, and you're the person best placed to notice.
What you need first
- The Go toolchain, matching the version in
go.mod. - Local Postgres command-line tools:
initdb,pg_ctl,createdb. - A
.env.localfile or environment variable withCFG_DATABASE_URL— only if you're not using the Makefile default. Most people don't need this.
Local defaults live in config.toml and .env.example. The default local database URL is:
postgres://playgo:playgo@127.0.0.1:54329/playgo?sslmode=disable
Note the unusual port. It's deliberate — it keeps this database from colliding with any other Postgres you already have running.
Get it running
Four commands, in order:
make db-up
make migrate-up
printf '%s\n' 'local-admin-password' | go run ./cmd/playgo admin create \
--email admin@example.test --password-stdin --display-name 'Local Admin'
make run
What each one does:
make db-upcreates and starts a Postgres data directory inside the project at.local/postgres. It's self-contained, so nothing here touches a system-wide Postgres install.make migrate-upapplies every migration, including the admin audit and state tables.playgo admin createmakes your first admin account. It only works for the first admin unless you pass--allow-additional— a small guard against accidentally provisioning admins somewhere you didn't mean to. Source:cmd/playgo/admin.go.make runstarts the server.
The password is piped in via stdin rather than passed as an argument, so it doesn't end up in your shell history or in the process list.
Local config also switches on passwordless code reveal and local auth endpoints, so you can exercise the full browser login flow without any email being sent.
Getting a session and CSRF token
Every /api/v1/admin route needs a browser session. Anything that changes data also needs an X-CSRF-Token header, which you get from GET /api/v1/profile/me.
# 1. Get a cookie jar and read the CSRF token from the response
curl -i -c /tmp/playgo.cookies http://localhost:8080/api/v1/profile/me
# 2. Log in, sending the token back
curl -i -b /tmp/playgo.cookies -c /tmp/playgo.cookies \
-H 'Content-Type: application/json' \
-H 'X-CSRF-Token: <csrf_from_profile_me>' \
-d '{"email":"admin@example.test","password":"local-admin-password"}' \
http://localhost:8080/api/v1/auth/login
After logging in, keep sending the cookie on every request. Send the CSRF header only on POST, PUT, PATCH, and DELETE.
It's almost certainly a missing or stale CSRF token. The check runs before body validation, so the error can look unrelated to what you actually sent. Everyone hits this once.
Making test data
Five things you can switch on locally:
| What | How to enable | What it lets you test |
|---|---|---|
| Fake game providers | Automatic when env=local, via app wiring | Provider accounts, launches, transfers, provider health, scripted outcomes |
| Dev payment mock | [payments.dev_mock] enabled = true in local config | Checkout and settlement loops without a real payment provider |
| Reward sandbox | [rewards.sandbox] enabled = true, local/dev only | In-memory reward scenarios with a deterministic seed and presets |
| Tester allowlist | The admin tester endpoints | Keeping your test accounts out of business reporting |
| Filesystem proof storage | Set the cash-out evidence backend to filesystem with a writable root | Proof upload, finalize, and preview without needing S3 |
Source: fake provider gating in buildProviderRegistry, reward sandbox wiring in internal/app/app.go, config validation in internal/platform/config/config.go.
Building up realistic records
There's no single seed command that fills every admin dashboard. That's a deliberate trade-off: data built through the real flows behaves like real data, and a seed script would quietly drift from the actual code paths.
So build it the same way it happens in production:
- Register or log in a player using local auth.
- Create deposit history with the dev payment mock, or the off-app admin deposit endpoints.
- Script provider load, redemption, and launch outcomes with the fake provider controls.
- Use admin reward grants and the reward sandbox for reward-only scenarios.
- Mark your test accounts as testers so they stay out of business reports.
It's tempting to INSERT a ledger row to get to the state you want. Please don't, unless you're specifically debugging storage internals.
Ledger entries, payment events, lifecycle facts, and idempotency records all have to move together. Hand-inserting one of them produces a state the real code can never create — so you end up debugging a situation that doesn't exist, and any conclusion you draw from it is unreliable.
Endpoints that only exist locally
POST /api/v1/admin/providers/fake/outcomerequiresFakeProviderControlsEnabled, which is set by local app wiring only.- Reward sandbox endpoints return
404to everyone — admins included — when the sandbox store is disabled. A 404 here means "not enabled", not "you lack permission". - Dev payment mock settlement only wires up interactive dev payments in the
localanddevenvironments.
Cleaning up
make db-down
For a completely fresh database: stop Postgres, delete .local/postgres, then run make db-up and make migrate-up again. Everything lives inside the project directory, so there's nothing to clean up elsewhere on your machine.
Next: Admin operations backend architecture for how the code is organised, then Admin domain semantics before you touch anything financial.