Helix Platform - Makefile Commands

This document provides a comprehensive guide to all available Makefile commands for the Helix platform.

Quick Start

# Show all available commands
make help

# Install dependencies
make install

# Start all services with Docker
make docker-up-build

# Check health of all services
make health-check

Command Categories

1. Setup & Installation

`make install`

Installs all project dependencies and generates Prisma clients.

make install

`make install-service`

Installs dependencies for a specific service.

make install-service SERVICE=auth-service

2. Local Development

`make build`

Builds all services using Nx in production mode.

make build

`make build-service`

Builds a specific service.

make build-service SERVICE=auth-service

`make serve`

Serves a specific service locally (useful for development).

make serve SERVICE=auth-service PORT=3001

`make lint`

Lints all services.

make lint

`make lint-service`

Lints a specific service.

make lint-service SERVICE=api-gateway

`make format`

Formats all code with Prettier.

make format

3. Testing

`make test`

Runs tests for all services.

make test

`make test-service`

Runs tests for a specific service.

make test-service SERVICE=auth-service

`make test-watch`

Runs tests in watch mode for a specific service (useful during development).

make test-watch SERVICE=auth-service

`make test-coverage`

Runs tests with coverage for all services.

make test coverage

`make test-coverage-service`

Runs tests with coverage for a specific service.

make test-coverage-service SERVICE=tenant-service

4. Docker Commands

`make docker-build`

Builds all Docker images with BuildKit optimization.

make docker-build

`make docker-build-service`

Builds Docker image for a specific service.

make docker-build-service SERVICE=auth-service

`make docker-up`

Starts all services with docker-compose (uses existing images).

make docker-up

`make docker-up-build`

Builds and starts all services (recommended for first run or after code changes).

make docker-up-build

`make docker-down`

Stops all running services.

make docker-down

`make docker-restart`

Restarts all services.

make docker-restart

`make docker-logs`

Shows logs for all services (follows in real-time).

make docker-logs

`make docker-logs-service`

Shows logs for a specific service.

make docker-logs-service SERVICE=api-gateway

`make docker-ps`

Shows status of all running containers.

make docker-ps

`make docker-clean`

⚠️ Dangerous - Removes all containers, images, and volumes.

make docker-clean

5. Database Commands

`make migrate`

Runs all Prisma migrations (central + tenant databases).

make migrate

`make migrate-central`

Runs migrations for the central database only.

make migrate-central

`make migrate-tenant`

Runs migrations for the tenant database only.

make migrate-tenant

`make migrate-create`

Creates a new migration.

# For central database
make migrate-create NAME=add_user_table SCHEMA=central

# For tenant database
make migrate-create NAME=add_tenant_settings SCHEMA=tenant

`make migrate-reset`

⚠️ Dangerous - Resets all databases (deletes all data).

make migrate-reset

`make db-seed`

Seeds the database with test data (if seed file exists).

make db-seed

`make prisma-generate`

Generates Prisma clients for both databases.

make prisma-generate

`make prisma-studio`

Opens Prisma Studio for database inspection.

make prisma-studio

6. Utility Commands

`make clean`

Cleans build artifacts and Nx cache.

make clean

`make clean-all`

⚠️ Thorough - Cleans everything including node_modules.

make clean-all

`make health-check`

Checks health of all running services via API Gateway.

make health-check

Common Workflows

First Time Setup

# 1. Install dependencies
make install

# 2. Start infrastructure (databases, redis, minio)
make docker-up

# 3. Run migrations
make migrate

# 4. Build and start all services
make docker-up-build

# 5. Check health
make health-check

Development Workflow

# 1. Make code changes

# 2. Run tests
make test-service SERVICE=auth-service

# 3. Rebuild and restart specific service
make docker-build-service SERVICE=auth-service
docker-compose up -d auth-service

# 4. Check logs
make docker-logs-service SERVICE=auth-service

Testing Workflow

# Run tests locally (faster)
make test-service SERVICE=auth-service

# Run tests in watch mode during development
make test-watch SERVICE=auth-service

# Check coverage before committing
make test-coverage-service SERVICE=auth-service

Database Changes

# 1. Create migration
make migrate-create NAME=add_new_field SCHEMA=central

# 2. Apply migration locally
make migrate-central

# 3. Test in Docker
make docker-down
make docker-up-build

Deployment Preparation

# 1. Lint and format code
make lint
make format

# 2. Run all tests
make test

# 3. Build all services
make build

# 4. Test Docker build
make docker-build

# Note: Terraform deployments are handled by CI/CD pipeline

Service Names

Available services for use with SERVICE= parameter:

api-gateway - Main API Gateway (port 3000)
auth-service - Authentication service (port 3001)
tenant-service - Tenant management (port 3002)
admin-service - Admin operations (port 3003)
file-service - File management (port 3004)
kira-service - Kira AI agent (port 3010)
vera-service - Vera AI agent (port 3011)
cleverscreen-service - CleverScreen AI agent (port 3012)

Environment Variables

Most commands respect standard environment variables:

NODE_ENV - Environment mode (development, production)
DATABASE_URL - PostgreSQL connection string
REDIS_HOST - Redis host
REDIS_PORT - Redis port

See .env.example for all available environment variables.

Troubleshooting

Services won't start

# Check Docker status
make docker-ps

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

# Clean and rebuild
make docker-clean
make docker-up-build

Database connection issues

# Check PostgreSQL container
docker logs helix-postgres

# Reset and re-run migrations
make migrate-reset
make migrate

Build fails

# Clean Nx cache
make clean

# Reinstall dependencies
make clean-all
make install

Tests fail

# Run with verbose output
npx nx test auth-service --verbose

# Check for missing dependencies
make install-service SERVICE=auth-service

Tips

Use tab completion - Most shells support tab completion for Makefile targets
Chain commands - You can run multiple commands: make clean && make build && make test
Override defaults - All parameters can be overridden: make serve SERVICE=auth-service PORT=4000
Check help - Always run make help to see latest commands
Use watch mode - During development, use make test-watch for instant feedback

Adding New Commands

To add new commands to the Makefile:

Add command under appropriate section
Add .PHONY declaration at top
Add description to help target
Use color codes for output (GREEN, YELLOW, RED, NC)
Test thoroughly before committing

Example:

.PHONY: my-command

my-command:
	@echo "$(GREEN)Running my command...$(NC)"
	# Your command here
	@echo "$(GREEN)✓ Command complete$(NC)"

Quick Start​

Command Categories​

1. Setup & Installation​

make install​

make install-service​

2. Local Development​

make build​

make build-service​

make serve​

make lint​

make lint-service​

make format​

3. Testing​

make test​

make test-service​

make test-watch​

make test-coverage​

make test-coverage-service​

4. Docker Commands​

make docker-build​

make docker-build-service​

make docker-up​

make docker-up-build​

make docker-down​

make docker-restart​

make docker-logs​

make docker-logs-service​

make docker-ps​

make docker-clean​

5. Database Commands​

make migrate​

make migrate-central​

make migrate-tenant​

make migrate-create​

make migrate-reset​

make db-seed​

make prisma-generate​

make prisma-studio​

6. Utility Commands​

make clean​

make clean-all​

make health-check​

Common Workflows​

First Time Setup​

Development Workflow​

Testing Workflow​

Database Changes​

Deployment Preparation​

Service Names​

Environment Variables​

Troubleshooting​

Services won't start​

Database connection issues​

Build fails​

Tests fail​

Tips​

Adding New Commands​