Deployment Overview

tx-agent-kit deploys staging and production environments with immutable container images. Compose remains available, and Kubernetes supports Mac Studio k3s (staging/prod) plus optional GKE deploys from the same artifact.

Deployment model

The deployment workflow has four stages:

Build images: build and optionally push container images for api and worker.
Run migrations: apply database schema changes to the target environment.
Deploy runtime target: Compose or Kubernetes (Mac k3s / optional GKE).
Smoke tests: verify critical API flows are working in the deployed environment.

What gets deployed

Component	Deployment method
API	Container image via Compose or Helm
Worker	Container image via Compose or Helm
OTEL Collector	Compose service or Helm workload
Web	Deployed separately (e.g., Vercel, static hosting)
Mobile	Deployed separately (e.g., EAS, App Store)

The API and Worker are the only components deployed as containers from this repository. The web and mobile apps are deployed through their respective platforms and configured to point at the deployed API via API_BASE_URL.

Secrets handling

All deployment secrets are stored in 1Password vaults and referenced via op:// URIs in the environment templates deploy/env/staging.env.template and deploy/env/prod.env.template.

During deployment, op inject resolves these references into a rendered .env file that is passed to Docker Compose. The rendered file is never committed to git.

Environment configuration

Both staging and production environments share the same configuration structure:

Variable	Source
`DATABASE_URL`	1Password (`op://<project-vault>/<env>/DATABASE_URL`)
`AUTH_SECRET`	1Password
`TEMPORAL_ADDRESS`	1Password
`API_CORS_ORIGIN`	1Password
`OTEL_EXPORTER_OTLP_ENDPOINT`	Literal (`http://otel-collector:4318`)
`OTEL_COLLECTOR_BACKEND`	Literal (`gcp` or `oss`)
`GOOGLE_CLOUD_PROJECT`	1Password (for GCP telemetry)

Quick reference

# Build container images
pnpm deploy:build-images

# Push images and pin digests
PUSH_IMAGES=1 pnpm deploy:build-images

# Run migrations
pnpm deploy:migrate:staging
pnpm deploy:migrate:prod

# Deploy to staging via Compose
pnpm deploy:staging

# Deploy to production via Compose
pnpm deploy:prod

# Deploy Mac k3s staging/prod
pnpm deploy:k8s:mac:staging deploy/artifacts/images-<sha>.env
pnpm deploy:k8s:mac:prod deploy/artifacts/images-<sha>.env

# Dedicated Mac k3s staging verification lane (separate from standard integration suites)
pnpm deploy:k8s:verify:staging deploy/artifacts/images-<sha>.env

# Optional GKE deploy from the same artifact
pnpm deploy:k8s:gke deploy/artifacts/images-<sha>.env

# Run smoke tests against a deployed environment
API_BASE_URL=https://api.example.com pnpm deploy:smoke

Assumptions and Defaults

Mac Studio runner has k3s, kubectl, helm, op, and cloudflared.

Page	Description
Build Images	Image build and push pipeline
Migrations	Database migration workflow
Deploy with Compose	Full deployment process
Deploy with Kubernetes	Mac `k3s` and optional GKE release flow
Cloudflare Tunnel	Mac-hosted API internet exposure through cloudflared
Smoke Tests	Post-deployment verification