Skip to main content

Makefile Commands Reference

Complete reference for all available make commands in the Helix platform. The Makefile provides convenient shortcuts for common development tasks.

Quick Reference​

make help              # Show all available commands
make install           # Get started with fresh setup
make docker-up         # Start the entire platform
make test              # Run all tests
make docker-logs       # Watch logs from all services

Setup & Installation​

make install​

Install all dependencies and generate Prisma clients.

make install

What it does:

  • Runs npm ci --legacy-peer-deps
  • Generates Prisma clients for central and tenant schemas
  • Sets up the monorepo

When to use:

  • Fresh clone of repository
  • After pulling major changes
  • When dependencies are out of sync

make install-service​

Install dependencies for a specific service.

make install-service SERVICE=kira-service

What it does:

  • Installs root dependencies
  • Installs service-specific dependencies (if package.json exists)

When to use:

  • Added new npm package to a service
  • Service dependencies are missing

Local Development​

make build​

Build all services with Nx.

make build

What it does:

  • Runs nx run-many --target=build --all --configuration=production
  • Builds all services in parallel (Nx optimization)
  • Outputs to dist/ directory

When to use:

  • Before deploying
  • To verify all services compile
  • After making changes to shared libraries

make build-service​

Build a specific service.

make build-service SERVICE=api-gateway

What it does:

  • Runs nx build <service> --configuration=production
  • Builds only the specified service and its dependencies

When to use:

  • Working on specific service
  • Faster than building all services
  • Testing service compilation

make serve​

Serve a service locally with hot-reload.

make serve SERVICE=auth-service PORT=3001

What it does:

  • Starts the service in development mode
  • Enables hot-reload on file changes
  • Runs on specified port (default: 3000)

When to use:

  • Active development
  • Testing changes immediately
  • Debugging

Example:

# Start API Gateway on port 3000
make serve SERVICE=api-gateway

# Start KIRA on custom port
make serve SERVICE=kira-service PORT=3004

make lint​

Lint all services.

make lint

What it does:

  • Runs ESLint on all services
  • Checks TypeScript code quality
  • Reports errors and warnings

When to use:

  • Before committing
  • Fixing code quality issues
  • CI/CD runs this automatically

make lint-service​

Lint a specific service.

make lint-service SERVICE=tenant-service

When to use:

  • Working on specific service
  • Faster than linting all

make format​

Format code with Prettier.

make format

What it does:

  • Runs Prettier on all files
  • Formats TypeScript, JSON, YAML, Markdown
  • Applies consistent code style

When to use:

  • Before committing
  • After copying/pasting code
  • Fixing formatting inconsistencies

Testing​

make test​

Run tests for all services.

make test

What it does:

  • Runs nx run-many --target=test --all
  • Executes unit tests for all services
  • Reports test results

When to use:

  • Before committing
  • Before deploying
  • Verifying all tests pass

make test-service​

Run tests for specific service.

make test-service SERVICE=kira-service

What it does:

  • Runs nx test <service>
  • Executes only tests for specified service

When to use:

  • Working on specific service
  • Faster than running all tests
  • Debugging failing tests

make test-watch​

Run tests in watch mode.

make test-watch SERVICE=auth-service

What it does:

  • Runs tests continuously
  • Re-runs on file changes
  • Great for TDD workflow

When to use:

  • Active development
  • Writing tests
  • Debugging test failures

Example session:

make test-watch SERVICE=auth-service
# Edit auth-service code
# Tests automatically re-run
# Fix issues until tests pass
# Ctrl+C to exit

make test-coverage​

Run tests with coverage for all services.

make test-coverage

What it does:

  • Runs tests with coverage reporting
  • Generates coverage reports in coverage/
  • Shows coverage percentages

When to use:

  • Checking overall test coverage
  • Before major releases
  • Identifying untested code

make test-coverage-service​

Run tests with coverage for specific service.

make test-coverage-service SERVICE=vera-service

When to use:

  • Checking service-specific coverage
  • Need to hit 80%+ coverage target

Docker Commands​

make docker-build​

Build all Docker images.

make docker-build

What it does:

  • Builds all services using docker-compose build
  • Uses BuildKit for caching
  • Creates optimized production images

When to use:

  • After Dockerfile changes
  • Before testing in Docker
  • Preparing for deployment

Time: ~10-15 minutes (first build), ~2-5 minutes (with cache)

make docker-build-service​

Build specific service image.

make docker-build-service SERVICE=api-gateway

What it does:

  • Builds only specified service
  • Much faster than building all

When to use:

  • Working on specific service
  • Testing Docker changes
  • Faster iteration

make docker-up​

Start all services with Docker Compose.

make docker-up

What it does:

  • Starts all services in detached mode
  • Creates network and volumes
  • Shows running containers

When to use:

  • Running full platform locally
  • Testing service integration
  • Testing API Gateway routing

Verify:

make docker-ps
# OR
docker-compose ps

make docker-up-build​

Build and start all services.

make docker-up-build

What it does:

  • Rebuilds all images
  • Starts all services
  • Combines docker-build + docker-up

When to use:

  • After code changes
  • Ensuring latest code is running
  • Fresh start needed

make docker-down​

Stop all services.

make docker-down

What it does:

  • Stops all containers
  • Removes containers
  • Preserves volumes (data retained)

When to use:

  • End of work session
  • Switching branches
  • Clearing resources

make docker-restart​

Restart all services.

make docker-restart

What it does:

  • Restarts containers without rebuilding
  • Faster than down + up

When to use:

  • Applying config changes
  • Clearing service state
  • Quick refresh

make docker-logs​

Show logs for all services.

make docker-logs

What it does:

  • Streams logs from all containers
  • Color-coded by service
  • Follows new log entries

When to use:

  • Debugging issues
  • Monitoring service behavior
  • Watching startup sequence

Tip: Ctrl+C to stop following logs

make docker-logs-service​

Show logs for specific service.

make docker-logs-service SERVICE=kira-service

What it does:

  • Shows logs only for specified service
  • Less noisy than all logs

When to use:

  • Debugging specific service
  • Following service behavior
  • Cleaner log output

make docker-ps​

Show running containers.

make docker-ps

What it does:

  • Lists all Helix containers
  • Shows status and ports
  • Formatted table output

Output example:

Running containers:
NAMES                    STATUS              PORTS
helix-api-gateway        Up 2 minutes        0.0.0.0:3000->3000/tcp
helix-auth-service       Up 2 minutes        0.0.0.0:3001->3001/tcp
helix-postgres           Up 2 minutes        0.0.0.0:5432->5432/tcp
helix-redis              Up 2 minutes        0.0.0.0:6379->6379/tcp

make docker-clean​

Remove all containers, images, and volumes.

make docker-clean

What it does:

  • Stops all containers
  • Removes containers and volumes
  • Prunes Docker system
  • ⚠️ Deletes all data

When to use:

  • Fresh start needed
  • Disk space cleanup
  • Troubleshooting Docker issues

Warning: This deletes database data. Back up if needed.

Database Commands​

make migrate​

Run all database migrations.

make migrate

What it does:

  • Runs central schema migrations
  • Runs tenant schema migrations
  • Applies all pending migrations

When to use:

  • After pulling schema changes
  • Setting up new environment
  • Applying new migrations

make migrate-central​

Run central database migrations only.

make migrate-central

What it does:

  • Runs prisma migrate deploy for central schema
  • Applies only central DB migrations

When to use:

  • Central schema changed
  • Selective migration needed

make migrate-tenant​

Run tenant database migrations only.

make migrate-tenant

What it does:

  • Runs prisma migrate deploy for tenant schema
  • Applies only tenant DB migrations

When to use:

  • Tenant schema changed
  • Selective migration needed

make migrate-create​

Create a new migration.

make migrate-create NAME=add_users_table SCHEMA=central

Parameters:

  • NAME - Migration name (required)
  • SCHEMA - Which schema (central or tenant)

What it does:

  • Creates new migration file
  • Opens interactive migration prompt
  • Generates SQL from schema changes

Example:

# Create central schema migration
make migrate-create NAME=add_audit_log SCHEMA=central

# Create tenant schema migration
make migrate-create NAME=add_products_table SCHEMA=tenant

make migrate-reset​

Reset database (destructive).

make migrate-reset

What it does:

  • Drops all tables
  • Re-runs all migrations
  • ⚠️ Deletes all data
  • Asks for confirmation

When to use:

  • Development only
  • Starting fresh
  • Schema conflicts

Warning: Never run in production or staging!

make db-seed​

Seed database with test data.

make db-seed

What it does:

  • Runs prisma/seed.ts (if exists)
  • Populates test data

When to use:

  • After migration reset
  • Setting up test environment
  • Generating sample data

make prisma-generate​

Generate Prisma clients.

make prisma-generate

What it does:

  • Generates TypeScript clients from schemas
  • Creates type-safe query builders
  • Updates node_modules/@prisma/client

When to use:

  • After schema changes
  • After pulling schema updates
  • TypeScript errors about Prisma types

make prisma-studio​

Open Prisma Studio (database GUI).

make prisma-studio

What it does:

When to use:

  • Viewing database contents
  • Manual data manipulation
  • Debugging data issues

Tip: Opens central DB. For tenant DB, run manually:

npx prisma studio --schema=prisma/tenant/schema.prisma --port 5556

Utility Commands​

make clean​

Clean build artifacts.

make clean

What it does:

  • Removes dist/ directory
  • Removes coverage/ directory
  • Resets Nx cache

When to use:

  • Build errors
  • Disk space cleanup
  • Fresh build needed

make clean-all​

Clean everything including node_modules.

make clean-all

What it does:

  • Runs make clean
  • Removes all node_modules directories
  • Removes Nx cache

When to use:

  • Dependency issues
  • Major version updates
  • Complete fresh start

Note: Run make install after this

make health-check​

Check health of all running services.

make health-check

What it does:

  • Curls /health endpoint for each service
  • Displays JSON responses
  • Shows which services are up

When to use:

  • After docker-compose up
  • Verifying deployment
  • Debugging service issues

Output example:

Checking service health...

API Gateway:
{
  "status": "healthy",
  "service": "api-gateway",
  "timestamp": "2024-01-15T10:30:00Z"
}

Auth Service (via Gateway):
{
  "status": "healthy",
  "service": "auth-service"
}

Common Workflows​

Starting Fresh Development​

# Clone repository
git clone <repo-url>
cd helix-platform

# Install dependencies
make install

# Start all services
make docker-up-build

# Check everything is running
make docker-ps
make health-check

Daily Development Workflow​

# Start services
make docker-up

# Work on specific service
make serve SERVICE=your-service PORT=3010

# Run tests while developing
make test-watch SERVICE=your-service

# Check logs if issues
make docker-logs-service SERVICE=your-service

# Stop when done
make docker-down

Testing Before Commit​

# Lint code
make lint

# Format code
make format

# Run all tests
make test

# Build all services
make build

Debugging Service Issues​

# Check running containers
make docker-ps

# View logs
make docker-logs-service SERVICE=problematic-service

# Restart service
docker-compose restart problematic-service

# Rebuild and restart
make docker-build-service SERVICE=problematic-service
docker-compose up -d problematic-service

# Check health
make health-check

Database Development​

# Edit schema
code prisma/central/schema.prisma

# Create migration
make migrate-create NAME=add_new_table SCHEMA=central

# Apply migration
make migrate-central

# Verify in Prisma Studio
make prisma-studio

# Regenerate client
make prisma-generate

Working with Multiple Services​

# Build specific services
make build-service SERVICE=api-gateway
make build-service SERVICE=auth-service

# Test specific services
make test-service SERVICE=api-gateway
make test-service SERVICE=auth-service

# Run services together in Docker
docker-compose up api-gateway auth-service postgres redis

Advanced Usage​

Building with Cache​

# Docker BuildKit is enabled by default in Makefile
make docker-build

# Force rebuild without cache
DOCKER_BUILDKIT=1 docker-compose build --no-cache

Selective Service Startup​

# Start only required infrastructure
docker-compose up -d postgres redis

# Start specific services
docker-compose up -d api-gateway auth-service

# Check what's running
make docker-ps

Testing with Different Environments​

# Test with staging config
ENV=staging make test-service SERVICE=auth-service

# Build for production
ENV=production make build

Tips & Tricks​

Tip 1: Chain Commands​

# Clean, install, and test
make clean-all && make install && make test

# Build and start Docker
make build && make docker-up-build

Tip 2: Watch Logs from Multiple Services​

# In separate terminals
make docker-logs-service SERVICE=api-gateway
make docker-logs-service SERVICE=auth-service

# Or use docker-compose
docker-compose logs -f api-gateway auth-service

Tip 3: Quick Health Check Script​

#!/bin/bash
# save as scripts/quick-health.sh

services=("api-gateway" "auth-service" "tenant-service" "kira-service")

for service in "${services[@]}"; do
  echo "Checking $service..."
  curl -s http://localhost:3000/health | jq .
done

Tip 4: Debugging with Docker Exec​

# Access service container
docker-compose exec auth-service sh

# Check environment variables
docker-compose exec auth-service env | grep DATABASE

# Check if service is listening
docker-compose exec auth-service netstat -tlnp

Troubleshooting​

Issue: make install fails​

Solutions:

# Clear npm cache
npm cache clean --force

# Use legacy peer deps
npm install --legacy-peer-deps

# Delete lock file and retry
rm package-lock.json
make install

Issue: make serve port already in use​

Solutions:

# Use different port
make serve SERVICE=auth-service PORT=3101

# Kill process using port
lsof -ti:3001 | xargs kill -9

# Stop Docker services
make docker-down

Issue: make test fails with database errors​

Solutions:

# Start database
docker-compose up -d postgres

# Run migrations
make migrate

# Generate Prisma client
make prisma-generate

# Retry tests
make test

Issue: make docker-up fails​

Solutions:

# Check Docker is running
docker ps

# Clean Docker state
make docker-clean

# Rebuild and start
make docker-up-build

# Check logs for errors
make docker-logs

Environment Variables​

Many commands respect environment variables:

# Use custom port
PORT=3100 make serve SERVICE=auth-service

# Specify environment
ENV=staging make build

# Custom service name
SERVICE=kira-service make test-service

Command Combinations​

Full Development Cycle​

# 1. Install
make install

# 2. Start infrastructure
docker-compose up -d postgres redis

# 3. Run migrations
make migrate

# 4. Start services
make docker-up

# 5. Check health
make health-check

# 6. Watch logs
make docker-logs

Pre-Commit Checklist​

make format        # Format code
make lint          # Check linting
make test          # Run tests
make build         # Verify builds

Deploy to Staging Checklist​

make test-coverage           # Ensure coverage > 80%
make docker-up-build         # Test locally
make health-check            # Verify health
git push origin develop      # Deploy (GitHub Actions handles rest)

Quick Command Reference​

CommandPurposeTime
make installInstall dependencies2-5 min
make buildBuild all services2-4 min
make testRun all tests2-3 min
make docker-upStart platform1-2 min
make docker-buildBuild images10-15 min
make migrateApply migrations10-30 sec
make health-checkCheck services5-10 sec
make docker-logsView logsInstant
make cleanClean artifacts10 sec

Need Help?​

Run make help to see all available commands with descriptions.

For more information:

  • Docker issues: See docs/architecture/docker-setup.md
  • Testing: See test files in each service
  • Database: See docs/architecture/database-prisma.md
  • Deployment: See docs/deployment/deployment-guide.md