# Clone and enter the repo
git clone https://github.com/janhq/server.git
cd server

# Interactive setup (runs jan-cli wizard and docker compose)
make quickstart

make setup   # Generates/updates .env via jan-cli
make up-full # Starts every service defined in docker-compose.yml

jan-server/
|-- apps/                  # Frontend applications
|   |-- web/               # Chat UI (React + Vite, port 3001)
|   |-- platform/          # Admin panel & docs (Next.js, port 3000)
|-- services/              # Go microservices
|   |-- llm-api/
|   |-- response-api/
|   |-- media-api/
|   |-- mcp-tools/
|   |-- realtime-api/
|   |-- template-api/
|-- packages/              # Shared packages
|   |-- interfaces/        # Shared UI components (@janhq/interfaces)
|-- docs/                  # Documentation hub
|-- infra/docker/          # Compose profiles (infra, api, mcp, realtime, inference)
|-- monitoring/            # Grafana, Prometheus, OTEL configs
|-- k8s/                   # Helm chart + setup guide
|-- config/                # Environment templates and helpers
|-- kong/                  # Gateway declarative config
|-- keycloak/              # Realm + theme customisation
|-- scripts/               # Utility scripts (new service template, etc.)
|-- Makefile               # Build, test, deploy targets

# Run frontend apps
cd apps/web && npm install && npm run dev       # http://localhost:3001
cd apps/platform && npm install && npm run dev  # http://localhost:3000

# Or via Docker
make up-web       # Start web app container
make up-platform  # Start platform app container

# Generate new service from template
./scripts/new-service-from-template.ps1 -Name my-new-service

# Template includes:
# - Go service skeleton with Gin HTTP server
# - Configuration management (Viper)
# - Structured logging (Zerolog)
# - OpenTelemetry tracing support
# - PostgreSQL with GORM
# - Dependency injection with Wire
# - Docker and Makefile setup
# - Health check endpoint

# Start services
make up-full              # Full stack (all 4 APIs + infrastructure)
make up-gpu               # With GPU inference (vLLM)
make up-cpu               # CPU-only inference
make up                   # Infrastructure only (DB, Keycloak, Redis)

# Build services
make build-llm-api        # Build LLM API
make build-response-api   # Build Response API
make build-media-api      # Build Media API
make build-mcp            # Build MCP Tools
make build-realtime-api   # Build Realtime API

# Development
make test-all             # Run all test suites
make swag                 # Generate API docs

# Testing
make test-auth            # Authentication tests
make test-conversations   # Conversation tests
make test-response        # Response API tests
make test-media           # Media API tests
make test-mcp             # MCP tools tests
make test-e2e             # Gateway E2E tests

# Monitoring
make monitor-up           # Start monitoring stack
make monitor-logs         # View monitoring logs

# Logs & Status
make logs-llm-api         # View LLM API logs
make logs-response-api    # View Response API logs
make logs-media-api       # View Media API logs
make logs-mcp             # View MCP Tools logs
make logs-realtime-api    # View Realtime API logs
make health-check         # Check all services health

# Database
make db-migrate           # Run migrations
make db-reset             # Reset database
make db-seed              # Seed test data

# Cleanup
make down                 # Stop services
make clean                # Clean artifacts
make clean-all            # Clean everything (including volumes)

# Start all services in Docker with host.docker.internal support
make dev-full

# Stop any service and run it on your host
docker compose stop llm-api
.\scripts\dev-full-run.ps1 llm-api  # Windows
./scripts/dev-full-run.sh llm-api   # Linux/Mac

# Install globally (recommended)
make cli-install

# Add to PATH as instructed, then run from anywhere
jan-cli --version
jan-cli config validate
jan-cli service list

# Linux/macOS/WSL
./jan-cli.sh config validate
./jan-cli.sh service list
./jan-cli.sh dev setup

# Windows PowerShell
.\jan-cli.ps1 config validate
.\jan-cli.ps1 service list
.\jan-cli.ps1 dev setup

jan-cli config validate              # Validate configuration
jan-cli config export --format env   # Export as environment variables
jan-cli config show llm-api          # Show service configuration
jan-cli config k8s-values --env prod # Generate Kubernetes values

jan-cli service list                 # List all services
jan-cli service logs llm-api         # Show service logs
jan-cli service status               # Check service health

jan-cli dev setup                    # Setup development environment
jan-cli dev scaffold my-service      # Create new service from template

# Get guest token (no registration required)
curl -X POST http://localhost:8000/llm/auth/guest-login

# Sample response:
# {
#   "access_token": "eyJhbGc...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "...",
#   "user_id": "guest-..."
# }

# Simple chat completion
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jan-v1-4b",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

# With media (using jan_* ID)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jan-v1-4b",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "jan_01hqr8v9k2x3f4g5h6j7k8m9n0"}}
      ]
    }]
  }'

# Upload media (remote URL)
curl -X POST http://localhost:8285/v1/media \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "remote_url",
      "url": "https://example.com/image.jpg"
    },
    "user_id": "user123"
  }'

# Response:
# {
#   "id": "jan_01hqr8v9k2x3f4g5h6j7k8m9n0",
#   "mime": "image/jpeg",
#   "bytes": 45678,
#   "presigned_url": "https://s3.menlo.ai/platform-dev/..."
# }

# Resolve jan_* ID to presigned URL
curl -X POST http://localhost:8285/v1/media/resolve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["jan_01hqr8v9k2x3f4g5h6j7k8m9n0"]}'

# Google search
curl -X POST http://localhost:8000/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "google_search",
      "arguments": {"q": "latest AI news", "num": 5}
    }
  }'

# List available tools
curl -X GET http://localhost:8091/v1/mcp/tools

# Create response with tool execution
curl -X POST http://localhost:8082/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Search for the latest AI news and summarize the top 3 results"
  }'

# Response includes:
# - Tool execution trace
# - Final generated response
# - Execution metadata (depth, duration, etc.)

make up-full              # All services (including optional ones)
make up-gpu               # With GPU inference
make up-cpu               # CPU-only inference
make monitor-up           # Add monitoring stack

# Optional services (enabled via profiles)
docker compose --profile realtime up -d  # Start Realtime API
docker compose --profile memory up -d    # Start Memory Tools

# Quick setup with defaults
make setup

# Or manually configure
cp config/secrets.env.example config/secrets.env
# Edit config/secrets.env with your API keys:
# - HF_TOKEN (HuggingFace token for model downloads)
# - SERPER_API_KEY (for Google Search tool)
# - POSTGRES_PASSWORD (database password)
# - KEYCLOAK_ADMIN_PASSWORD (Keycloak admin password)

# Available environment configs:
# - config/defaults.env       - Base configuration
# - config/development.env    - Docker development
# - config/testing.env        - Testing configuration
# - config/production.env.example - Production template

# Run all tests (6 jan-cli api-test collections)
make test-all

# Specific test suites
make test-auth            # Authentication flows (guest + user)
make test-conversations   # Conversation management
make test-response        # Response API orchestration
make test-media           # Media API operations
make test-mcp             # MCP tools integration
make test-e2e             # Gateway end-to-end tests

# Test reports
# - CLI output: Detailed results with assertions