docs: Add documentation site and API reference

2026-02-13 15:12:14 +01:00
parent d82fe87113
commit e17d34e6d7
7 changed files with 968 additions and 0 deletions
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,104 @@
+# Configuration
+
+All configuration is done through environment variables. Copy `.env.example` to `.env` and set the values before starting the server.
+
+```bash
+cp .env.example .env
+```
+
+---
+
+## Gitea Settings
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `GITEA_URL` | Yes | — | Base URL of your Gitea instance (e.g. `https://gitea.example.com`) |
+| `GITEA_TOKEN` | Yes | — | API token of the Gitea bot user |
+
+The `GITEA_TOKEN` must be a token belonging to a user that has at least read access to all repositories you want the AI to access. The server validates the token on startup by calling the Gitea `/api/v1/user` endpoint.
+
+---
+
+## MCP Server Settings
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `MCP_HOST` | No | `0.0.0.0` | Interface to bind to |
+| `MCP_PORT` | No | `8080` | Port to listen on |
+| `MCP_DOMAIN` | No | — | Public domain name (used for Traefik labels in Docker) |
+| `LOG_LEVEL` | No | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+
+---
+
+## Authentication Settings
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AUTH_ENABLED` | No | `true` | Enable or disable API key authentication |
+| `MCP_API_KEYS` | Yes (if auth enabled) | — | Comma-separated list of valid API keys |
+| `MAX_AUTH_FAILURES` | No | `5` | Number of failed attempts before rate limiting an IP |
+| `AUTH_FAILURE_WINDOW` | No | `300` | Time window in seconds for counting failures |
+
+### API Key Requirements
+
+- Minimum length: 32 characters
+- Recommended: generate with `make generate-key` (produces 64-character hex keys)
+- Multiple keys: separate with commas — useful during key rotation
+
+```env
+# Single key
+MCP_API_KEYS=abc123...
+
+# Multiple keys (grace period during rotation)
+MCP_API_KEYS=newkey123...,oldkey456...
+```
+
+> **Warning:** Setting `AUTH_ENABLED=false` disables all authentication. Only do this in isolated development environments.
+
+---
+
+## File Access Settings
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `MAX_FILE_SIZE_BYTES` | No | `1048576` | Maximum file size the server will return (bytes). Default: 1 MB |
+| `REQUEST_TIMEOUT_SECONDS` | No | `30` | Timeout for upstream Gitea API calls (seconds) |
+
+---
+
+## Audit Logging Settings
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AUDIT_LOG_PATH` | No | `/var/log/aegis-mcp/audit.log` | Absolute path for the JSON audit log file |
+
+The directory is created automatically if it does not exist (requires write permission).
+
+---
+
+## Full Example
+
+```env
+# Gitea
+GITEA_URL=https://gitea.example.com
+GITEA_TOKEN=abcdef1234567890abcdef1234567890
+
+# Server
+MCP_HOST=0.0.0.0
+MCP_PORT=8080
+MCP_DOMAIN=mcp.example.com
+LOG_LEVEL=INFO
+
+# Auth
+AUTH_ENABLED=true
+MCP_API_KEYS=a1b2c3d4e5f6...64chars
+MAX_AUTH_FAILURES=5
+AUTH_FAILURE_WINDOW=300
+
+# Limits
+MAX_FILE_SIZE_BYTES=1048576
+REQUEST_TIMEOUT_SECONDS=30
+
+# Audit
+AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log
+```