### Clone and Start Jan Server (Bash)

Source: https://github.com/janhq/server/blob/main/README.md

This snippet demonstrates how to clone the Jan Server repository, navigate into the directory, and initiate an interactive setup process using the 'make quickstart' command. This process guides the user through LLM provider selection, search provider configuration, and API enablement.

```bash
# 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
```

--------------------------------

### Run Jan Server Quickstart Wizard

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/quickstart.mdx

Executes the 'quickstart' Make target, which launches an interactive wizard to configure Jan Server. The wizard prompts for LLM provider, MCP search provider, and Media API preferences, then automatically generates configuration files and starts the Docker Compose stack.

```bash
make quickstart
```

--------------------------------

### Quick Start Media API Setup

Source: https://github.com/janhq/server/blob/main/services/media-api/README.md

This section provides a quick start guide for running the media API. It includes commands to enable public S3 URLs if needed, navigate to the service directory, build and run the API, and perform a health check.

```bash
## If you need remote LLMs to fetch images directly, enable public S3 URLs:
# export MEDIA_S3_URL_ENABLED=true
# export MEDIA_S3_PUBLIC_ENDPOINT=https://s3.menlo.ai/platform-dev

cd services/media-api
make run
curl -H "Authorization: Bearer <token>" \
  http://localhost:8285/healthz
```

--------------------------------

### Quick Start: Jan Server Setup and Run (Bash)

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/development.mdx

This snippet provides the essential bash commands to clone the Jan Server repository, set up the environment, start all services using Docker Compose, and verify their health. It also includes commands for stopping and cleaning up containers.

```bash
# 1. Clone and enter the repo
git clone https://github.com/janhq/jan-server.git
cd jan-server

# 2. Create .env, docker/.env, and Docker networks
make setup

# 3. Start the full stack (infra + APIs + MCP + optional vLLM)
make up-full

# 4. Verify everything is healthy
make health-check

# 5. Tail logs or iterate
make logs          # all containers
docker compose ps  # status

# Stop containers: make down
# Remove volumes: make down-clean
# Restart a single service: make restart-api, make restart-kong, make restart-keycloak
```

--------------------------------

### Start and Verify Multi-vLLM Docker Instances

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/deployment.mdx

Commands to create a Docker network, start the vLLM instances defined in the docker-compose file, and verify their health status. This is the initial step after defining the multi-instance setup.

```bash
# Create shared network
docker network create jan-network

# Start multi-vLLM stack
docker compose -f docker-compose.vllm-multi.yml up -d

# Verify instances are healthy
curl http://localhost:8101/health
curl http://localhost:8102/health
curl http://localhost:8103/health

```

--------------------------------

### Update Project Configuration with Wizard

Source: https://github.com/janhq/server/blob/main/docs/quickstart.md

This command reruns the `quickstart` wizard, which allows for updating the `.env` configuration file. The wizard prompts the user and can safely reuse existing values while applying new choices, avoiding manual edits to the configuration.

```bash
make quickstart  # rerun the wizard and choose Y to overwrite .env
```

--------------------------------

### Manual Jan Server Configuration

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/quickstart.mdx

Provides steps for manually configuring Jan Server when the setup wizard cannot be run. This involves copying template configuration files, editing them with desired settings, and then running 'make setup' to validate and prepare the environment.

```bash
# Copy templates
cp .env.template .env
cp config/secrets.env.example config/secrets.env

# Edit with your values
nano .env
nano config/secrets.env

# Populate defaults and validate
make setup
```

--------------------------------

### Development Workflow - Bash

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/index.mdx

Guides for setting up the development environment, starting services in Docker, switching to native mode, and running automated tests. It covers common commands for local development.

```bash
# 1. Setup development environment (.env + infra/docker/.env)
make setup

# 2. Start everything in Docker
make up-full

# 3. Switch a service to native mode (optional)
docker compose stop llm-api
./jan-cli.sh dev run llm-api   # macOS/Linux
.\jan-cli.ps1 dev run llm-api  # Windows

# 4. Run automated tests
make test-all                  # jan-cli api-test integration suites
go test ./services/llm-api/...
```

--------------------------------

### Local Development Infrastructure Setup

Source: https://github.com/janhq/server/blob/main/docs/guides/connectors.md

Commands to set up and run the necessary infrastructure and services for local development of the JanHQ server. This includes starting the database and other backend services.

```bash
# Start infrastructure
make up-infra
```

--------------------------------

### Checking Go Installation in Bash

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/testing.mdx

These commands verify if the Go programming language is installed and accessible in the system's PATH. `which go` shows the path to the Go executable, and `go version` displays the installed version. Instructions for installation on different platforms are also provided.

```bash
# Check Go installation
which go
go version

# If not installed:
# Linux: sudo apt install golang-go
# macOS: brew install go
# Windows: Download from https://go.dev/dl/
```

--------------------------------

### Troubleshooting - Services Won't Start

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/quickstart.mdx

A sequence of commands to troubleshoot issues where Jan Server services fail to start. Includes checking Docker, status, logs, and performing a full reset.

```bash
# Check Docker
docker --version
docker compose version

# Check status
make health-check
docker compose ps

# View errors
make logs

# Full reset
make down
make down-clean
make setup
make up-full
```

--------------------------------

### Start Full Docker Stack

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/conventions/conventions.mdx

Starts the complete Docker environment, including infrastructure, APIs, and MCP. This command is used for full development and testing setups.

```bash
make up-full
```

--------------------------------

### Starting Docker Desktop or Colima on macOS

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/testing.mdx

These commands are used to start Docker services on macOS. `open -a Docker` launches Docker Desktop, while `colima start` starts the Colima container runtime, which is often used as an alternative to Docker Desktop.

```bash
# macOS: Start Docker Desktop or Colima
open -a Docker # Docker Desktop
colima start # Colima
```

--------------------------------

### Verify Minikube Installation

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Verifies the Minikube cluster installation by checking the cluster information, node status, and overall Minikube status.

```powershell
kubectl cluster-info
kubectl get nodes
minikube status
```

--------------------------------

### Start Minikube Cluster

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Starts a Minikube Kubernetes cluster with specified resources. It's recommended to allocate sufficient CPUs and memory for development purposes.

```powershell
# Start with sufficient resources
minikube start --cpus=4 --memory=8192 --driver=docker
```

--------------------------------

### Install Minikube using Chocolatey

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Installs Minikube, a tool for running Kubernetes locally, using the Chocolatey package manager. This is a prerequisite for local development environments on Windows.

```powershell
# Using Chocolatey
choco install minikube

# Or download from: https://minikube.sigs.k8s.io/docs/start/
```

--------------------------------

### Setup Project Environment

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/conventions/conventions.mdx

Copies environment template files to create local development environment files. This includes setting up .env and docker/.env files.

```bash
make setup
```

--------------------------------

### Install Jan Server using Helm

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Installs the Jan Server application using a Helm chart. It specifies the release name, namespace, and ensures the namespace is created if it doesn't exist.

```powershell
cd d:\Working\Menlo\jan-server\k8s

# Install with default values
helm install jan-server ./jan-server `
  --namespace jan-server `
  --create-namespace

```

--------------------------------

### Go Example: Loading Configuration with Environment

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/configuration/precedence.mdx

Shows how to initialize and load configuration using the `config.NewConfigLoader`. This example specifies the environment ('development') and the default YAML file, demonstrating the loading order which includes environment-specific YAML files and environment variables.

```go
// Load development environment
loader:= config.NewConfigLoader("development", "config/defaults.yaml")
cfg, err:= loader.Load(context.Background())

// Loads in order:
// 1. Struct defaults (100)
// 2. config/defaults.yaml (200)
// 3. config/environments/development.yaml (300) <- Environment-specific
// 4. Environment variables (500)
```

--------------------------------

### Verify Docker Desktop Kubernetes Installation

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Verifies the Kubernetes installation within Docker Desktop by checking the cluster info and node status. Assumes Kubernetes has been enabled in Docker Desktop settings.

```powershell
kubectl cluster-info
kubectl get nodes
```

--------------------------------

### Setup and Environment Management

Source: https://github.com/janhq/server/blob/main/docs/conventions/conventions.md

Commands for setting up the development environment, including copying environment template files and starting Docker containers. `make setup` prepares the `.env` files, while `make up-full` and `make dev-full` manage Docker services.

```bash
make setup
make up-full
make dev-full
```

--------------------------------

### Install and Configure External Secrets Operator

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/deployment.mdx

This example demonstrates the installation of the external-secrets operator using Helm and the creation of a SecretStore resource for AWS Secrets Manager. This is part of the security considerations for managing secrets externally.

```bash
# Install external-secrets operator
helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  --namespace external-secrets-system \
  --create-namespace

# Create SecretStore for AWS Secrets Manager
kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: aws-secretsmanager
  namespace: jan-server
spec:
  provider:
    aws:
      service: SecretsManager
      region: us-west-2
EOF
```

--------------------------------

### Structured Logging Example with Zerolog in Go

Source: https://github.com/janhq/server/blob/main/CLAUDE.md

Provides examples of using the `zerolog` library for structured logging in Go services. It demonstrates logging informational messages with context like `user_id` and `action`, and error messages including the `request_id` from middleware context. It also lists recommended log levels.

```go
// Use structured logging with zerolog
log.Info().
    Str("user_id", userID).
    Str("action", "create_conversation").
    Msg("Conversation created")

// Always include request_id from middleware context
log.Error().
    Err(err).
    Str("request_id", requestID).
    Msg("Failed to process request")

// Log levels:
// - Debug - Development noise
// - Info - State changes, business events
// - Warn - Recoverable issues
// - Error - Failures requiring attention
```

--------------------------------

### Troubleshoot Pods Not Starting

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/deployment.mdx

This snippet provides kubectl commands to diagnose issues when pods are not starting. It includes commands to check pod status, view pod logs, and describe pods to get detailed event information.

```bash
# Check pod status
kubectl get pods -n jan-server

# View pod logs
kubectl logs -n jan-server <pod-name>

# Describe pod for events
kubectl describe pod -n jan-server <pod-name>
```

--------------------------------

### Install Colima (macOS)

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/testing.mdx

Install Colima, a lightweight container runtime for macOS, using Homebrew. This snippet also includes commands to start Colima with specific resource allocations suitable for local development or CI/CD environments.

```bash
# Install via Homebrew
brew install docker colima

# Start with appropriate resources
colima start --cpu 4 --memory 8 --disk 100

# For CI/CD (conservative settings)
colima start \
 --cpu 2 \
 --memory 4 \
 --disk 20 \
 --vm-type=vz \
 --mount-type=virtiofs
```

--------------------------------

### Initialize and Start Dev-Full Mode

Source: https://github.com/janhq/server/blob/main/docs/guides/development.md

Commands to set up the development environment and start the 'Dev-Full Mode'. This mode is recommended for hybrid debugging, running infrastructure in Docker while allowing native replacement of specific services.

```bash
make setup         # once per machine
make dev-full      # start infra + APIs + MCP with host routing
```

--------------------------------

### Local Development Setup for MCP Tools

Source: https://github.com/janhq/server/blob/main/services/mcp-tools/README.md

Instructions to set up and run the MCP Tools service locally. This involves navigating to the service directory, installing Go module dependencies, and running the service using `go run`.

```bash
cd services/mcp-tools

# Install dependencies
go mod tidy

# Run the service
go run .
```

--------------------------------

### Admin API Examples

Source: https://github.com/janhq/server/blob/main/integrations/keycloak/README.md

Demonstrates common administrative tasks using the Keycloak Admin API, such as retrieving tokens, listing users, and managing group memberships.

```APIDOC
## Admin API Examples

### Description
Examples for interacting with the Keycloak Admin API to perform administrative tasks like user and group management.

### Method
POST, GET, PUT

### Endpoint
- `/realms/{realm}/protocol/openid-connect/token` (for admin token)
- `/admin/realms/{realm}/users`
- `/admin/realms/{realm}/users/{user-id}/groups`
- `/admin/realms/{realm}/users/{user-id}/groups/{group-id}`

### Parameters
#### Path Parameters
- **realm** (string) - Required - The realm name (e.g., `jan`, `master`).
- **user-id** (string) - Required - The ID of the user.
- **group-id** (string) - Required - The ID of the group.

#### Query Parameters
None

#### Request Body
None for GET requests. PUT request to add user to group may have a body, but is often empty.

### Request Example
```bash
# Get admin token
ADMIN_TOKEN=$(curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin" | jq -r .access_token)

# List users
curl -X GET http://localhost:8080/admin/realms/jan/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Get user groups
curl -X GET http://localhost:8080/admin/realms/jan/users/{user-id}/groups \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Add user to group
curl -X PUT http://localhost:8080/admin/realms/jan/users/{user-id}/groups/{group-id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Response
#### Success Response (200 OK)
Responses vary based on the endpoint. Typically JSON arrays of users, groups, or simple success messages.

#### Response Example
```json
// Example for listing users:
[
  {
    "id": "...",
    "username": "testuser",
    "firstName": "Test",
    "lastName": "User",
    "email": "test@example.com"
  }
]
```
```

--------------------------------

### Common Development Command - View Logs

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/quickstart.mdx

Provides commands to view logs for different services or the entire Jan Server setup. Useful for debugging and understanding service behavior.

```bash
# All services
make logs

# API profile (LLM, Response, Media)
make logs-api

# MCP Tools profile
make logs-mcp
```

--------------------------------

### Initialize Observability and HTTP Server (Go)

Source: https://github.com/janhq/server/blob/main/packages/go-common/observability/README.md

Demonstrates the quick start for initializing the observability library and setting up an HTTP server with automatic instrumentation middleware. It loads configuration, initializes the OpenTelemetry provider, and applies HTTP middleware for tracing and metrics.

```go
package main

import (
    "context"
    "log"
    "net/http"

    "github.com/janhq/jan-server/pkg/config"
    "github.com/janhq/jan-server/pkg/observability"
    "github.com/janhq/jan-server/pkg/observability/middleware"
)

func main() {
    ctx := context.Background()

    // Load config
    cfg := config.Load()

    // Initialize observability
    obsCfg := observability.DefaultConfig("my-service")
    obsCfg.Environment = cfg.Environment
    obsCfg.TracingEnabled = cfg.Monitoring.OTEL.TracingEnabled
    obsCfg.PIILevel = cfg.Monitoring.OTEL.PIILevel

    provider, err := observability.Init(ctx, obsCfg)
    if err != nil {
        log.Fatalf("Failed to initialize observability: %v", err)
    }
    defer provider.Shutdown(ctx)

    // Setup HTTP server with middleware
    mux := http.NewServeMux()
    mux.HandleFunc("/health", handleHealth)

    handler := middleware.HTTPMiddleware(provider.Tracer, provider.Meter, "my-service")(mux)

    log.Fatal(http.ListenAndServe(":8080", handler))
}

```

--------------------------------

### Jan Server Project Setup and Run Commands (Bash)

Source: https://github.com/janhq/server/blob/main/CLAUDE.md

This snippet provides essential bash commands for setting up, running, and managing the Jan Server project. It includes commands for interactive setup, environment configuration, starting all services, health checks, development mode, code formatting, documentation generation, testing, and cleanup operations.

```bash
make quickstart              # Interactive setup wizard
make setup                   # Generate .env from template
make up-full                 # Start all services in Docker
make health-check            # Verify all services are healthy

# Development
make dev-full                # Docker stack with host.docker.internal for debugging
go fmt ./...                 # Format Go code
make swagger                 # Regenerate OpenAPI docs
make test-all                # Run all integration tests

# Cleanup
make down                    # Stop containers (keep volumes)
make down-clean              # Stop containers and remove volumes
```

--------------------------------

### Create a New Kong Plugin Directory

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/kong-plugins.mdx

A simple bash command to create the necessary directory structure for a new custom Kong plugin, named 'my-plugin' in this example.

```bash
mkdir -p kong/plugins/my-plugin
```

--------------------------------

### Quick Start: Use MCP Tools (Bash)

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/api-reference/introduction.mdx

An example of using the MCP Tools API to execute a tool, specifically a `google_search`, via a `curl` request with authentication.

```bash
curl -X POST http://localhost:8000/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "google_search",
      "arguments": {"q": "AI news"}
    }
  }'
```

--------------------------------

### Monitoring Setup - Bash

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/index.mdx

Instructions for setting up the monitoring stack, including commands to start the monitoring services and access dashboards for Grafana, Prometheus, and Jaeger. It also shows how to view logs.

```bash
# Start monitoring stack
make monitor-up

# Access dashboards
# - Grafana: http://localhost:3331
# - Prometheus: http://localhost:9090
# - Jaeger: http://localhost:16686

# View logs
make monitor-logs
```

--------------------------------

### Go Import Order Example

Source: https://github.com/janhq/server/blob/main/CLAUDE.md

Demonstrates the standard order for Go imports, categorizing them into standard library packages, third-party packages, and internal project packages. This convention helps maintain code readability and organization.

```go
import (
    // Standard library
    "context"
    "fmt"

    // Third-party packages
    "github.com/gin-gonic/gin"
    "gorm.io/gorm"

    // Internal packages
    "jan-server/services/llm-api/internal/domain/user"
)
```

--------------------------------

### Display All Make Commands

Source: https://github.com/janhq/server/blob/main/docs/quickstart.md

This command lists all available `make` commands for the project, providing a comprehensive overview of the build and management tasks. It's useful for understanding the project's automation capabilities.

```bash
make help-all
```

--------------------------------

### Troubleshooting Jan Server PostgreSQL Startup

Source: https://github.com/janhq/server/blob/main/infra/k8s/SETUP.md

Diagnoses issues with the PostgreSQL pod not starting in the 'jan-server' namespace. Involves checking PostgreSQL logs and persistent volume claims (PVCs).

```bash
# Check PostgreSQL logs
kubectl logs -n jan-server jan-server-postgresql-0

# Check PVC
kubectl get pvc -n jan-server
```

--------------------------------

### Test Plugin Behavior with cURL

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/kong-plugins.mdx

Provides example cURL commands to make test requests to a Kong endpoint and inspect response headers, useful for verifying plugin functionality after deployment or changes.

```bash
# Make test request
curl -v http://localhost:8000/your-endpoint \
 -H "X-Custom-Header: value"

# Check response headers
curl -I http://localhost:8000/your-endpoint
```

--------------------------------

### Local Development Environment Setup (Bash)

Source: https://github.com/janhq/server/blob/main/docs/conventions/workflow.md

Commands to clone the repository, set up the local environment using `make setup`, start the full stack services with `make up-full`, and perform a health check.

```bash
# 1. Clone
git clone https://github.com/janhq/jan-server.git
cd jan-server

# 2. Create .env and docker/.env, verify Docker, etc.
make setup

# 3. Start full stack (PostgreSQL, Keycloak, Kong, APIs, MCP)
make up-full

# 4. Check health
make health-check
```

--------------------------------

### Kong Plugin Handler Logic (Lua)

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/kong-plugins.mdx

Provides a basic Lua template for a Kong plugin's handler file (`handler.lua`), defining the plugin's priority, version, and an example access function that logs a message.

```lua
local MyPluginHandler = {
 PRIORITY = 1000, -- Plugin execution priority
 VERSION = "1.0.0",
}

function MyPluginHandler:access(conf)
 -- Your plugin logic here
 kong.log.info("My plugin executed!")
end

return MyPluginHandler
```

--------------------------------

### Jan-CLI Development Setup Commands

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/jan-cli.mdx

Commands for setting up the development environment and scaffolding new services using jan-cli. This includes initializing the environment, creating new services from templates, and generating API documentation.

```bash
# Setup environment
jan-cli dev setup

# Create new service from template
jan-cli dev scaffold worker-service --template api

# Generate API documentation
jan-cli swagger generate --service llm-api
```

--------------------------------

### Start Multiple vLLM Instances with Docker Compose

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/deployment.mdx

Defines a docker-compose file to launch three vLLM instances, each with dedicated GPU resources and cache volumes. It also specifies a shared network for communication. This setup is ideal for local testing and development.

```yaml
version: '3.8'

services:
  vllm-1:
    image: vllm/vllm-openai:latest
    container_name: vllm-instance-1
    environment:
      - VLLM_API_KEY=${VLLM_API_KEY:-}
      - VLLM_SERVED_MODEL_NAME=meta-llama/Llama-2-7b-hf
    ports:
      - "8101:8000"
    volumes:
      - vllm-cache-1:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - jan-network
    restart: unless-stopped

  vllm-2:
    image: vllm/vllm-openai:latest
    container_name: vllm-instance-2
    environment:
      - VLLM_API_KEY=${VLLM_API_KEY:-}
      - VLLM_SERVED_MODEL_NAME=meta-llama/Llama-2-7b-hf
    ports:
      - "8102:8000"
    volumes:
      - vllm-cache-2:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - jan-network
    restart: unless-stopped

  vllm-3:
    image: vllm/vllm-openai:latest
    container_name: vllm-instance-3
    environment:
      - VLLM_API_KEY=${VLLM_API_KEY:-}
      - VLLM_SERVED_MODEL_NAME=meta-llama/Llama-2-7b-hf
    ports:
      - "8103:8000"
    volumes:
      - vllm-cache-3:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - jan-network
    restart: unless-stopped

volumes:
  vllm-cache-1:
  vllm-cache-2:
  vllm-cache-3:

networks:
  jan-network:
    external: true

```

--------------------------------

### Deploy Jan Server to Minikube using Helm

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/deployment.mdx

This snippet details the steps to deploy Jan Server to a Minikube environment. It includes prerequisites like starting Minikube, building and loading Docker images for various services (llm-api, media-api, mcp-tools), deploying the Helm chart, creating necessary databases, and verifying the deployment by checking pods and port-forwarding to access services.

```bash
# Prerequisites
minikube start --cpus=4 --memory=8192 --driver=docker

# Build and load images
cd services/llm-api && go mod tidy && cd ../..
cd services/media-api && go mod tidy && cd ../..
cd services/mcp-tools && go mod tidy && cd ../..

docker build -t jan/llm-api:latest -f services/llm-api/Dockerfile .
docker build -t jan/media-api:latest -f services/media-api/Dockerfile .
docker build -t jan/mcp-tools:latest -f services/mcp-tools/Dockerfile .

# Load images into minikube
minikube image load jan/llm-api:latest jan/media-api:latest jan/mcp-tools:latest
minikube image load quay.io/keycloak/keycloak:24.0.5
minikube image load bitnami/postgresql:latest bitnami/redis:latest

# Deploy
cd k8s
helm install jan-server ./jan-server \
  --namespace jan-server \
  --create-namespace

# Create databases
kubectl exec -n jan-server jan-server-postgresql-0 -- bash -c "PGPASSWORD=postgres psql -U postgres << 'EOF'\nCREATE USER media WITH PASSWORD 'media';\nCREATE DATABASE media_api OWNER media;\nCREATE USER keycloak WITH PASSWORD 'keycloak';\nCREATE DATABASE keycloak OWNER keycloak;\nEOF"

# Verify deployment
kubectl get pods -n jan-server

# Access services
kubectl port-forward -n jan-server svc/jan-server-llm-api 8080:8080
curl http://localhost:8080/healthz
```

--------------------------------

### Go Service Internal Structure Example

Source: https://github.com/janhq/server/blob/main/CLAUDE.md

Illustrates the standard directory layout for Go services within the 'services/<name>/' path, including directories for command entrypoints, internal domain logic, infrastructure integrations, migrations, and documentation.

```go
services/<service>/
├── cmd/server/                  # Main entrypoint + wire.go
├── internal/
│   ├── domain/                  # Business logic (NO HTTP/DB imports)
│   │   └── <entity>/            # Entity, service, filter, dto
│   ├── infrastructure/          # External integrations
│   │   ├── config/              # Service config loading
│   │   ├── database/            # GORM schemas, repositories
│   │   │   ├── dbschema/        # Schema structs with EtoD/DtoE
│   │   │   └── repository/      # Repository implementations
│   │   └── <provider>/          # External API clients
│   └── interfaces/httpserver/   # HTTP layer
│       ├── routes/              # Gin route handlers
│       ├── middlewares/         # Auth, logging, CORS
│       ├── requests/            # Request DTOs
│       └── responses/           # Response DTOs
├── migrations/                  # SQL migrations (goose)
├── docs/swagger/                # Generated OpenAPI specs
└── Makefile                     # Service-local targets
```

--------------------------------

### Setup and Run Playwright E2E Tests

Source: https://github.com/janhq/server/blob/main/docs/guides/connectors.md

This sequence of commands navigates to the Playwright E2E test directory, installs the necessary npm dependencies, and then executes the Playwright test suite. This is used for end-to-end testing of the application's user interface and workflows.

```bash
cd tests/e2e/playwright
npm install
npx playwright test
```

--------------------------------

### Start Keycloak with Docker Compose

Source: https://github.com/janhq/server/blob/main/integrations/keycloak/README.md

Commands to start the Keycloak service within the Jan Server Docker Compose setup. This command initiates the Keycloak container and automatically imports the realm configuration on its first run.

```bash
# Start full stack including Keycloak
docker-compose up -d keycloak

# Or start everything
docker-compose up -d
```

--------------------------------

### Ensuring Makefile Compatibility on Windows

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/guides/testing.mdx

This section provides guidance on running Makefiles on Windows, emphasizing the need for Git Bash or WSL. It also highlights crucial path and naming conventions for Windows environments, such as using forward slashes and appending `.exe` to binaries.

```text
Make requires Git Bash or WSL on Windows:
- Install Git for Windows: https://git-scm.com/download/win
- Or use WSL: https://docs.microsoft.com/en-us/windows/wsl/install

GitHub Actions Windows runners use Git bash. Ensure:
- Use forward slashes in Makefile paths
- Use `ifeq ($(OS),Windows_NT)` branches for Windows-specific commands
- Binary names include `.exe` extension for Windows
```

--------------------------------

### Start Jan Server Services

Source: https://github.com/janhq/server/blob/main/apps/platform/content/docs/quickstart.mdx

Commands to start the Jan Server Docker Compose stack. 'make up-full' starts the complete stack including CPU inference, while 'make monitor-up' optionally starts the monitoring stack (Grafana, Prometheus, Jaeger).

```bash
# Start full stack (CPU inference)
make up-full

# Optional: start monitoring stack
make monitor-up
```

--------------------------------

### JavaScript SDK Example (OpenAI Compatible)

Source: https://github.com/janhq/server/blob/main/docs/api/README.md

Example of how to use an OpenAI-compatible client library (JavaScript) to interact with the Jan Server API.

```APIDOC
## JavaScript SDK Example (OpenAI SDK)

### Description
This example demonstrates how to use the official OpenAI JavaScript SDK, configured to point to the Jan Server's base URL.

### Code Example
```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "your_guest_token_here", // Replace with your actual token if needed
});

async function main() {
  try {
    const response = await client.chat.completions.create({
      model: "jan-v1-4b",
      messages: [{ role: "user", content: "Hello!" }],
    });
    console.log(response.choices[0].message.content);
  } catch (error) {
    console.error("Error calling Jan Server API:", error);
  }
}

main();
```
```

--------------------------------

### Install Jan Server Helm Chart (Minikube)

Source: https://github.com/janhq/server/blob/main/infra/k8s/README.md

Installs the Jan Server Helm chart in the 'jan-server' namespace for a Minikube development setup. It also builds Helm dependencies before installation.

```bash
cd k8s/jan-server
helm dependency build
cd ..
helm install jan-server ./jan-server \
  --namespace jan-server \
  --create-namespace
```

--------------------------------

### CLI Tool - Quick Install

Source: https://github.com/janhq/server/blob/main/README.md

Instructions for installing the Jan Server CLI tool globally.

```APIDOC
## CLI Tool - Quick Install

### Description
Instructions for installing the Jan Server CLI tool globally.

### Method
N/A (Makefile target and shell commands)

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
# 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
```

### Response
None
```