Getting Started

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/ales27pm/monGARS/blob/HEAD/README.md) - [scripts/docker_menu.py](https://github.com/ales27pm/monGARS/blob/HEAD/scripts/docker_menu.py) - [configs/agents/agents_config.json](https://github.com/ales27pm/monGARS/blob/HEAD/configs/agents/agents_config.json) - [AGENTS.md](https://github.com/ales27pm/monGARS/blob/HEAD/AGENTS.md) - [monGARS_structure.txt](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS_structure.txt) - [ROADMAP.md](https://github.com/ales27pm/monGARS/blob/HEAD/ROADMAP.md) - [tests/AGENTS.md](https://github.com/ales27pm/monGARS/blob/HEAD/tests/AGENTS.md) - [monGARS/api/AGENTS.md](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/api/AGENTS.md) - [sdks/python/README.md](https://github.com/ales27pm/monGARS/blob/HEAD/sdks/python/README.md) - [sdks/typescript/README.md](https://github.com/ales27pm/monGARS/blob/HEAD/sdks/typescript/README.md)

This guide provides instructions for setting up the monGARS (Modular Neural Guardian for Autonomous Research & Support) development environment. monGARS is a privacy-first AI assistant designed for resilient deployment across various platforms. This document covers prerequisites, local development, and the recommended Docker-based deployment using an interactive orchestrator.

The system is composed of a FastAPI service for the core API, a Django web application for the operator console, and various optional modules for machine learning and research. Following this guide will enable you to run the full stack, interact with the API and UI, and begin development.

Sources: README.md:5-9, README.md:29-41

Prerequisites

Before you begin, ensure your development environment meets the following requirements:

• Python: Version 3.11+
• Node.js: Version 18+ (for frontend assets)
• Docker & Docker Compose: For containerized workflows. The interactive menu script is compatible with both the docker compose plugin and the standalone docker-compose binary.
• NVIDIA Drivers: (Optional) Required for GPU workloads, compatible with CUDA 12.1 for the default PyTorch image.

Sources: AGENTS.md:68, configs/agents/agents_config.json:33, README.md:120-123, scripts/docker_menu.py:302-312

Local Development Setup

This approach is suitable for quick development and testing of individual components.

The following diagram illustrates the local setup workflow.

Step-by-Step Instructions

1. Create a virtual environment and activate it:

   python -m venv .venv
   source .venv/bin/activate
   

   Sources: README.md:126-127

2. Install Python dependencies:

   pip install -r requirements.txt
   

   Sources: README.md:128

3. Configure the environment: Copy the example environment file and update secrets and URLs as needed.

   cp .env.example .env
   

   Sources: README.md:129

4. Initialize the database: This script applies Alembic migrations and prepares the persistence tables.

   python init_db.py
   

   Sources: README.md:130

5. Run the FastAPI server:

   uvicorn monGARS.api.web_api:app --host 0.0.0.0 --port 8000 --reload
   

   Sources: README.md:131

6. (Optional) Run the Django Operator Console:

   cd webapp
   export DJANGO_SECRET_KEY="change-me"
   export FASTAPI_URL="http://localhost:8000"
   python manage.py migrate
   python manage.py runserver 0.0.0.0:8001
   

   You can then access the UI at http://127.0.0.1:8001/chat/login/.
   Sources: README.md:195-201

Docker Compose Deployment (Recommended)

The recommended method for running the complete monGARS stack is using the interactive Docker Compose orchestrator. This script simplifies environment setup, service management, and diagnostics.

Sources: README.md:133-135, scripts/docker_menu.py

Interactive Orchestrator (docker_menu.py)

The docker_menu.py script provides a terminal-based user interface for managing the Docker stack.

python scripts/docker_menu.py

This command launches a menu with the following capabilities:

• Automated Setup: On first run, it creates .env from .env.example, rotates weak default secrets, and scans for available host ports to prevent collisions.
• Service Management: Deploy, start, stop, restart, and destroy the stack.
• Observability: Tail logs from one or more services and view service status.
• Profile Selection: Interactively enable optional profiles like inference (Ollama) or ray (Ray orchestration) before startup.
• Diagnostics & Healing: Run checks for the Docker daemon, .env file completeness, port availability, and Compose configuration. It can auto-remediate common issues and provides an "auto-heal" routine to restart unhealthy services.
• Environment Summary: Display the current environment variables with sensitive values masked.

The following diagram shows the sequence of deploying the stack using the interactive menu.

Service Architecture

The docker-compose.yml file defines the services that constitute the monGARS stack. The interactive menu script can dynamically include docker-compose.searxng.yml if enabled in the configuration.

Component	Location	Responsibilities
FastAPI service	monGARS/api	Authentication, REST/WebSocket endpoints, dependency wiring
Cognition core	monGARS/core	Memory, reasoning, LLM integration, adaptive response generation
Evolution modules	modules/	Adapter training, diagnostics, research tooling
Django UI	webapp/	Operator-facing chat console and auth proxy
Persistence	init_db.py, monGARS/core/persistence.py	SQLModel schemas, Hippocampus caching, Redis/disk tiers
Tooling	scripts/, docker-compose.yml	Automation, orchestration, deployment manifests

Sources: README.md:110-117

The diagram below shows the primary services and their relationships within the Docker environment.

This diagram illustrates the dependencies between the main application components and the backing services managed by Docker Compose.
Sources: README.md:33-41, README.md:110-117, scripts/docker_menu.py:210-223

Configuration

Configuration is managed primarily through environment variables defined in a .env file at the project root. The docker_menu.py script automates the creation and maintenance of this file.

Sources: README.md:129, scripts/docker_menu.py:89-92

Key Environment Variables

The following table lists important configuration variables. The deployment script automatically manages port assignments and rotates weak secrets.

Setting	Description	Default / Managed
SECRET_KEY	Required for JWT signing and Fernet encryption.	Rotated automatically.
API_PORT / WEBAPP_PORT	Host ports for FastAPI and Django UI.	8000 / 8001 (auto-reassigned on conflict).
POSTGRES_PORT, REDIS_PORT, etc.	Host ports for backing services.	Managed by docker_menu.py.
DB_PASSWORD	Password for the mongars Postgres user.	Rotated automatically if changeme.
USE_RAY_SERVE / RAY_SERVE_URL	Toggles distributed inference via Ray Serve.	false / http://rayserve:8000/generate
DJANGO_SECRET_KEY	Secret key for the Django application.	Rotated automatically.
FASTAPI_URL	URL of the FastAPI backend, used by the Django UI.	http://localhost:8000
OLLAMA_HOST	URL for the Ollama runtime.	http://ollama:11434
LLM_MODELS_PROFILE	Active model profile from configs/llm_models.json.	Varies
RAG_ENABLED	Toggles repository-aware RAG enrichment.	false
WS_ALLOWED_ORIGINS	Comma-separated list of allowed WebSocket origins.	Auto-synced with API_PORT and WEBAPP_PORT.
TRAINING_PIPELINE_ENABLED	Controls the background evolution training workflow.	false

Sources: README.md:203-255, scripts/docker_menu.py:18-26, scripts/docker_menu.py:270-290

Operational Workflows

Once the environment is running, you can use the following commands for common development tasks. These are enforced by the project's contribution guardrails.

• Testing: Run the entire test suite. The suite contains over 600 tests and completes in approximately 110 seconds.

  pytest
  

  For frontend changes, run the corresponding tests:

  npm run test
  

  Sources: AGENTS.md:70, tests/AGENTS.md:79-83

• Static Analysis & Formatting: Format code using black and isort before committing.

  black . && isort .
  

  Sources: AGENTS.md:69, configs/agents/agents_config.json:34

• Model Provisioning: Ensure the LLM models required by the active profile are downloaded and available.

  python -m scripts.provision_models --json
  

  Sources: README.md:267-269, README.md:286-287

Summary

This guide has covered the essential steps to get the monGARS project running, from a minimal local setup to a full-featured, robust deployment using the provided Docker orchestration script. The interactive docker_menu.py is the recommended entry point as it handles complex configuration, secret management, and port allocation automatically. After setting up the environment, developers should familiarize themselves with the operational workflows for testing and code formatting to ensure contributions align with project standards.