WBSP
ProvidersDocsSign in
All pages

Useful Commands

A scenario-based reference for the commands an application developer uses to develop, deploy, and operate their app on the WBSP platform — all through the wbsp-app CLI — organised by target environment:

  • compose / dev / standalone — apps deployed on your machine (whole stack in containers, IDE + data-services only, or a single all-in-one container)
  • aws — apps deployed to the platform EKS cluster
  • aws.on-demand — apps deployed as on-demand AWS Lambda functions
  • aws.demo — throwaway sample-mode instances (Lambda, sample data baked in)

Each section is self-contained — commands are repeated where they apply to more than one environment. Operator commands that need direct AWS/cluster access (wbsp-platform, kubectl, aws, terraform) are a separate, operator-only concern and are not covered here.

Deploying and lifecycle. Configs declare a top-level destination: block and deploy with --destination <name> (reading .env.<destination>). Lifecycle commands (status, logs, remove, stop) scope by --enclave <name> instead (auto-detected from deployment state). See the application creator guide and wbsp-yaml-reference.md.

The binaries

Built into bin/ in the repository (rebuild after any Go change — see install-binaries):

BinaryRole
wbsp-appDeploy and manage applications (deploy, list, status, logs, stop, remove, services, prepare, dump-data)
wbsp-platformOperator tooling — provision/destroy infrastructure, platform health, cleanup
wbsp-apiThe platform API server (runs as a platform component)

Conventions used below

  • wbsp-app reads a .env beside the app's yaml (it never reads platform config).
  • Deploying to an aws destination assumes your AWS profile is set: export AWS_PROFILE=<profile> (or AWS_PROFILE in the app .env). Region, account, ECR, and EKS endpoint are auto-derived from the profile.
  • Naming: an app deploys into namespace wbsp-<tenant>-<app> with workload <tenant>-<app>. A parallel-services environment uses namespace wbsp-svc-<tenant>-<env-name>.

local-machine types — compose / dev / standalone

Apps run on your own machine. A destination's type: in the app's wbsp.yaml picks one of three deployment shapes:

  • compose — the whole app stack runs in containers (app + a per-app PostgreSQL/Redis), production-parity.
  • dev — ONLY the data services run in containers; you run the app from your IDE (live reload). The deploy writes a .env next to the app with discrete DATABASE_* / REDIS_* values pointing at localhost on derived ports — source it and start your app.
  • standalone — app + DB + Redis inside ONE ephemeral container.

All three share the same contract: deploy with wbsp-app deploy --destination <name>, expose the same discrete DATABASE_* / REDIS_* env vars as aws (no DATABASE_URL/REDIS_URL), use no Traefik (routes are ignored), and host-publish ports derived from the project number (Postgres 54NNN, Redis 63NNN, the app from its declared port; values above 65535 fold into [49152, 65535]).

Basics — deploy, list, status, remove

# Deploy / redeploy an app (the destination's type selects compose/dev/standalone)
wbsp-app deploy --config path/to/wbsp.yaml --destination dev

# Deploy AND write a deployment-diagram prompt for this app
#   → a text file with an image prompt (paste into Google "Nano Banana") plus a
#     mermaid block (render in VS Code / GitHub / mermaid.live). No secrets in it.
wbsp-app deploy --config path/to/wbsp.yaml --destination dev --diagram my-app.diagram.txt

# List local-machine apps. `local` is the umbrella (like bare `aws`): it shows
# EVERY local deployment — compose + dev + standalone — in one listing, each row
# labelled with its type. Name a single type instead to narrow to just that one.
wbsp-app list --provider local                    # all local types at once
wbsp-app list --provider local --tenant <tenant>  # scope to one tenant
wbsp-app list --provider local --json             # machine-readable (type per entry)
wbsp-app list --provider compose                  # just one type (compose / dev / standalone)
wbsp-app list --provider compose --health         # also probe each app

# Show one app's status (auto-detects destination if omitted)
wbsp-app status <app-name>
wbsp-app status <app-name> --json

# Stop an app but KEEP its data (database + Redis preserved)
#   The app stops running; deploy it again with the same name to reconnect to
#   the same database. Use this to pause without losing data.
wbsp-app stop <app-name> --tenant <tenant>
wbsp-app deploy --config path/to/wbsp.yaml --destination dev   # restart → same DB

# Remove an app and all its resources (DELETES the database — data is lost)
wbsp-app remove <app-name> --tenant <tenant>
wbsp-app remove <app-name> --tenant <tenant> --force   # no prompt

Dev — run the app from your IDE against containerised data services

With a type: dev destination, the deploy brings up DB/Redis in containers and writes a .env next to the app (discrete DATABASE_* / REDIS_* on localhost, derived ports). There is no app container and no Traefik — you run the app yourself from your IDE.

# Bring up DB/Redis + write the .env, then run your app from the IDE
wbsp-app deploy --config path/to/wbsp.yaml --destination dev
source .env && <run your app from the IDE>   # e.g. npm run dev

# Stop the dev environment but KEEP its data
wbsp-app stop <app-name> --tenant <tenant>

# Tear it down and DELETE its data
wbsp-app remove <app-name> --tenant <tenant>

Debugging — logs

wbsp-app logs <app-name>                 # last 100 lines
wbsp-app logs <app-name> --lines 500
wbsp-app logs <app-name> --follow        # stream

Debugging — connect to the local platform database

The platform Postgres runs as a docker-compose service (default container wbsp-postgres-1, user wbsp_admin, password wbsp_local_dev, port 5432).

# psql via the host (if you have psql installed)
PGPASSWORD=wbsp_local_dev psql -h localhost -p 5432 -U wbsp_admin -d <db-name>

# or exec into the container
docker exec -it wbsp-postgres-1 psql -U wbsp_admin -d <db-name>

# list databases (one per app with database.enabled)
docker exec -it wbsp-postgres-1 psql -U wbsp_admin -c '\l'

Debugging — inspect the app container directly

docker ps                                  # find the container
docker logs -f <container>
docker exec -it <container> sh

Sample data (shared with aws.demo)

# Dump the app's local DB to SQL seed files (→ sample-data/ next to the config)
wbsp-app dump-data --config path/to/wbsp.yaml
wbsp-app dump-data --config path/to/wbsp.yaml --data-only --exclude-table audit_log

An app's own docker-compose services (using, not providing)

If your app uses extra services for local development, run them with the app's own docker-compose.yaml (this is separate from the platform):

docker compose up -d
docker compose ps
docker compose logs -f <service>
docker compose down                 # stop (keeps named volumes)
docker compose down -v              # stop AND delete volumes (data loss)

To run those same services on AWS beside a deployed app, see Parallel services under aws.

aws

Apps deployed to the platform EKS cluster. Image is built, pushed to ECR, and rolled out as a Deployment behind Traefik. Requires AWS_PROFILE set and the platform provisioned on AWS.

Basics — deploy, list, status, remove

# Deploy / redeploy (builds + pushes image, rolls out) — `prod` is an aws destination
wbsp-app deploy --config path/to/wbsp.yaml --destination prod

# List apps (queries the cluster across tenants)
wbsp-app list --provider aws
wbsp-app list --provider aws --tenant <tenant>
wbsp-app list --provider aws --json
wbsp-app list --provider aws --health

# Status of one app (enclave auto-detected; pass --enclave to disambiguate)
wbsp-app status <app-name> --tenant <tenant>
wbsp-app status <app-name> --tenant <tenant> --json

# Remove an app and its resources
wbsp-app remove <app-name> --tenant <tenant>
wbsp-app remove <app-name> --tenant <tenant> --force

Debugging — logs

wbsp-app logs <app-name> --tenant <tenant> --lines 200
wbsp-app logs <app-name> --tenant <tenant> --follow

Connect to an app's platform database — wbsp-app db (preferred)

Apps with database.enabled get a private RDS database. RDS is not publicly reachable, but wbsp-app db tunnels to it through a persistent in-cluster relay (no manual relay/credentials needed). It reads the app's connection from the deployed pod env, so the app must be deployed first.

# Run migrations (the headline use case) — opens a tunnel, runs the command, tears down
wbsp-app db run --config wbsp.yaml -- npx prisma migrate deploy

# Interactive psql against the app's database
wbsp-app db connect --config wbsp.yaml

# Hold a tunnel open for a GUI client (TablePlus/DBeaver/…) — prints localhost:PORT + creds
wbsp-app db proxy --config wbsp.yaml      # auto-picks a free local port; --port to override

# Print the connection string
wbsp-app db url --config wbsp.yaml
  • The relay is provisioned with the platform (wbsp-platform provision --provider aws creates wbsp-db-proxy in the wbsp-system namespace); if it's missing, the commands say so.
  • A local-machine destination (compose/dev/standalone) connects straight to the docker-compose database (no relay).
  • The password is shown only by db proxy (so you can paste it into a GUI); other commands never print it.

Technical — parallel services environment

Run an app's docker-compose services (postgres, redis, forgejo, …) in a dedicated, isolated namespace beside the app. Full guide: parallel-services-guide.md.

# From the app directory (with a wbsp-services.yaml environment definition)
wbsp-app services up   --config wbsp-services.yaml            # additive
wbsp-app services up   --config wbsp-services.yaml --prune    # reconcile (remove dropped, keep volumes)
wbsp-app services down --config wbsp-services.yaml            # stop, retain volumes
wbsp-app services down --config wbsp-services.yaml --purge    # delete namespace + volumes (data loss)

# Redeploy the app afterwards so the connection env (<SERVICE>_HOST/_PORT) is injected
wbsp-app deploy --config wbsp.yaml --destination prod

Reaching the parallel-services containers directly (kubectl port-forward, Forgejo admin token, repo seeding) requires direct cluster/AWS access and is an operator task, outside the wbsp-app workflow.

aws.on-demand

Apps deployed as AWS Lambda functions (scale-to-zero, invoked on demand) rather than always-on Deployments — an aws destination with mode: on-demand. Same wbsp-app verbs as a normal aws destination; routing and ECR are shared, the compute backend differs. Below, lambda names an aws/mode: on-demand destination.

Basics — deploy, list, status, remove

wbsp-app deploy --config path/to/wbsp.yaml --destination lambda

wbsp-app list   --provider aws.on-demand
wbsp-app list   --provider aws.on-demand --json --health

wbsp-app status <app-name> --tenant <tenant>
wbsp-app remove <app-name> --tenant <tenant> --force

Debugging — logs

wbsp-app logs <app-name> --tenant <tenant> --lines 200
wbsp-app logs <app-name> --tenant <tenant> --follow

Technical — database & parallel services

mode: on-demand apps use the same platform RDS and can be allow-listed on a parallel-services environment exactly as a normal aws destination — see connect to an app's database and parallel services.

aws.demo

Throwaway sample-mode instances: a single image with sample data baked in, deployed as Lambda functions on demo subdomains (WBSP_SAMPLE_BASE_DOMAIN) — an aws destination with mode: demo. Build the image once with prepare, then spin up instances with deploy. Below, demo names an aws/mode: demo destination.

One-time — prepare the sample image

# (If the app has a database) generate seed SQL from your local DB first
wbsp-app dump-data --config path/to/wbsp.yaml

# Build + push the sample image (sample data baked in)
wbsp-app prepare --config path/to/wbsp.yaml
wbsp-app prepare --config path/to/wbsp.yaml --destination demo   # the demo destination

Basics — deploy, list, status, remove

# Spin up a sample instance
wbsp-app deploy --config path/to/wbsp.yaml --destination demo

wbsp-app list   --provider aws.demo
wbsp-app list   --provider aws.demo --json --health

wbsp-app status <app-name> --tenant <tenant>
wbsp-app remove <app-name> --tenant <tenant> --force

Debugging — logs

wbsp-app logs <app-name> --tenant <tenant> --lines 200
wbsp-app logs <app-name> --tenant <tenant> --follow

mode: demo apps carry their data inside the image (no platform RDS), so there is no external database to connect to. Wildcard TLS for the demo subdomains is provisioned and managed by the platform (an operator concern).

Rebuilding the binaries

After any Go change, rebuild all three binaries into bin/ with the version stamped in (--version reads it):

make build          # builds wbsp-app, wbsp-platform, wbsp-api into bin/ with -ldflags version

# Quick gate
go build ./... && go test ./...

Installing them onto another machine (clients/operators) is covered in installation.md.

Help for any command

wbsp-app --help
wbsp-app <command> --help          # e.g. wbsp-app deploy --help
wbsp-app services --help
wbsp-platform --help
wbsp-platform <command> --help

External reference documentation

The underlying tools the platform builds on — consult these when a command's behaviour or flags go beyond what's covered above.

Traefik (ingress)

Docker & Docker Compose

Forgejo (the worked-example parallel service)

PostgreSQL

Prisma (used by the example app)