/dev

Start Dev Environment

Standard flow to start the AIHelms local development environment.

Prerequisites

1. Docker is running 2. `.env` file exists (copy from `.env.example` if not) 3. Python environment activated (conda activate aihelms) 4. Node.js and npm available

Startup Flow

Step 1: First Time Setup

./dev/setup

Or manually:

cp .env.example .env
cd apps && pip install -e ".[dev]"
cd ui && npm install

Step 2: Start Middleware

./dev/start-docker-compose

Verify:

docker compose -f docker-compose.middleware.yaml -p aihelms ps

Step 3: Backend

./dev/start-api

Verify: `curl http://localhost:8000/api/health` returns `{"status":"ok"}`

Note: `start-api` simultaneously starts uvicorn (hot reload) and Celery worker.

Step 4: Frontend

./dev/start-web

Starts both admin (port 4001) and web (port 4002) dev servers.

Unified access via Nginx: `http://<NGINX_SERVER_NAME>:<WEB_PORT>/admin` and `http://<NGINX_SERVER_NAME>:<WEB_PORT>/`

Service Ports

| Service | Port | Description | |---------|------|-------------| | FastAPI | 8000 | Backend API | | Vue Admin | 4001 | Admin dev server | | Vue Web | 4002 | User app dev server | | Nginx | WEB_PORT (default 80) | Unified gateway (dev + prod) | | PostgreSQL | DB_PORT (default 5432) | Database | | Redis | REDIS_PORT (default 6379) | Cache | | LiteLLM | LITELLM_PORT (default 4000) | Model proxy |

Troubleshooting

Database connection failed

docker compose -f docker-compose.middleware.yaml -p aihelms ps db
docker compose -f docker-compose.middleware.yaml -p aihelms logs db

# Rebuild database (will clear data)
docker compose -f docker-compose.middleware.yaml -p aihelms down -v
docker compose -f docker-compose.middleware.yaml -p aihelms up -d

LiteLLM startup failed

docker compose -f docker-compose.middleware.yaml -p aihelms logs litellm

# Common cause: LITELLM_MASTER_KEY or LITELLM_SALT_KEY not set
grep LITELLM .env

Frontend dependency install failed

# Clear cache and reinstall
rm -rf node_modules packages/*/node_modules
npm install

Port already in use

lsof -i :8000
lsof -i :4001
lsof -i :4002