WBSP Platform Operator Guide

Audience: Platform operators who set up, administer, and maintain the WBSP platform. You should have basic experience with Docker and Docker Compose (for local) or AWS (for cloud).

Not what you're looking for? If you want to deploy an application on the platform, see the Application Creator Guide.

Application placement: application configs use a destination: map (placement: cluster + enclave + mode). The operator-owned concepts here — clusters and which one receives edge traffic by default, plus diverting specific wildcard domains/vanity hosts to additional clusters — are an operator decision, never an app-owner one. For the wbsp.yaml field reference, see the Application Creator Guide and wbsp-yaml-reference.md.

Table of Contents

1. Prerequisites
2. Local-Machine Deployment
3. AWS Platform Setup
4. Health Monitoring
5. Platform Administration
6. Platform Teardown

Prerequisites

For Local Development

• Docker (version 20.10 or later) and Docker Compose (v2)
• The wbsp-platform and wbsp-app CLIs — see Installing the WBSP CLIs (operators: go install, GitHub Release, or make build from source)
• At least 2 GB of free memory for platform containers

Verify Docker is available:

docker --version
docker compose version

For AWS Deployment

Everything listed above for local, plus:

• AWS CLI (v2) configured with valid credentials
• Terraform (v1.5 or later)
• An AWS account with permissions to create: VPCs, EKS clusters, RDS instances, load balancers, IAM roles
• A target AWS region selected

Verify AWS access:

aws sts get-caller-identity
terraform --version

Local-Machine Deployment (no platform to provision)

The local platform is retired (feature 063). There is no local Traefik, PostgreSQL, or WBSP-API to provision — wbsp-platform --provider local is gone (it returns an error). Running apps on a laptop no longer requires an operator to stand up a shared local platform.

Local-machine application deployment is now fully self-contained and is an application-creator activity, not a platform-operator one. An app creator picks a local-machine destination type in wbsp.yaml and deploys with wbsp-app:

None use Traefik; each host-publishes its own ports. The only one-time host setup is docker network create wbsp-shared (for the compose type's HAP reachability). See the Application Creator Guide for the full workflow.

The rest of this guide covers the AWS platform, which operators still provision and manage.

{
  "platform_status": "healthy",
  "components": [
    { "component": "database", "status": "healthy", "message": "connected" },
    { "component": "ingress", "status": "healthy", "message": "traefik responding" }
  ]
}

(That shape is the AWS wbsp-platform health --provider aws --json output.)

AWS Platform Setup

Step 1: Configure AWS Environment

Set the AWS profile and region for your deployment:

export AWS_PROFILE=your-profile    # named profile with EKS/RDS/ECR permissions
export AWS_REGION=ap-southeast-1   # your target region

Verify access:

aws sts get-caller-identity --profile your-profile

Step 2: Provision the Platform

wbsp-platform provision --provider aws

This validates AWS credentials via aws sts get-caller-identity, then runs Terraform to create:

Provisioning takes 15-25 minutes depending on region and resource availability.

Step 3: Verify Health

wbsp-platform health --provider aws --json

The health check verifies connectivity to the EKS cluster, RDS instance, and Traefik ingress. All components must report healthy before applications can be deployed.

How AWS Configuration Works

After provisioning, the CLI reads Terraform outputs automatically (terraform output -json from deploy/aws/). You do not need to manually set environment variables for RDS endpoints, EKS cluster details, or ECR registry URLs — these are resolved at runtime.

The following environment variables are read from Terraform outputs:

The only environment variables you must set yourself are AWS_PROFILE (or AWS credentials) and AWS_REGION.

Lambda Deployment Prerequisites

Lambda support is provisioned automatically as part of wbsp-platform provision --provider aws. The Terraform module at deploy/aws/modules/lambda/main.tf creates all required resources.

IAM roles created by Terraform:

Security group:

A security group (<cluster>-lambda-rds) is created in the platform VPC to allow Lambda functions to reach the RDS instance on port 5432, DNS, and HTTPS for AWS API calls.

Terraform outputs for Lambda:

Like the other AWS outputs, these are read automatically via terraform output -json. You can override them with environment variables if needed:

Sample mode base domain:

Sample-mode deployments (an aws destination with mode: demo) use subdomain-based routing. The sample_base_domain is configured at platform provisioning time (Terraform variable) or via the WBSP_SAMPLE_BASE_DOMAIN environment variable:

For production, configure a wildcard DNS record (*.demo.wbsp.io) pointing to the Traefik load balancer, and optionally an ACM wildcard certificate (*.demo.wbsp.io) for HTTPS. For local development, add specific subdomain entries to /etc/hosts after deploying, or use dnsmasq with address=/demo.localhost/127.0.0.1 for wildcard resolution.

Demo cleanup Lambda:

When you first deploy an application to a demo destination (type: aws, mode: demo), the platform automatically creates a wbsp-demo-cleanup Lambda. This function runs on an EventBridge Scheduler schedule to delete expired demo deployments. The cleanup Lambda uses the demo_cleanup_role_arn role, which is scoped to resources prefixed with wbsp-.

AWS Troubleshooting

Health Monitoring

CLI Health Check

# Human-readable output
wbsp-platform health --provider aws

# JSON output for scripting
wbsp-platform health --provider aws --json

Human-readable output:

Platform Status: healthy

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

API Health Check

The AWS API server (wbsp-api) exposes a health endpoint at $WBSP_API_URL:

curl "$WBSP_API_URL/api/v1/platform/health"

Returns HTTP 200 when healthy, HTTP 503 when degraded. The response body lists each component's status.

Component Status Values

What to Check When a Component Is Degraded

Platform Inventory

wbsp-platform inventory shows, in a single read-only table, everything the platform runs on a target: application workloads across every namespace, the platform-system infrastructure, parallel services environments, and the managed data tier (databases and Redis). It answers "what is running here?" without running a separate kubectl per namespace.

# Full inventory for a target (for AWS this aggregates EKS + on-demand + demo)
wbsp-platform inventory --provider aws

# Filter to one tenant (applies to workloads, data tier, and parallel envs)
wbsp-platform inventory --provider aws --tenant wbsp

# Machine-readable output for scripts
wbsp-platform inventory --provider aws --json

The table is grouped into sections — Platform system, Applications, Parallel environments, and Data tier — with each row showing the namespace, name, kind (Deployment / StatefulSet / Lambda / Database / Redis / ParallelService), exposure (service kind and port(s)), tenant, live status (ready/desired, age, restart and health markers), and a short description.

Notes:

• AWS aggregation: any AWS target flag (aws, aws.on-demand, aws.demo) returns the same aggregated view across all three sub-targets; each Lambda row is tagged with its sub-target.
• Read-only: the command never creates, modifies, or removes anything.
• No secrets: output contains names, ports, and roles only — never passwords or connection strings.
• Partial results: if one source is unavailable, the rest is still shown and the failed source is listed in a footer; the command exits non-zero only when the target is wholly unreachable.

Platform Administration

Environment Variables

AWS platform behaviour is configured via the WBSP_* / AWS_* variables read by wbsp-platform and wbsp-api (RDS, ECR, EKS, and ACME settings). See AWS Platform Setup for the required ones.

Viewing Platform Logs

The AWS platform's components run in the cluster; view their logs with kubectl:

kubectl logs -n <wbsp-api-namespace> deploy/wbsp-api
kubectl logs -n traefik deploy/traefik

(There are no local platform containers to log — the local platform is retired, feature 063.)

Platform Teardown

There is no local platform to tear down (feature 063). Local-machine app deployments are removed per-app by their creator with wbsp-app remove <app> --tenant <tenant> (see the Application Creator Guide).

AWS Teardown

wbsp-platform destroy --provider aws --force

This runs terraform destroy to remove all AWS infrastructure. This is irreversible and will delete all data including RDS databases.

What Gets Removed

Troubleshooting

If platform destroy reports errors:

1. Check if containers are still running: docker ps | grep wbsp
2. Force-remove stuck containers: docker rm -f <container-name>
3. Remove the Docker network manually if needed: docker network rm wbsp
4. Remove orphaned volumes: docker volume prune

CLI Reference for Platform Operators

wbsp-platform provision

wbsp-platform provision --provider <provider> [flags]

wbsp-platform health

wbsp-platform health --provider <provider> [flags]

wbsp-platform destroy

wbsp-platform destroy --provider <provider> [flags]