Local Development Setup

This guide walks you through setting up the MATIH Platform on your local machine for development. The local environment uses Docker Compose for infrastructure services and supports multiple development profiles depending on which components you need.

Development Profiles

MATIH supports several profiles to balance resource usage with the components you need:

Profile	Components	RAM Usage	Best For
minimal	PostgreSQL, Redis, Kafka	~4 GB	Backend service development
data	Minimal + StarRocks, MinIO	~8 GB	Query engine, data pipeline work
ai	Minimal + AI service dependencies	~6 GB	AI/ML service development
full	All infrastructure services	~12 GB	Integration testing, full-stack development

Step 1: Clone and Explore the Repository

# Clone the repository
git clone https://github.com/your-org/matih-prototype.git
cd matih-prototype
 
# Explore the project structure
ls -la

Key directories:

Directory	Contents
`control-plane/`	Java Spring Boot services (IAM, tenant, config, etc.)
`data-plane/`	Data Plane services (AI, ML, query engine, etc.)
`frontend/`	React/TypeScript workbench applications
`infrastructure/`	Helm charts, Terraform modules, Kubernetes manifests
`scripts/`	Build, deploy, and utility scripts
`local/`	Local development configurations
`commons/`	Shared libraries (Java, Python, TypeScript)

Step 2: Start Infrastructure Services

Use the local/matih CLI to start the infrastructure services:

# Start with minimal profile (PostgreSQL, Redis, Kafka)
./local/matih start --profile minimal
 
# Start with full profile (all services)
./local/matih start --profile full

Alternatively, use Docker Compose directly:

# Start infrastructure services
docker-compose up -d
 
# Check running containers
docker-compose ps
 
# View logs
docker-compose logs -f

Infrastructure Service Ports

Service	Port	URL
PostgreSQL	5432	`postgresql://localhost:5432`
Redis	6379	`redis://localhost:6379`
Kafka	29092	`localhost:29092`
Kafka UI	8090	`http://localhost:8090`
MinIO	9000 / 9001	`http://localhost:9000` (API), `http://localhost:9001` (console)
Dgraph Alpha	8080 / 9080	`http://localhost:8080` (HTTP), `localhost:9080` (gRPC)
Dgraph Ratel	8000	`http://localhost:8000`

Step 3: Build the Platform

Build Everything

# Full build (all services, all tests)
./scripts/build.sh
 
# Build with tests skipped (faster for development)
./scripts/build.sh --skip-tests

Build by Language

# Build only Java services (Control Plane)
./scripts/build.sh --java
 
# Build only Python services (AI, ML, Data Quality)
./scripts/build.sh --python
 
# Run tests only
./scripts/build.sh --test-only --with-deps

Build a Single Service

# Build and deploy a specific service
./scripts/tools/service-build-deploy.sh ai-service
 
# Full rebuild of a specific service
./scripts/tools/full-service-rebuild.sh ai-service

Step 4: Build Base Images

Some services share base Docker images. Build these first:

./scripts/tools/build-base-images.sh

This builds the shared base images that provide common dependencies for Java, Python, and Node.js services.

Step 5: Set Up Databases

Initialize the database schemas for all services:

./scripts/tools/setup-databases.sh

This script creates the required databases and schemas in PostgreSQL:

Database	Purpose
`matih_control_plane`	Control plane services (IAM, tenant, config, etc.)
`matih_ai_service`	AI service data
`matih_ml_service`	ML service and MLflow data
`matih_query_engine`	Query engine metadata
`matih_catalog`	Data catalog metadata
`matih_pipeline`	Pipeline definitions and execution state

Step 6: Run Control Plane Services

Control Plane services are Java Spring Boot applications. Run them using Gradle:

# Run the IAM service
cd control-plane/iam-service
./gradlew bootRun
 
# Run the tenant service (in another terminal)
cd control-plane/tenant-service
./gradlew bootRun
 
# Run the config service
cd control-plane/config-service
./gradlew bootRun

Control Plane Service Ports

Service	Port	Health Check
api-gateway	8080	`http://localhost:8080/actuator/health`
iam-service	8081	`http://localhost:8081/actuator/health`
tenant-service	8082	`http://localhost:8082/actuator/health`
platform-registry	8084	`http://localhost:8084/actuator/health`
notification-service	8085	`http://localhost:8085/actuator/health`
audit-service	8086	`http://localhost:8086/actuator/health`
billing-service	8087	`http://localhost:8087/actuator/health`
observability-api	8088	`http://localhost:8088/actuator/health`
infrastructure-service	8089	`http://localhost:8089/actuator/health`
config-service	8888	`http://localhost:8888/actuator/health`

Step 7: Run Data Plane Services

AI Service (Python)

cd data-plane/ai-service
 
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
 
# Install dependencies
pip install -r requirements.txt
 
# Run the service
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

ML Service (Python)

cd data-plane/ml-service
 
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
 
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Query Engine (Java)

cd data-plane/query-engine
./gradlew bootRun

Step 8: Run Frontend Workbenches

Install Frontend Dependencies

# Install shared dependencies
cd frontend/shared
pnpm install
 
# Install workbench dependencies
cd ../bi-workbench
pnpm install

Start a Workbench

# BI Workbench (port 3000)
cd frontend/bi-workbench
pnpm dev
 
# ML Workbench (port 3001)
cd frontend/ml-workbench
pnpm dev
 
# Data Workbench (port 3002)
cd frontend/data-workbench
pnpm dev
 
# Agentic Workbench (port 3003)
cd frontend/agentic-workbench
pnpm dev
 
# Control Plane UI (port 3004)
cd frontend/control-plane-ui
pnpm dev

Frontend Port Summary

Workbench	Port	URL
BI Workbench	3000	`http://localhost:3000`
ML Workbench	3001	`http://localhost:3001`
Data Workbench	3002	`http://localhost:3002`
Agentic Workbench	3003	`http://localhost:3003`
Control Plane UI	3004	`http://localhost:3004`
Data Plane UI	3005	`http://localhost:3005`

Environment Variables

Create a .env file in the project root for local development (this file is gitignored):

# Database
DATABASE_URL=postgresql://matih:password@localhost:5432/matih_control_plane
 
# Redis
REDIS_URL=redis://localhost:6379
 
# Kafka
KAFKA_BOOTSTRAP_SERVERS=localhost:29092
 
# Authentication
JWT_SECRET=your-local-development-secret-key-minimum-256-bits
 
# AI Service
OPENAI_API_KEY=sk-your-openai-api-key
 
# ML Service
MLFLOW_TRACKING_URI=http://localhost:5000

Running Tests

Java Tests

# All Java tests
./scripts/build.sh --test-only --java
 
# Tests for a specific service
cd control-plane/iam-service
./gradlew test
 
# With test report
./gradlew test jacocoTestReport

Python Tests

# All Python tests
./scripts/build.sh --test-only --python
 
# Tests for a specific service
cd data-plane/ai-service
pytest tests/ -v
 
# With coverage
pytest tests/ --cov=src --cov-report=html

Frontend Tests

cd frontend/bi-workbench
pnpm test
 
# With coverage
pnpm test:coverage

Integration Tests

# Run integration tests (requires infrastructure services running)
cd tests/integration
./run-tests.sh

Local Validation

Validate that services are running correctly:

# Validate local services
./scripts/tools/local-service-validate.sh
 
# Validate schema consistency
./scripts/tools/local-schema-validate.sh
 
# Validate port assignments (no conflicts)
./scripts/tools/validate-ports.sh

Common Development Workflows

Working on the AI Service

# 1. Start infrastructure
./local/matih start --profile ai
 
# 2. Start the AI service in development mode
cd data-plane/ai-service
source .venv/bin/activate
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
 
# 3. Start the Agentic Workbench
cd frontend/agentic-workbench
pnpm dev
 
# 4. Test via the UI at http://localhost:3003

Working on the Control Plane

# 1. Start infrastructure
./local/matih start --profile minimal
 
# 2. Start required services
cd control-plane/iam-service && ./gradlew bootRun &
cd control-plane/tenant-service && ./gradlew bootRun &
 
# 3. Start the Control Plane UI
cd frontend/control-plane-ui
pnpm dev
 
# 4. Access the UI at http://localhost:3004

Working on BI Dashboards

# 1. Start infrastructure with data profile
./local/matih start --profile data
 
# 2. Start the BI service and query engine
cd data-plane/bi-service && ./gradlew bootRun &
cd data-plane/query-engine && ./gradlew bootRun &
 
# 3. Start the BI Workbench
cd frontend/bi-workbench
pnpm dev
 
# 4. Access at http://localhost:3000

Stopping the Environment

# Stop infrastructure services
./local/matih stop
 
# Or with Docker Compose
docker-compose down
 
# Remove volumes (reset all data)
docker-compose down -v

Troubleshooting

Port Conflicts

# Check for port conflicts
./scripts/tools/validate-ports.sh
 
# Find what is using a port
lsof -i :8080

Docker Resource Issues

If services are crashing or failing to start:

Increase Docker Desktop memory allocation (Settings > Resources)
Use a smaller profile (--profile minimal instead of --profile full)
Stop services you are not actively developing

Database Connection Issues

# Verify PostgreSQL is running
docker-compose ps postgres
 
# Check connection
psql -h localhost -p 5432 -U matih -d matih_control_plane -c "SELECT 1"
 
# Reset databases
docker-compose down -v
docker-compose up -d postgres
./scripts/tools/setup-databases.sh

Next Steps

If deploying to the cloud, continue to Cloud Deployment
If your local environment is running, proceed to First-Time Configuration
Ready to explore the platform? Jump to Quickstart Tutorials

Prerequisites Cloud Deployment