kiven-dev — Dev Orchestrator

Shared local development infrastructure for Kiven. Manages Docker Compose, kind, CNPG, and Tilt. Service repos live as sibling directories.

First Time Setup

# 1. Clone
git clone git@github.com:kivenio/kiven-dev.git
cd kiven-dev

# 2. Init (installs mise, tools, git hooks, checks Docker)
task init

# 3. Clone all service repos
task repos:clone

# 4. Start everything
task dev
tilt up

Daily Workflow

cd kiven-dev
task dev                  # Start infra + kind + CNPG
tilt up                   # Start all services (auto-reload on code changes)

# Code in any sibling repo → Tilt rebuilds automatically
# Dashboard:    http://localhost:3000
# API:          http://localhost:8080
# Tilt UI:      http://localhost:10350

tilt down                 # Stop services
task dev:stop             # Stop everything

Directory Layout

~/workshops/kivenio/
├── kiven-dev/            ← THIS REPO (shared infra + orchestration)
│   ├── deploy/
│   │   ├── docker-compose.yml    ← PostgreSQL, Redpanda, Valkey, MinIO
│   │   ├── seed.sql              ← Dev seed data (org, user)
│   │   └── kind/                 ← kind cluster + CNPG test cluster
│   ├── migrations/               ← Database migrations (golang-migrate)
│   │   ├── 000001_initial_schema.up.sql
│   │   ├── 000001_initial_schema.down.sql
│   │   └── ...
│   ├── templates/                ← Template files for new service repos
│   ├── Tiltfile                  ← Orchestrates all services
│   ├── Taskfile.yml              ← task init, task dev, task infra:up...
│   └── .mise.toml                ← Shared tool versions + env vars
│
├── svc-api/              ← Service repos (each has task init + task run)
├── svc-agent-relay/
├── svc-provisioner/
├── kiven-agent/
├── provider-cnpg/
├── kiven-go-sdk/
├── dashboard/
└── ...

Hooks

When you cd into this repo (with mise shell hook):

• mise auto-activates: tools are available, env vars set
• First time: run task init to bootstrap everything

Each service repo has the same pattern:

cd ../svc-api
task init                 # mise trust + install + go mod download + git hooks
task run                  # Start the service
task test                 # Run tests

Commands

task --list               # See all tasks

# Init & Setup
task init                 # First time: mise + tools + hooks + Docker check
task repos:clone          # Clone all service repos as siblings
task repos:status         # Git status of all repos

# Infrastructure
task infra:up             # Start Docker Compose (PG, Kafka, Valkey, MinIO)
task infra:down           # Stop Docker Compose
task infra:reset          # Stop + delete all data

# Kubernetes
task kind:create          # Create kind cluster + CNPG operator
task kind:delete          # Delete kind cluster
task cnpg:deploy          # Deploy test PostgreSQL cluster
task cnpg:status          # Check CNPG status
task cnpg:connect         # Port-forward to test PG

# Services (from sibling repos)
task svc:api              # Run svc-api
task svc:relay            # Run svc-agent-relay
task svc:provisioner      # Run svc-provisioner
task agent                # Run kiven-agent
task frontend             # Run dashboard

# Database Migrations
task db:migrate           # Run all pending migrations
task db:rollback          # Rollback the last migration
task db:status            # Show current migration version
task db:create NAME=...   # Create a new migration
task db:seed              # Insert local dev seed data
task db:reset             # Drop everything, re-migrate, re-seed

# Database Connect
task psql                 # Connect to Kiven product DB
task psql:cnpg            # Connect to test CNPG cluster

# Dev lifecycle
task dev                  # Start everything (infra + kind + CNPG)
task dev:stop             # Stop everything

Database Migrations

Schema is managed by golang-migrate. Migrations live in migrations/ and run automatically when Docker Compose starts.

Creating a new migration

task db:create NAME=add_user_avatar
# Creates:
#   migrations/000003_add_user_avatar.up.sql
#   migrations/000003_add_user_avatar.down.sql

Edit both files — the .up.sql applies the change, the .down.sql reverses it. Wrap DDL in BEGIN; ... COMMIT; for atomicity.

Running migrations

# Docker Compose runs migrations automatically on `task infra:up`
# To run manually against a running database:
task db:migrate           # Apply all pending
task db:rollback          # Undo the last one
task db:status            # Show current version
task db:reset             # Nuclear option: drop everything, re-migrate, re-seed

Rules

1. Never edit a migration that has been applied — create a new one instead
2. Every .up.sql must have a matching .down.sql — rollbacks must work
3. Wrap DDL in transactions — BEGIN; ... COMMIT; so failures don't leave dirty state
4. Service plans seed data lives in migration 001 (needed in all environments)
5. Dev seed data (test org/user) lives in deploy/seed.sql (local dev only)

Templates & Scaffolding

templates/ contains complete starter configs for all repo types. See templates/README.md.

task scaffold:service NAME=svc-foo    # Scaffold a new Go service
task scaffold:sdk NAME=kiven-foo      # Scaffold a new Go SDK/library

Templates include: .editorconfig, .mise.toml, Taskfile.yml, .golangci.yml, .pre-commit-config.yaml, .vscode/, .github/workflows/ci.yml, Dockerfile, .air.toml.

Reusable CI Workflows

.github/workflows/ contains reusable GitHub Actions workflows:

• ci-go-reusable.yml — Go: lint, test, build, security, Docker
• ci-terraform-reusable.yml — Terraform: fmt, validate, lint, Trivy, Checkov
• ci-frontend-reusable.yml — Frontend: lint, type check, test, build
• docker-build-reusable.yml — Build & push Docker image to GHCR

Docs

• Development Guide
• Architecture