Guides

Comprehensive how-to guides for working with Jan Server. For incident response and on-call steps, see ../runbooks/README.md.

Available Guides

Development

Development Guide - Complete development workflow, setup, and best practices
Development Guide - Full Docker, dev-full (hybrid), and native execution modes
Testing Guide - Unit tests, integration tests, and testing best practices

Operations (how-to)

Monitoring - Observability, metrics, traces, and dashboards
Deployment - Kubernetes, Docker Compose, and hybrid deployment strategies
Troubleshooting - Common issues and solutions (links out to runbooks where applicable)

Special Topics

MCP Testing - Testing MCP (Model Context Protocol) integration

Quick Links

For Developers

Task	Guide
Setup local environment	Development Guide
Run services natively	Development Guide - Dev-Full Mode
Write and run tests	Testing Guide
Debug issues	Troubleshooting

For DevOps

Task	Guide
Deploy to production	Deployment Guide
Setup monitoring	Monitoring
Troubleshoot issues	Troubleshooting (see runbooks for on-call steps)

For QA

Task	Guide
Run integration tests	Testing Guide
Test MCP tools	MCP Testing

Common Tasks

Development Workflow

# 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/... # Unit tests from source

Use Development Guide for the complete workflow including full Docker, dev-full (hybrid), and native execution modes.

Testing Workflow

# Integration tests (runs all Postman collections)
make test-all

# Specific test suites
make test-auth
make test-conversations
make test-mcp

# Unit tests from source
go test ./...

See Testing Guide for details.

Monitoring Setup

# 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

See Monitoring Guide for details.

Getting Help

Each guide includes:

Step-by-step instructions
Code examples
Common pitfalls
Troubleshooting tips
Related resources

Need More Help?

Back to: Documentation Home | Next: Choose a guide above

Guides

On this page