Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started with Tenki Cloud Development

Last updated: 2025-06-12

This guide will help you set up your development environment and run Tenki Cloud locally.

Prerequisites

Required Software

  1. Nix
  2. Devenv
  3. Direnv
  4. 1Password
  5. 1Password CLI
    • Integrate with 1Password CLI
    • Verify you have access to luxor/Engineering by running: 
      op account list
op vault list --account=luxor
    • If luxor isn’t showing as luxor.1password.com, try other accounts from op account list: 
      op vault list --account=<account_name>
    • If luxor account isn’t showing at all, contact administrator

Verify Prerequisites

nix --version
devenv version
direnv --version
op --version

Hardware Requirements

  • RAM: 16GB minimum (32GB recommended)
  • CPU: 4 cores minimum (8 cores recommended)
  • Disk: 50GB free space

Initial Setup

1. Clone the Repository

git clone https://github.com/luxorlabs/tenki.app.git
cd tenki.app

2. Pull Setup Keys

sh tools/scripts/setup.sh

If you run into an issue where it’s using the wrong account, try this:

op account list
# account can be `luxor` if url is `luxor.1password.com`,
# or `my` if url is `my.1password.com` and there's only one account
# or the 3rd column (USER ID) if you have multiple accounts if you're getting the same url for all accounts.
sh tools/scripts/setup.sh <account>

Example: sh tools/scripts/setup.sh luxor

If you run into permission issues, try chmod +x ./tools/scripts/*.sh

3. Enable Development Environment

direnv allow

This will:

  • Install all required tools (Go, Node.js, pnpm, etc.)
  • Set up environment variables
  • Configure Git hooks

4. Install Dependencies

# Install all npm dependencies
pnpm install

# Generate protobuf code
bufgen

# Run Go mod tidy
tidy

# Update /etc/hosts entries
sync-hosts

# Initialize database
tb-format

5. Hosts and Other Setup

NOTE: Before running this script, the host needs to have hostctl installed since it requires elevated execution. Verify with hostctl --version

Add tenki.lab hosts:

sync-hosts

Format TigerBeetle database:

tb-format

Managing Environment and Secrets

Secret Files

  • resources/secrets/*.sops.yaml - Encrypted secrets pushed/committed to git
  • resources/secrets/*.local.yaml - Decrypted secrets (gitignored)

Commands

  • env-sync - Decrypt secrets and create a copy on individual apps/backend folders
  • env-decrypt - Decrypt secrets, *.sops.yaml to *.local.yaml
  • env-encrypt - Encrypt secrets, *.local.yaml to *.sops.yaml

Pulling Latest Secrets

  1. git pull to get the latest secrets
  2. env-sync to create your own copy of the secrets

Updating Secrets

  1. Locate the secret you want to update in resources/secrets/*.local.yaml
  2. Run env-encrypt to encrypt the secret
  3. Commit the changes and push to GitHub

Overwriting Secrets (usually only needed once per setup)

  • For Next.js apps: .env.local will overwrite .env. Copy .env.sample to .env.local and update values
  • For backend: engine.local.yaml will overwrite engine.yaml. Copy engine.sample.yaml to engine.local.yaml and update values

Seeding and Migrations

NOTE: Before running these commands, the database must be up and running. Run dev up or devenv up

  • Run db up to migrate the database
  • Run psql -U postgres -d tenki -f ./tools/seed/20240915152331_seed.sql to seed the database with CSP & related data

Or run db deploy to run both.

  • Run db seed to seed the database with users, workspaces, projects, VMs. After this you can start the dev server & login with:
    • Email: odin@tenki.cloud
    • Password: tenki.app

Database Commands

db up          # Run migrations
db down        # Rollback last migration
db reset       # Reset database
db status      # Check migration status
db create add_users_table  # Create new migration
db deploy      # Run migrations and seed
db nuke        # Complete database reset
db seed        # Seed test data

For Redpanda, see internal docs to set it up.

NOTE: This should be automated in the future

Running the Application

Quick Start

# Start all services
dev up

# Access the application
open https://app.tenki.lab:4001

Development Domains

  • Frontend: https://app.tenki.lab:4001
  • Temporal UI: https://temporal.tenki.lab
  • Redpanda Console: https://redpanda.tenki.lab
  • Grafana: https://grafana.tenki.lab
  • API: https://api.tenki.lab

Individual Services

# Start specific service
dev up postgres
dev up temporal
dev up engine

# Other options
dev up --simple  # Minimal output
dev up -D        # Detached mode

# Service management
dev start [service]     # Start specific service
dev stop [service]      # Stop specific service
dev restart [service]   # Restart service
dev logs [service]      # View service logs
dev list               # List all services

# Examples
dev start  # (enter, then choose services, hit tab to select multiple)
dev start engine
dev logs -f postgres  # Follow logs

Development Workflow

Frontend Development

cd apps/app
pnpm dev

# Run type checking
pnpm type-check

# Run linting
pnpm lint
pnpm lint:fix

Backend Development

# Run Go services
cd backend
go run cmd/engine/main.go

# Run tests
gotest

# Generate mocks
gomocks

# Build binaries
make build-engine

Database Changes

# Create new migration
db create add_user_preferences

# Apply migrations
db up

# Rollback migration
db down

# Reset database
db reset

Resetting Existing/Flaky Local Environment

  • Close/stop all services
  • Run reset-local
  • In another terminal:
    • Run db deploy

Common Tasks

Adding shadcn/ui Components

# Add a new component
pnpm -F @shared/ui ui:add
# or
pnpm -F @shared/ui ui:add <component>

Then add the component to the exports in packages/ui/package.json:

"exports": {
  "./button": "./src/components/ui/button.tsx",
  "./alert-dialog": "./src/components/ui/alert-dialog.tsx"
}

Generating App Icons

pnpm -F app generate-icon

Then:

  • Copy public/images/favicon-196.png to:
    • src/app/favicon.png
    • src/app/icon.png
  • Copy all rel="apple-touch-startup-image" from src/asset-generator.html to src/app/layout.tsx

Adding a New API Endpoint

  1. Define proto in proto/tenki/cloud/
  2. Run bufgen to generate code
  3. Implement service in backend/internal/domain/
  4. Add tRPC router in apps/app/src/server/api/

Running Tests

# All tests
pnpm test
gotest

# Specific package
pnpm -F app test
cd backend && go test ./pkg/...

# Integration tests
gotest-integration

# With coverage
cd backend && go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Debugging

# Check service health
dev list

# View all logs
dev logs

# Restart a service
dev restart engine

# Database console (direct connection)
psql -h localhost -U postgres -d tenki

# Temporal CLI
temporal workflow list

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :4001

# Kill process
kill -9 <PID>

Database Connection Issues

# Restart postgres
dev restart postgres

# Check logs
dev logs postgres

# Reset database
db nuke

Proto Generation Fails

# Clean and regenerate
rm -rf backend/pkg/proto
bufgen

Node Modules Issues

# Clean and reinstall
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install

Next Steps

Editor Setup

VS Code

  1. Install recommended extensions:

    • Go
    • ESLint
    • Prettier
    • Proto3

  2. Use workspace settings:

    {
  "editor.formatOnSave": true,
  "go.lintTool": "golangci-lint"
}

GoLand/WebStorm

  1. Enable Go modules
  2. Set up file watchers for:
    • gofmt
    • prettier
    • eslint

Runner Prerequisites

Setting up GitHub App

  • Create Github Organization, skip this if you already have one
  • Create a github app
    • run pnpm -F github-app run create or pnpm -F github-app run create -o <org>
    • if name already exist, change it and continue
    • once done it’ll redirect you to a success screen, close the tab,
  • In github-app-response.json take note of the slug, pem, webhook_secret, client_id and client_secret