Deploy Pipeline

tawa deploy is the only supported way to deploy services on the Tawa platform. Never use kubectl, helm, or docker commands directly for deployments — the builder handles the complete pipeline automatically.

The Complete Deploy Sequence

When you run tawa deploy, the builder executes the following steps in order:

1. Trigger build — The CLI sends your current commit SHA to the builder, which queues a new build job.
2. Clone repo — The builder clones your repository at the exact commit you pushed. Private repos are accessed using an injected Forgejo token.
3. Parse catalog-info.yaml — The builder reads your service configuration: framework, databases, routes, dependencies, pod tier, and any deploy-gated tests.
4. Deploy gate check — The builder verifies your org wallet has enough gas to cover three months of hosting for the declared pod tier. If the balance is insufficient, the build is blocked before any Docker work begins.
5. Generate Dockerfile — If no Dockerfile exists in your repo, the builder auto-generates one based on your framework annotation (nextjs, express, hono, fastify, static, worker).
6. Docker build — The image is built and tagged with the short commit SHA.
7. Docker push — The image is pushed to the platform container registry.
8. Provision databases — If spec.databases is declared, the builder generates connection strings and creates the necessary secrets. These are injected as MONGODB_URI, REDIS_URL, or NEO4J_URI.
9. Provision OAuth — If spec.auth.mode: sso is declared, the builder creates or updates a Bio-ID OAuth client and injects BIO_CLIENT_ID and BIO_CLIENT_SECRET.
10. Resolve dependencies — Internal dependencies declared in spec.internalDependencies or spec.dependencies are resolved to reachable service URLs and injected as env vars.
11. Helm deploy — The service is deployed to Kubernetes via Helm. All env vars, secrets, and config are injected at this stage.
12. DNS configuration — A DNS record is created or updated automatically via Cloudflare for the service's environment subdomain.
13. Health check — The builder waits for the pod to become healthy by probing the health endpoint (/health for most frameworks, /api/health for Next.js).
14. Deploy-gated tests — If spec.tests is declared (requires insureco.io/catalog-version: "0.5.0"), smoke tests run against the deployed service. Failures mark the build as failed but do not roll back the pod.
15. Koko registration — The service and its routes are registered in the Koko service registry. External API routes declared in spec.routes become accessible through Janus.

Build Status Flow

queued → cloning → building → pushing → deploying → testing → completed
                                                              ↘ failed

If any step fails, the build status moves to failed. The pod from the previous successful deploy continues running. Check build logs with tawa logs --build <id> to diagnose failures.

Deploy Commands

Core Deploy

Build & Status

Pod Management

Diagnostics & Audit

Environment Targets

What the Builder Does Automatically

You do not need to write or manage any of the following — the builder handles them on every deploy:

• Dockerfile generation — Based on your insureco.io/framework annotation. You rarely need to write your own.
• Database secrets — Connection strings for MongoDB, Redis, and Neo4j are generated and injected automatically. Redeploys never touch your data.
• OAuth client — Bio-ID client ID and secret are provisioned and injected when auth: mode: sso is set.
• DNS records — Cloudflare records are created or updated automatically for the correct environment subdomain.
• Service registration — Your service and its routes are registered in Koko after a successful deploy.

Key Rules

NOTE: Always commit and push your changes before running tawa deploy. The builder clones your repo at the latest pushed commit — local uncommitted changes are not included.

NOTE: Deploys are idempotent. Running tawa deploy again updates the existing deployment rather than creating a duplicate. Databases, DNS records, and OAuth clients are updated in place.

NOTE: Redeploying never modifies your database data. Only the application code and configuration are updated.

IMPORTANT: Never use kubectl apply, helm upgrade, or docker push for deployments. These bypass the builder pipeline and will cause your service to fall out of sync with the platform registry, secrets management, and DNS.