Skip to main content

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.local file or environment variable with CFG_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-up creates 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-up applies every migration, including the admin audit and state tables.
  • playgo admin create makes 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 run starts 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.

If you get a rejection that seems to ignore your request body

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:

WhatHow to enableWhat it lets you test
Fake game providersAutomatic when env=local, via app wiringProvider accounts, launches, transfers, provider health, scripted outcomes
Dev payment mock[payments.dev_mock] enabled = true in local configCheckout and settlement loops without a real payment provider
Reward sandbox[rewards.sandbox] enabled = true, local/dev onlyIn-memory reward scenarios with a deterministic seed and presets
Tester allowlistThe admin tester endpointsKeeping your test accounts out of business reporting
Filesystem proof storageSet the cash-out evidence backend to filesystem with a writable rootProof 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:

  1. Register or log in a player using local auth.
  2. Create deposit history with the dev payment mock, or the off-app admin deposit endpoints.
  3. Script provider load, redemption, and launch outcomes with the fake provider controls.
  4. Use admin reward grants and the reward sandbox for reward-only scenarios.
  5. Mark your test accounts as testers so they stay out of business reports.
Don't insert money rows directly

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/outcome requires FakeProviderControlsEnabled, which is set by local app wiring only.
  • Reward sandbox endpoints return 404 to 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 local and dev environments.

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.