Complete Workflow — Creating an App from Scratch

Here is an end-to-end walkthrough to understand how everything fits together.

Step 1 — Create the App

You go into the UI, "New App", you give it a name. Wakastart creates:

• The App record in the DB
• A dedicated space in the registry for your future Docker images
• A dedicated space in the secrets vault for your credentials

Step 2 — Define the Architecture

You navigate to Infra → Architecture. You create:

1. A managed Repository exemple-backend (Wakastart creates the repo on GitHub via the Waka-Start org)
2. A ServiceDefinition backend (role: BACK, exposure: PUBLIC, port: 3000, from the exemple-backend repo)
3. A DatabaseDefinition primary (engine: PostgreSQL, defaultMode: IN_CLUSTER)
4. A StorageBucketDefinition medias (defaultMode: MANAGED)

Step 3 — Create an environment

You create a dev environment:

• gitRef: main
• autoDeploy: true

→ Wakastart creates for this environment:

• A dedicated Kubernetes namespace that isolates the env's resources
• The DatabaseInstance and StorageBucketInstance matching the Definitions (in-cluster in dev)
• The application credentials to access the env's resources
• A platform-managed URL app.dev.exemple.wakastart.app

Step 4 — Build and deploy

You commit code, you push to main. Wakastart:

1. Detects the push via a GitHub webhook
2. Creates a Build in PENDING
3. The build moves through BUILDING → PUSHING → SUCCEEDED
4. In AUTO mode → the image is deployed to the dev env
5. A Deployment appears, status PROGRESSING, then SUCCEEDED
6. Your pods are running, your API is accessible at app.dev.exemple.wakastart.app

Step 5 — Promote to prod

You create a prod environment:

• gitRef: prod (dedicated branch)
• autoDeploy: true
• You override your DatabaseInstance: mode: MANAGED (managed PostgreSQL, HA + auto backups)
• You add a custom domain exemple.com

→ Your app now runs in prod on managed infrastructure, isolated from dev.

---

Frequently asked questions

"Why is there a Definition / Instance distinction?" → So that you can define your architecture once and duplicate it across multiple environments with local overrides (cheaper plan in dev, more powerful in prod).

"My build failed, where do I look?" → Infra → Builds → click on the build: you see the Docker build logs and the precise error.

"My service won't start, where do I look?" → Infra → Environments → {env} → Services → {service}: Logs tab for the container logs, Deployments tab to see if the deployment failed.

"How do I rotate my DB credentials?" → For databases in MANAGED mode: rotation is triggered on the cloud provider side. K8s secrets are regenerated and services are redeployed.

"How do I restore a backup?" → Infra → Backups: you see the list of backups, click Restore on the one you want.