WBSP Platform Operator Guide

Start here. This guide is for people who set up and run their own WBSP platform, in their own AWS account, so that WBSP-compatible applications can be deployed to it.

Everything here is done with one tool, wbsp-platform. You do not need the AWS command-line tool, Terraform or kubectl on your machine: the tool brings its own copies inside a container image. When you want to see the machinery underneath, read Platform technical details.

Not what you're looking for? To deploy an application, see the Application Creator Guide.

Table of Contents

1. What you need
2. From nothing to a working platform
3. Telling developers where the platform is
4. Who may deploy
5. Checking the platform
6. Seeing what the platform runs, and what it costs
7. The image registry
8. Letting applications sign in with another sign-in service
9. Backups
10. Several platforms in one AWS account
11. Operating a platform from another machine
12. Removing a platform
13. Troubleshooting
14. Command reference

What you need

• An AWS account, and a named profile for it on your machine (AWS_PROFILE). The tool prints the exact permissions the build needs:

  wbsp-platform aws-policy --platform --cluster acme --output acme-build-policy.json

  --cluster is the name you will give the platform (acme throughout this guide). The policy names its resources after it, so leaving it out produces a policy for the wrong names. Paste the file's contents into IAM → Policies → Create policy → JSON. That permission set can create and delete the network, the cluster and the database, so grant it for the build and remove it afterwards.

• A domain name you have registered, with any registrar. The platform serves every name one level under it: api.<domain>, hap.<domain> (HAP, the sign-in service), registry.<domain>, and your applications' own names.

• An email address. It receives your sign-in codes and certificate notices.

• A container runtime: Docker Desktop, Colima or Podman on macOS; Docker Engine or Podman on Linux; WSL2 with either on Windows.

• The operator tool:

  curl -fsSL https://get.wbsp.ai/install-platform.sh | bash

Developers deploying applications use a different tool, wbsp (see Installing the WBSP CLIs). If you will also deploy, or sign in to your own platform, install wbsp that way too.

From nothing to a working platform

Two commands, and three things only you can do.

1. wbsp-platform setup prepares everything without building anything:

export AWS_PROFILE=<named profile for the account>
wbsp-platform setup acme --domain apps.example.com

In order, it:

• confirms your AWS credentials work. If they don't, it prints the console steps to create a user and an access key, then waits for you.
• checks that the account isn't held back by an AWS Organizations rule. If it is, it names the management account to sign in to and the console page to change, then checks again when you press Enter.
• refuses a name or domain another platform in the account already uses.
• creates the install home (~/.wbsp-platform/acme) and the account's infrastructure-records bucket.
• finds or creates the DNS zone for your domain and tells you exactly what to change at your registrar (Namecheap, GoDaddy or any other, for a whole domain or a subdomain of one). It then waits until the public internet sees the change.
• generates the platform's passwords and asks once for your email address.

--email, --registrar and --region answer its questions up front. Running it again on a finished install changes nothing and shows every step as done.

2. You change your domain's nameservers at the registrar, as setup told you.

3. wbsp-platform up does everything else, in order, announcing each stage. It takes 30–40 minutes:

wbsp-platform up --platform acme

It builds the infrastructure, points the domain at it with real certificates, deploys HAP (the sign-in service) and makes you its administrator, deploys the platform's API server together with the image registry developers push to, checks that both answer, and adds the platform to the wbsp tool's list on this machine. Every stage skips what is already done, so after any interruption you simply run it again.

4. You click the verification link that AWS emails to your address. On a new AWS account, only verified addresses receive email until AWS lifts the restriction. up reports where the account stands. To ask AWS to lift it, go to the AWS console → Amazon SES → Account dashboard → Request production access. The tool never sends requests to AWS for you. AWS usually answers within a day. Until then, invite nobody else: their sign-in codes would never arrive.

5. You sign in:

wbsp login --platform acme

You now have:

Telling developers where the platform is

The wbsp tool knows wbsp.ai out of the box. Anyone deploying to your platform sets it up by name, once, on their own machine:

# On the machine that ran setup and up (reads the install's own record):
wbsp platform import --install acme

# On anyone else's machine (the addresses derive from the domain):
wbsp platform add acme --base-domain apps.example.com --tenant <platform-tenant>

wbsp login --platform acme

Their projects then name it in a destination (platform: acme). No address goes into any project, and the same project can keep deploying to wbsp.ai from its other destinations. See "Deploying to several platforms" in the wbsp.yaml reference.

Before a developer can deploy, give them the deploy role in their tenant (next section).

For a shell session of your own operator work:

eval "$(wbsp-platform env --platform acme)"

This exports the API, sign-in, registry and git addresses and the tenant, so wbsp commands in that shell go to your platform. A destination that names a different platform: still wins for its own commands.

Who may deploy

The platform keeps no list of who may act on which tenant, and has no administrator role of its own. Authority comes from the sign-in credential, and one rule applies in every tenant:

A credential carries the deploy right for the tenant that issued it, or it doesn't. A credential issued for one tenant confers nothing in any other, because only that tenant's keys verify it.

In practice:

• Tenants and roles are managed in HAP, by each tenant's own administrator, in HAP's console. Giving a colleague working access is one act: the wbsp-platform:deploy role in that tenant. The only other role is wbsp-platform:config-read, a lesser inspect-only grant. There is no admin role.
• Deploy in the platform's own tenant is a privileged grant. The platform's API server is itself installed there, and deploy authority covers the whole tenant, so grant it rarely and deliberately. People who merely use the applications in that tenant need no role.
• Administering HAP grants nothing on the platform by itself. To act on a tenant, grant yourself the deploy role there and sign in to it (wbsp login --tenant <name>). That leaves a record in the tenant you touched. There is no cross-tenant override.
• Refusals name the remedy: the tenant, the missing role, and that tenant's administration page in HAP. A tenant that doesn't exist, a credential for another tenant, and an unreachable HAP each give a different message, and the last is never a permissions problem.
• A role granted after someone signed in takes effect at their next sign-in or token refresh. Nothing needs restarting.

Checking the platform

wbsp-platform health --platform acme             # human-readable
wbsp-platform health --platform acme --verbose   # with each check's progress
wbsp-platform health --platform acme --json      # for scripts

Platform Status: healthy

COMPONENT            STATUS     MESSAGE
---------            ------     -------
database             healthy    connected
ingress              healthy    traefik responding

All components must report healthy before applications can be deployed.

The API server can also be asked directly, from anywhere:

curl https://api.<domain>/api/v1/platform/health   # 200 when healthy, 503 when degraded
curl https://api.<domain>/api/v1/version           # the version it is running

When a component is degraded, run health --verbose first: it says which check failed. To look at the platform's own logs and workloads, see "Looking inside the cluster" in Platform technical details.

Seeing what the platform runs, and what it costs

What is running. inventory lists, in one read-only table, every application, the platform's own services, any parallel-services environments, and the data tier (databases and Redis):

wbsp-platform inventory --platform acme
wbsp-platform inventory --platform acme --tenant sales    # one tenant only
wbsp-platform inventory --platform acme --json

It never changes anything and never shows passwords or connection strings. If one source can't be reached, the rest is still shown and the missing source is named in a footer.

Every AWS asset the platform made. Everything the platform creates in AWS carries the tag wbsp:platform=<name>. This includes what the build makes and what the API server makes as applications are deployed (Redis stores, roles, buckets, image folders).

wbsp-platform inventory --platform acme --aws

This lists every asset, grouped by service. It marks any asset found only by name (--tag-missing adds the tag to those), and any that a full removal keeps on purpose.

Splitting the bill per platform. In the account's Billing console → Cost allocation tags, activate wbsp:platform once. Cost Explorer can then group costs by platform, from the day you activate it onwards.

A picture of everything. wbsp-platform diagram landscape.txt --platform acme writes a description of every application, route and data store. It contains no secrets, and you can hand it to a diagramming tool.

Leftovers. wbsp-platform cleanup --platform acme scans for resources that no longer belong to anything. It only reports unless you add --mode interactive (confirm each one) or --mode force.

The image registry (who may push)

A deploy from a project's repository builds the image on the developer's machine and pushes it to registry.<domain>. That address is a gateway in front of your account's own image storage. wbsp-platform up brings it up as part of deploying the API server, and checks that it answers.

On wbsp.ai, the catalog website decides who may push. Your platform has no catalog, so its own API server decides, from what it already knows:

• Anyone HAP vouches for may pull their tenant's images.
• Pushing needs the deploy role in that tenant, the same right a deploy needs, since pushing an image is the first half of a deploy.
• Images are filed per tenant and project, so one tenant's push can never change another tenant's image of the same project. Each folder keeps the last ten images, and untagged images expire after two weeks. Removing the platform removes the folders.
• Every decision is logged with the tenant, the caller, the path, the outcome and a reason.

If the gateway isn't up yet, a developer's wbsp deploy stops before building and says so, naming wbsp-platform up as the remedy.

Git is not per platform: every project's repository lives in the one catalog at git.wbsp.ai, whichever platform it deploys to. Installing a published catalog image, rather than deploying from a repository, is a wbsp.ai facility.

Letting applications sign in with another sign-in service

By default, applications on your platform sign their users in through your platform's own HAP. A destination may instead use another sign-in service (identity: <name> in its wbsp.yaml). The platform registers the application there, so it needs that service's admin key:

wbsp-platform identity add clientb-hap --base-url https://hap.clientb.com \
    --admin-key-file ./clientb-admin.key [--tenant clientb]
wbsp-platform identity list
wbsp-platform identity remove clientb-hap

Without --tenant, each application is registered in the tenant it deploys under. The change takes effect when the platform's API server is next deployed: run wbsp-platform api spec --platform acme and the deploy command it prints. A deploy that names a service the platform doesn't know is refused before anything starts.

Backups

The database. The platform's one database holds every application's data and the platform's own configuration store. It keeps seven days of automated daily backups. Removing the platform takes a final snapshot (<cluster>-postgres-final-<id>), which outlives the platform until you delete it, so a removal, or a mistake, can be recovered.

Restoring is an AWS operation (RDS → Snapshots → Restore) into a new database instance. Then point the platform at it and redeploy the API server (see Platform technical details).

The install home: keep a safe copy. The install home on the machine that ran setup (~/.wbsp-platform/<name>) holds the passwords and the configuration encryption key. Every configuration value the platform stores is sealed with that key. A database backup without it is still readable for names and placements, but not for a single stored value or credential. Keep a copy of the install home somewhere safe, and not in the same place as your database backups.

Several platforms in one AWS account

Two or more platforms can share one AWS account and region. Every AWS resource a platform creates is named after its cluster name, which is the install's own name unless you chose another with setup --cluster-name (2–20 characters):

Setup protects the platforms already there. Before it builds anything, it lists the other platforms recorded in the account and refuses an install name already in use, a cluster name that already has a cluster, database or role, and a domain that already points at a platform. Then it prints every name the new platform will use. Two platforms' commands never act on each other's cluster by accident: with several clusters in the account, a command that hasn't been told which platform to use refuses to guess.

Account limits. By default, AWS allows five networks (VPCs), five fixed public addresses and a handful of network gateways per region. Each platform uses one of each. Ask AWS to raise the limits before building a sixth platform in one region.

One verified email address per account. The verification belongs to the account, not the platform. The first platform's build creates it, and later platforms use it (the tool says so). Removing the platform that created it removes the verification. The next up on a remaining platform creates it again, and AWS emails you a new link.

Operating a platform from another machine

The install home is made on the machine that ran setup. Another machine with AWS access to the platform's account can rebuild it from the account's own records:

export AWS_PROFILE=<the platform's account>
wbsp-platform installs fetch acme

The fetched home holds no secrets, and needs none to list the platform, check it, point the tools at it, or remove it: AWS access is the authority for those. Bringing the platform up again, or redeploying HAP or the API server, needs the values kept in the original machine's copy of the home. That is one more reason to keep a safe copy of it (see Backups).

Removing a platform

Say what should happen to the data, explicitly:

wbsp-platform destroy --platform acme --keep-data
wbsp-platform destroy --platform acme --delete-data

• --keep-data removes the cluster (its machines, workloads, and the load balancers in front of them). It keeps the database, the image registry, the network, the domain and its certificates, the email setup and the applications' Redis stores. A later wbsp-platform up rebuilds the cluster on top of them. The API server comes back with its records, and applications reconnect to their data when they are deployed again. Their workloads must be redeployed; until then, the records still say "running". What is kept still costs money: inventory --aws lists it.
• --delete-data removes everything, data included. The database is snapshotted first. At the end it asks the account what is left, removes what the applications had made, and its last line says either 0 assets remain or lists what does. Kept on purpose, and listed: the final database snapshot, the DNS zone (your registrar points at it), the account's shared verified email address, and the platform's records in the infrastructure-records bucket.

Troubleshooting

Command reference

Every command takes --platform <name> (or --install <name>, the same thing) to say which platform to act on. wbsp-platform installs use <name> sets a default. Worked examples are in Useful commands, operator.

The commands for running individual stages, running the tool as a service, and letting an AI agent drive it are described in Platform technical details.