Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The monGARS project utilizes a layered configuration system designed for flexibility across local development, containerized deployments, and research experiments. Configuration is primarily managed through environment variables, JSON files for specific domains like LLM models and agent behavior, and a powerful interactive Docker menu for orchestrating the stack. The core principle is to resolve configuration once at startup, with services accessing settings via a central utility, monGARS.config.get_settings().
This guide provides a comprehensive overview of the different configuration layers, key variables, and management scripts. It covers environment setup, service orchestration with Docker Compose, LLM model management, and the unique agent charter system that governs module development.
Environment Variables
The primary method for configuring the monGARS stack is through environment variables defined in a .env file at the project root. The system is bootstrapped using the scripts/docker_menu.py script, which copies .env.example to .env on its first run and automatically rotates weak default secrets.
Sources: scripts/docker_menu.py:126-129, scripts/docker_menu.py:131-154, README.md:162-165
Configuration Loading Flow
The interactive docker_menu.py script orchestrates the environment setup before launching services. This diagram illustrates the startup and configuration process.
This diagram shows the automated setup performed by docker_menu.py, including environment file creation, secret rotation, and dynamic port allocation.
Sources: scripts/docker_menu.py:126-129, scripts/docker_menu.py:131-154, scripts/docker_menu.py:192-211
Key Environment Variables
The following table details the most important environment variables for operating the monGARS stack.
| Setting | Description | Default/Example |
|---|---|---|
SECRET_KEY | Required for JWT signing and Fernet encryption. Rotated automatically from weak defaults. | dev-secret-change-me |
API_PORT / WEBAPP_PORT | Host ports for the FastAPI service and Django operator console. | 8000 / 8001 |
POSTGRES_PORT, REDIS_PORT, etc. | Host bindings for stateful and optional services managed by Docker Compose. | 5432, 6379 |
DB_PASSWORD | Password for the mongars Postgres user. Rotated automatically. | changeme |
USE_RAY_SERVE / RAY_SERVE_URL | Toggles distributed inference and specifies the Ray Serve HTTP endpoint. | http://rayserve:8000/generate |
DJANGO_SECRET_KEY | Secret key for the Django web application. Rotated automatically. | django-insecure-change-me |
FASTAPI_URL | URL of the FastAPI backend, used by the Django webapp. | http://localhost:8000 |
OLLAMA_HOST | URL for the Ollama runtime. | http://ollama:11434 |
LLM_MODELS_CONFIG_PATH | Path to the JSON manifest for LLM model profiles. | configs/llm_models.json |
LLM_MODELS_PROFILE | The active profile name from the LLM models JSON file. | default |
LLM_MODELS_AUTO_DOWNLOAD | If true, missing local models are pulled automatically. | true |
RAG_ENABLED / RAG_SERVICE_URL | Toggles repository-aware RAG enrichment and sets the service URL. | false |
WS_ALLOWED_ORIGINS | Comma-separated list of origins allowed for WebSocket connections. | ["http://localhost:8000", ...] |
TRAINING_PIPELINE_ENABLED | Controls whether the background evolution training workflow runs. | true |
TRAINING_CYCLE_INTERVAL_SECONDS | Interval for the training cycle. | 3600 |
Sources: README.md:218-255, scripts/docker_menu.py:43-50, scripts/docker_menu.py:213-228
Docker Compose & Service Orchestration
The entire monGARS stack is defined in docker-compose.yml and orchestrated using the scripts/docker_menu.py script. This script provides an interactive menu for common operations like deploying, stopping, viewing logs, and destroying the stack.
Sources: README.md:166-216, scripts/docker_menu.py
Service Interaction Diagram
The following diagram shows the main services and their relationships as managed by Docker Compose.
This diagram illustrates the services defined in the Docker Compose setup and how they are configured to interact via environment variables.
Sources: README.md:129-145, README.md:218-255, scripts/docker_menu.py:213-228
Optional Profiles
The docker_menu.py script allows enabling optional services via profiles before startup. This is handled by passing --profile arguments to the docker compose command.
- Inference Profile (
inference): Launches theollamaservice for local LLM execution. - Ray Profile (
ray): Launches theray-headandrayserveservices for distributed task execution and model serving. - SearxNG Integration: The
docker-compose.searxng.ymloverlay is automatically included ifSEARCH_SEARX_ENABLEDis true in the.envfile.
Sources: scripts/docker_menu.py:530-535, scripts/docker_menu.py:418-432
Domain-Specific Configuration
Beyond environment variables, monGARS uses JSON files to manage more complex, domain-specific configurations.
LLM Model Configuration
LLM models are defined in a JSON file specified by the LLM_MODELS_CONFIG_PATH environment variable (defaulting to configs/llm_models.json). This file allows defining multiple profiles, each with different models for various tasks.
The structure of this file typically includes:
- A top-level object with profile names as keys (e.g., "default").
- Each profile contains model definitions for roles like "general" and "coding".
- Each model definition specifies the provider (e.g., "ollama"), model name, and other metadata.
The active profile is selected using the LLM_MODELS_PROFILE environment variable.
Sources: README.md:240-244, README.md:257-264
Agent & Module Charters
A unique aspect of monGARS is its use of AGENTS.md files, which act as "charters" or "contracts" for different parts of the codebase. These Markdown files are not written manually but are generated from a central configuration file: configs/agents/agents_config.json.
The agents_config.json file defines:
- The
pathfor eachAGENTS.mdfile. - The
titleandscopeof the charter. roadmap_focussections that link the module's responsibilities to the globalROADMAP.md.sectionscontaining specific rules, guidelines, and guardrails for developers working in that module.
The scripts/manage_agents.py script reads this JSON file and the roadmap to dynamically generate the content for each AGENTS.md file. This ensures that development guidelines are centralized, version-controlled, and consistently applied across the repository.
// Example snippet from configs/agents/agents_config.json
{
"path": "monGARS/api/AGENTS.md",
"title": "FastAPI Surface Standards",
"scope": "Applies to routers, schemas, WebSocket helpers, and auth utilities under `monGARS/api/`.",
"roadmap_focus": [
{
"phase": "Phase 5 – Web Interface & API Refinement (✅ Completed Q4 2025)",
"label": "API Refinement"
}
],
"sections": [
{
"heading": "Endpoint Design",
"bullets": [
"Expose asynchronous routes returning typed Pydantic responses...",
"Register routers with explicit prefixes/tags..."
]
}
]
}
Sources: configs/agents/agents_config.json:1-300, scripts/manage_agents.py:20-29, scripts/manage_agents.py:155-201
Training Configuration
Training configurations for modules like the MNTPTrainer are stored in the configs/training/ directory. For example, mntp_dolphin_config.json likely contains parameters for fine-tuning a specific model. These configurations are loaded by the training modules, often with paths passed as explicit arguments to maintain testability.
Sources: monGARS_structure.txt:8-11, modules/AGENTS.md:34-37
Summary
Configuration in monGARS is a well-structured, multi-layered system. It combines the simplicity of .env files for environment-specific settings, the power of Docker Compose for service orchestration, and the clarity of JSON files for domain-specific data like LLM models. The automated docker_menu.py script simplifies setup and management, while the unique agents_config.json system provides a novel way to enforce development standards and link code directly to project goals. This comprehensive approach ensures that the system is both robust for production and adaptable for research and development.