Platform Runbook

This runbook provides frequently used commands for operating the CTMS platform. Commands are organized by component with both native commands and Make-based shortcuts.

Environment Selection

Most commands support environment selection. Add ENV=production to use production configuration:

make <command> ENV=production

---

Quick Reference

Task	Component	Command
Start web app	Web	make dev or bun run dev
Deploy web app	Web	make deploy-prod
Run data ingestion	Ingester	make batch
Build DBT models	DBT	make build
Clear analytics cache	Cube	make cache-bust
Check health	Cube	make health

---

1. Web Application (hb-life-science-web)

The Next.js application serving the CTMS user interface.

Core Commands

Task	Make Command	Native Command
Install dependencies	make setup	bun install
View configuration	make status	—
Start development server	make dev	bun run dev
Build for production	make build	bun run build
Start production server	make start	bun run start
Lint code	make lint	bun run lint

Vercel Deployment

Task	Make Command	Native Command
Link to Vercel project	make vercel-link	vercel link
Deploy preview	make deploy	vercel
Deploy production	make deploy-prod	vercel --prod
Pull env variables	make vercel-env-pull	vercel env pull .env.local
Add env variable	make vercel-env-add KEY=name VALUE=value	vercel env add
View logs	make vercel-logs	vercel logs

Optional Commands

Task	Command
Generate entity APIs	bun run generate:apis
Generate OpenAPI spec	bun run openapi:generate
Validate OpenAPI spec	bun run openapi:validate
Export Postman collection	bun run openapi:postman
Clean build artifacts	make clean

---

2. Data Ingester (ctms-ingester-dlthub)

DLT Hub pipeline that extracts data from Frappe API and loads into PostgreSQL.

Core Commands

Task	Make Command	Native Command
Install dependencies	make setup	pip3 install -r requirements.txt
View configuration	make status	—
Run all endpoints	make batch	python3 bot_frappe_api_to_db.py
Run production batch	make batch ENV=production	—

Optional Commands

Task	Make Command	Native Command
Run single endpoint	make run ENDPOINT='/doctype/Patient'	—
Run Patient endpoint	make run-patient	—
Run Study endpoint	make run-study	—
Purge database schemas	make purge	python3 db_schema_purge.py

---

3. DBT Pipeline (ctms-lakehouse-dbt)

DBT project that transforms raw data through Bronze → Silver → Gold layers.

Core Commands

Task	Make Command	Native Command
Install dependencies	make setup	pip install -r requirements-dbt.txt
Install DBT packages	make deps	dbt deps
Verify connection	make debug	dbt debug
View configuration	make status	—
Build all models	make build	dbt build
Run daily pipeline	make daily	—

Build Commands

Task	Make Command	Native Command
Load seed data	make seed	dbt seed
Run models only	make run	dbt run
Run tests only	make test	dbt test
Generate docs	make docs	dbt docs generate

Data Quality (Elementary)

Task	Make Command	Native Command
Build Elementary tables	make elementary	dbt run --select elementary
Generate HTML report	make report	edr report
View report in browser	make view-report	open edr_target/report.html

Cleanup

Task	Make Command	Native Command
Clean compiled files	make clean	rm -rf target/

---

4. Semantic Cube (ctms-semantic-cube)

Cube.dev semantic layer providing analytics API.

Core Commands

Task	Make Command	Native Command
Install dependencies	make setup	npm install
View configuration	make status	—
Start dev server	make dev	npm run dev
View logs	make logs	tail -f logs/*.log

Cache Management

Task	Make Command	Native Command
Clear production cache	make cache-bust	flyctl apps restart ctms-semantic-cube
Clear local cache	make cache-bust-local	rm -rf .cubestore

Production Deployment

Task	Make Command	Native Command
Deploy to Fly.io	make deploy	flyctl deploy
Restart production	make restart	flyctl apps restart ctms-semantic-cube

Validation

Task	Make Command	Native Command
Check server health	make health	curl https://ctms-semantic-cube.fly.dev/readyz
Get schema metadata	make meta	curl .../cubejs-api/v1/meta
Validate cube files	make validate	—

---

Common Workflows

Daily Data Refresh (Production)

Run these commands in sequence to refresh all data:

# 1. Extract data from Frappe API
cd ctms-ingester-dlthub
make batch ENV=production

# 2. Transform data through DBT layers
cd ../ctms-lakehouse-dbt
make daily ENV=production

# 3. Clear analytics cache
cd ../ctms-semantic-cube
make cache-bust

Initial Setup (New Environment)

# 1. Setup Ingester
cd ctms-ingester-dlthub
make setup
make status

# 2. Setup DBT
cd ../ctms-lakehouse-dbt
make setup
make deps
make debug

# 3. Setup Cube
cd ../ctms-semantic-cube
make setup
make status

# 4. Start Web App
cd ../hb-life-science-web
bun install
bun run dev

Troubleshooting Data Issues

# Check ingester status
cd ctms-ingester-dlthub
make status

# Verify DBT connection
cd ../ctms-lakehouse-dbt
make debug

# Check Cube health
cd ../ctms-semantic-cube
make health ENV=production

# View Cube logs
make logs

---

Environment Files

Each component uses environment files for configuration:

Component	Development	Production
Ingester	.env	.env.production
DBT	.env	.env.production
Cube	.env	.env.production
Web App	.env.local	Environment variables

---

Useful Fly.io Commands

For components deployed on Fly.io (Semantic Cube):

Task	Command
View app status	flyctl status
View logs	flyctl logs
SSH into container	flyctl ssh console
List secrets	flyctl secrets list
Set secret	flyctl secrets set KEY=value

---

Useful Vercel Commands

For components deployed on Vercel (CTMS Web App):

Task	Command
Link project	vercel link
Deploy preview	vercel
Deploy production	vercel --prod
List deployments	vercel list
View logs	vercel logs
Pull env variables	vercel env pull
Add env variable	vercel env add VAR_NAME
Remove env variable	vercel env rm VAR_NAME
List env variables	vercel env ls

First-Time Vercel Setup

# 1. Install Vercel CLI
npm install -g vercel

# 2. Login to Vercel
vercel login

# 3. Link your project
cd hb-life-science-web
make vercel-link

# 4. Set environment variables
make vercel-env-add KEY=NEXT_PUBLIC_SUPABASE_URL VALUE=https://...
make vercel-env-add KEY=NEXT_PUBLIC_SUPABASE_ANON_KEY VALUE=...

# 5. Deploy to production
make deploy-prod

---

Getting Help

Each component's Makefile includes built-in help:

cd <component-directory>
make help

This displays all available commands with descriptions.