docs: user guide, admin guide, dev guide (closes #57) (#151)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
This commit was merged in pull request #151.
This commit is contained in:
311
docs/guides/admin-guide.md
Normal file
311
docs/guides/admin-guide.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Mosaic Stack — Admin Guide
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [User Management](#user-management)
|
||||
2. [System Health Monitoring](#system-health-monitoring)
|
||||
3. [Provider Configuration](#provider-configuration)
|
||||
4. [MCP Server Configuration](#mcp-server-configuration)
|
||||
5. [Environment Variables Reference](#environment-variables-reference)
|
||||
|
||||
---
|
||||
|
||||
## User Management
|
||||
|
||||
Admins access user management at `/admin` in the web dashboard. All admin
|
||||
endpoints require a session with `role = admin`.
|
||||
|
||||
### Creating a User
|
||||
|
||||
**Via the web admin panel:**
|
||||
|
||||
1. Navigate to `/admin`.
|
||||
2. Click **Create User**.
|
||||
3. Enter name, email, password, and role (`admin` or `member`).
|
||||
4. Submit.
|
||||
|
||||
**Via the API:**
|
||||
|
||||
```http
|
||||
POST /api/admin/users
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Jane Doe",
|
||||
"email": "jane@example.com",
|
||||
"password": "securepassword",
|
||||
"role": "member"
|
||||
}
|
||||
```
|
||||
|
||||
Passwords are hashed by BetterAuth before storage. Passwords are never stored in
|
||||
plaintext.
|
||||
|
||||
### Roles
|
||||
|
||||
| Role | Permissions |
|
||||
| -------- | --------------------------------------------------------------------- |
|
||||
| `admin` | Full access: user management, health, all agent tools |
|
||||
| `member` | Standard user access; agent tool set restricted by `AGENT_USER_TOOLS` |
|
||||
|
||||
### Updating a User's Role
|
||||
|
||||
```http
|
||||
PATCH /api/admin/users/:id/role
|
||||
Content-Type: application/json
|
||||
|
||||
{ "role": "admin" }
|
||||
```
|
||||
|
||||
### Banning and Unbanning
|
||||
|
||||
Banned users cannot sign in. Provide an optional reason:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/:id/ban
|
||||
Content-Type: application/json
|
||||
|
||||
{ "reason": "Violated terms of service" }
|
||||
```
|
||||
|
||||
To lift a ban:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/:id/unban
|
||||
```
|
||||
|
||||
### Deleting a User
|
||||
|
||||
```http
|
||||
DELETE /api/admin/users/:id
|
||||
```
|
||||
|
||||
This permanently deletes the user. Related data (sessions, accounts) is
|
||||
cascade-deleted. Conversations and tasks reference the user via `owner_id`
|
||||
which is set to `NULL` on delete (`set null`).
|
||||
|
||||
---
|
||||
|
||||
## System Health Monitoring
|
||||
|
||||
The health endpoint is available to admin users only.
|
||||
|
||||
```http
|
||||
GET /api/admin/health
|
||||
```
|
||||
|
||||
Sample response:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"database": { "status": "ok", "latencyMs": 2 },
|
||||
"cache": { "status": "ok", "latencyMs": 1 },
|
||||
"agentPool": { "activeSessions": 3 },
|
||||
"providers": [{ "id": "ollama", "name": "ollama", "available": true, "modelCount": 3 }],
|
||||
"checkedAt": "2026-03-15T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
`status` is `ok` when both database and cache pass. It is `degraded` when either
|
||||
service fails.
|
||||
|
||||
The web admin panel at `/admin` polls this endpoint and renders the results in a
|
||||
status dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Provider Configuration
|
||||
|
||||
Providers are configured via environment variables and loaded at gateway startup.
|
||||
No restart-free hot reload is supported; the gateway must be restarted after
|
||||
changing provider env vars.
|
||||
|
||||
### Ollama
|
||||
|
||||
Set `OLLAMA_BASE_URL` (or the legacy `OLLAMA_HOST`) to the base URL of your
|
||||
Ollama instance:
|
||||
|
||||
```env
|
||||
OLLAMA_BASE_URL=http://localhost:11434
|
||||
```
|
||||
|
||||
Specify which models to expose (comma-separated):
|
||||
|
||||
```env
|
||||
OLLAMA_MODELS=llama3.2,codellama,mistral
|
||||
```
|
||||
|
||||
Default when unset: `llama3.2,codellama,mistral`.
|
||||
|
||||
The gateway registers Ollama models using the OpenAI-compatible completions API
|
||||
(`/v1/chat/completions`).
|
||||
|
||||
### Custom Providers (OpenAI-compatible APIs)
|
||||
|
||||
Any OpenAI-compatible API (LM Studio, llama.cpp HTTP server, etc.) can be
|
||||
registered via `MOSAIC_CUSTOM_PROVIDERS`. The value is a JSON array:
|
||||
|
||||
```env
|
||||
MOSAIC_CUSTOM_PROVIDERS='[
|
||||
{
|
||||
"id": "lmstudio",
|
||||
"name": "LM Studio",
|
||||
"baseUrl": "http://localhost:1234",
|
||||
"models": ["mistral-7b-instruct"]
|
||||
}
|
||||
]'
|
||||
```
|
||||
|
||||
Each entry must include:
|
||||
|
||||
| Field | Required | Description |
|
||||
| --------- | -------- | ----------------------------------- |
|
||||
| `id` | Yes | Unique provider identifier |
|
||||
| `name` | Yes | Display name |
|
||||
| `baseUrl` | Yes | API base URL (no trailing slash) |
|
||||
| `models` | Yes | Array of model ID strings to expose |
|
||||
| `apiKey` | No | API key if required by the endpoint |
|
||||
|
||||
### Testing Provider Connectivity
|
||||
|
||||
From the web admin panel or settings page, click **Test** next to a provider.
|
||||
This calls:
|
||||
|
||||
```http
|
||||
POST /api/agent/providers/:id/test
|
||||
```
|
||||
|
||||
The response includes `reachable`, `latencyMs`, and optionally
|
||||
`discoveredModels`.
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Configuration
|
||||
|
||||
The gateway can connect to external MCP (Model Context Protocol) servers and
|
||||
expose their tools to agent sessions.
|
||||
|
||||
Set `MCP_SERVERS` to a JSON array of server configurations:
|
||||
|
||||
```env
|
||||
MCP_SERVERS='[
|
||||
{
|
||||
"name": "my-tools",
|
||||
"url": "http://localhost:3001/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer my-token"
|
||||
}
|
||||
}
|
||||
]'
|
||||
```
|
||||
|
||||
Each entry:
|
||||
|
||||
| Field | Required | Description |
|
||||
| --------- | -------- | ----------------------------------- |
|
||||
| `name` | Yes | Unique server name |
|
||||
| `url` | Yes | MCP server URL (`/mcp` endpoint) |
|
||||
| `headers` | No | Additional HTTP headers (e.g. auth) |
|
||||
|
||||
On gateway startup, each configured server is connected and its tools are
|
||||
discovered. Tools are bridged into the Pi SDK tool format and become available
|
||||
in agent sessions.
|
||||
|
||||
The gateway itself also exposes an MCP server endpoint at `POST /mcp` for
|
||||
external clients. Authentication requires a valid BetterAuth session (cookie or
|
||||
`Authorization` header).
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Reference
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start. |
|
||||
| `DATABASE_URL` | PostgreSQL connection string. Default: `postgresql://mosaic:mosaic@localhost:5433/mosaic` |
|
||||
|
||||
### Gateway
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --------------------- | ----------------------- | ---------------------------------------------- |
|
||||
| `GATEWAY_PORT` | `4000` | Port the gateway listens on |
|
||||
| `GATEWAY_CORS_ORIGIN` | `http://localhost:3000` | Allowed CORS origin for browser clients |
|
||||
| `BETTER_AUTH_URL` | `http://localhost:4000` | Public URL of the gateway (used by BetterAuth) |
|
||||
|
||||
### SSO (Optional)
|
||||
|
||||
| Variable | Description |
|
||||
| ------------------------- | ------------------------------ |
|
||||
| `AUTHENTIK_CLIENT_ID` | Authentik OAuth2 client ID |
|
||||
| `AUTHENTIK_CLIENT_SECRET` | Authentik OAuth2 client secret |
|
||||
| `AUTHENTIK_ISSUER` | Authentik OIDC issuer URL |
|
||||
|
||||
All three Authentik variables must be set together. If only `AUTHENTIK_CLIENT_ID`
|
||||
is set, a warning is logged and SSO is disabled.
|
||||
|
||||
### Agent
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------ | --------------- | ------------------------------------------------------- |
|
||||
| `AGENT_FILE_SANDBOX_DIR` | `process.cwd()` | Root directory for file/git/shell tool access |
|
||||
| `AGENT_SYSTEM_PROMPT` | — | Platform-level system prompt injected into all sessions |
|
||||
| `AGENT_USER_TOOLS` | all tools | Comma-separated allowlist of tools for non-admin users |
|
||||
|
||||
### Providers
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ---------------------------- | ------------------------------------------------ |
|
||||
| `OLLAMA_BASE_URL` | — | Ollama API base URL |
|
||||
| `OLLAMA_HOST` | — | Alias for `OLLAMA_BASE_URL` (legacy) |
|
||||
| `OLLAMA_MODELS` | `llama3.2,codellama,mistral` | Comma-separated Ollama model IDs |
|
||||
| `MOSAIC_CUSTOM_PROVIDERS` | — | JSON array of custom OpenAI-compatible providers |
|
||||
|
||||
### Memory and Embeddings
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------- | --------------------------- | ---------------------------------------------------- |
|
||||
| `OPENAI_API_KEY` | — | API key for OpenAI embedding and summarization calls |
|
||||
| `EMBEDDING_API_URL` | `https://api.openai.com/v1` | Base URL for embedding API |
|
||||
| `EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model ID |
|
||||
| `SUMMARIZATION_API_URL` | `https://api.openai.com/v1` | Base URL for log summarization API |
|
||||
| `SUMMARIZATION_MODEL` | `gpt-4o-mini` | Model used for log summarization |
|
||||
| `SUMMARIZATION_CRON` | `0 */6 * * *` | Cron schedule for log summarization (every 6 hours) |
|
||||
| `TIER_MANAGEMENT_CRON` | `0 3 * * *` | Cron schedule for log tier management (daily at 3am) |
|
||||
|
||||
### MCP
|
||||
|
||||
| Variable | Description |
|
||||
| ------------- | ------------------------------------------------ |
|
||||
| `MCP_SERVERS` | JSON array of external MCP server configurations |
|
||||
|
||||
### Plugins
|
||||
|
||||
| Variable | Description |
|
||||
| ---------------------- | ------------------------------------------------------------------------- |
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token (enables Discord plugin) |
|
||||
| `DISCORD_GUILD_ID` | Discord guild/server ID |
|
||||
| `DISCORD_GATEWAY_URL` | Gateway URL for Discord plugin to call (default: `http://localhost:4000`) |
|
||||
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (enables Telegram plugin) |
|
||||
| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call |
|
||||
|
||||
### Observability
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------------- | ----------------------- | -------------------------------- |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OpenTelemetry collector endpoint |
|
||||
| `OTEL_SERVICE_NAME` | `mosaic-gateway` | Service name in traces |
|
||||
|
||||
### Web App
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ----------------------- | -------------------------------------- |
|
||||
| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:4000` | Gateway URL used by the Next.js client |
|
||||
|
||||
### Coordination
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------- | ----------------------------- | ------------------------------------------ |
|
||||
| `MOSAIC_WORKSPACE_ROOT` | monorepo root (auto-detected) | Root path for mission workspace operations |
|
||||
Reference in New Issue
Block a user