onboarding

Onboarding a New Game

This walks through bringing a new game onto a ggscale deployment, from an empty stack to a client making authenticated calls. It assumes a local development stack. The same steps apply against a hosted deployment once you point the URL at it.

1. Start the stack

make up

This brings up ggscale-server, Postgres, and Mailpit. The server is on http://localhost:8080. See the Quickstart for prerequisites and the health check.

2. Claim the control panel

The first admin is created with a one-time bootstrap token.

cat ./data/bootstrap.token

Open http://localhost:8080/v1/control-panel/setup, paste the token, and set the email and password for the first platform admin. The token is spent after this step. Sign in.

3. Create the tenant, project, and API key

In the control panel:

1. Create a tenant, shown as "Account Tenant". This is your studio or game brand.
2. Create a project inside it, shown as "Game Project", for example my-game-prod. Many studios add a second project for staging.
3. Creating the project mints an API key. Copy it now, because it is hashed at rest and will not be shown again. Your game clients send it as Authorization: Bearer <api_key>.

See Core Concepts for what each of these is.

4. Invite your team

Other operators reach the control panel through an invitation. From the tenant's team settings, invite a teammate by email and pick a role:

• owner: full control, including owner-only actions on the tenant.
• admin: manage projects, keys, players, and settings.
• member: read-only view of projects and players.

The invite email lands in Mailpit locally at http://localhost:8025. The teammate follows the link to set a password and join the tenant.

5. Wire up a client

A game client reaches ggscale over the HTTP API directly, or through an SDK (see Client SDKs). A typical player session runs like this:

1. Authenticate to get a session token. For a first run, POST /v1/auth/anonymous. For real accounts, POST /v1/auth/signup followed by POST /v1/auth/login.
2. Call player features with the session token in X-Session-Token, such as saving data, submitting scores, and managing friends.
3. To get into a match, submit a ticket to POST /v1/matchmaker/tickets, then read the result over the WebSocket or by polling the ticket.
4. Connect players together using the match result, and report progress back through the API.

Signup sends a verification email, which also lands in Mailpit on the local stack.

6. Where quotas appear

Each tenant sits in a tier class that sets its limits, such as open sessions and stored objects. The control panel shows the current usage and limit for a tenant, and a tenant admin can request a change from the same screen. A self-hosted deployment runs unrestricted by default, so these limits matter mainly on a managed deployment. See Quotas, Tiers, and Entitlements for the operator view.

7. Game server hosting (optional)

Peer-to-peer modes need no dedicated game server. If your game runs an authoritative server instead, you host that binary yourself and register it in the server browser, or use the game-server fleet to allocate instances on demand. The fleet is beta; see the Game Server Fleet guide for the Docker, Agones, and plugin backends and the fleet key scope.