Configuration and Deployment

Ragty backend settings use the M8TY_RAGTY_ prefix and are read from environment variables or backend/.env. Frontend routing has a separate build-time base-path setting.

Required backend settings

These values have no application default and must be supplied to the backend and worker. They are the only settings that are always mandatory; every other setting below is optional (its default applies) or conditional (required only in the noted situation), as marked in the Required column of each table.

Variable	Purpose
`M8TY_RAGTY_AUTH_JWT_SECRET`	Signs local session JWTs
`M8TY_RAGTY_DATABASE_URL`	Async SQLAlchemy PostgreSQL URL
`M8TY_RAGTY_REDIS_URL`	Direct Redis endpoint, or Redis data-node credentials/TLS/database settings when Sentinel is enabled
`M8TY_RAGTY_S3_ENDPOINT`	S3-compatible object-storage endpoint
`M8TY_RAGTY_S3_ACCESS_KEY`	Object-storage access key
`M8TY_RAGTY_S3_SECRET_KEY`	Object-storage secret key
`M8TY_RAGTY_CREDENTIAL_ENCRYPTION_KEY`	Master material used to encrypt stored provider and connector credentials

When M8TY_RAGTY_APP_ENV=production, the JWT and credential-encryption secrets must each contain at least 32 characters. Keep all secrets in a secret manager or Kubernetes Secret, never in a frontend variable or image layer.

Application and authentication

The Required column states whether a value must be supplied. "No" means the listed default applies when unset. "Conditional" means it is required only in the noted situation.

Variable	Required	Description	Default
`M8TY_RAGTY_APP_ENV`	No	`development`, `production`, or `prod`	`development`
`M8TY_RAGTY_LOG_LEVEL`	No	Application log level	`INFO`
`M8TY_RAGTY_ROOT_PATH`	No	FastAPI root path when the backend is externally mounted under a prefix	empty
`M8TY_RAGTY_FRONTEND_URL`	No (recommended in production)	Canonical browser-visible frontend URL used for invitations and OAuth callbacks	`http://localhost:8080`
`M8TY_RAGTY_AUTH_MODE`	No	`local`, `oidc`, or `both`	`local`
`M8TY_RAGTY_OIDC_ISSUER_URL`	Conditional — required in `oidc`/`both` modes	OIDC issuer	empty
`M8TY_RAGTY_OIDC_AUDIENCE`	No	Expected OIDC audience	`m8ty-rag`
`M8TY_RAGTY_SELF_REGISTRATION_ENABLED`	No	Allow public local account registration	`false`
`M8TY_RAGTY_OIDC_AUTO_PROVISION_ENABLED`	No	Create an unknown validated OIDC identity on first login	`false`
`M8TY_RAGTY_BOOTSTRAP_ADMIN_EMAIL`	No — set with the password to seed the first superadmin	First platform-superadmin email	empty
`M8TY_RAGTY_BOOTSTRAP_ADMIN_PASSWORD`	Conditional — required with the bootstrap email	Bootstrap password, at least 12 characters	empty
`M8TY_RAGTY_BOOTSTRAP_ADMIN_NAME`	No	Bootstrap display name	`superadmin`
`M8TY_RAGTY_MAX_UPLOAD_BYTES`	No	Maximum direct document-upload size in bytes (range 1 KiB–1 GiB)	`104857600` (100 MiB)
`M8TY_RAGTY_RATE_LIMIT_ENABLED`	No	Enable the main-API HTTP rate limiter (fails closed with `503` when Redis is unavailable)	`true`
`M8TY_RAGTY_RATE_LIMIT_REQUESTS_PER_MINUTE`	No	Requests per rolling 60s window per caller (range 1–100000)	`120`
`M8TY_RAGTY_ARGON2_TIME_COST`	No	Argon2id iterations for password hashing (range 1–10)	`2`
`M8TY_RAGTY_ARGON2_MEMORY_COST_KIB`	No	Argon2id memory cost in KiB (range 8192–1048576)	`19456`
`M8TY_RAGTY_ARGON2_PARALLELISM`	No	Argon2id parallelism lanes (range 1–16)	`1`
`M8TY_RAGTY_CRAWLER_ALLOWED_INTERNAL_CIDRS`	No	Comma-separated internal CIDR allowlist for the web crawler/SSRF guard; loopback, link-local, and metadata ranges stay blocked	empty

Bootstrap email and password must be configured together. Bootstrap is available only in local or both mode, not pure oidc mode. Legacy bcrypt password hashes remain verifiable and are upgraded to Argon2id on the next successful login.

Storage and vector backend

Variable	Required	Description	Default
`M8TY_RAGTY_QDRANT_URL`	No	Qdrant URL; an empty value selects PostgreSQL/pgvector	empty
`M8TY_RAGTY_QDRANT_COLLECTION_NAME`	No	Qdrant collection	`documents`
`M8TY_RAGTY_S3_REGION`	No	S3 signing region	`us-east-1`
`M8TY_RAGTY_S3_ARTIFACTS_BUCKET`	No	Document-artifact bucket	`m8ty-artifacts`

PostgreSQL remains required when Qdrant is enabled because it stores application metadata and authorization state. The default Compose deployment uses pgvector/pgvector:pg16 and does not start a Qdrant container.

Redis and workers

Variable	Required	Description	Default
`M8TY_RAGTY_REDIS_SENTINEL_NODES`	No	Comma-separated Sentinel `host[:port]` endpoints; non-empty enables discovery	empty
`M8TY_RAGTY_REDIS_SENTINEL_MASTER`	Conditional — used when Sentinel nodes are set	Sentinel master group	`mymaster`
`M8TY_RAGTY_REDIS_SENTINEL_PASSWORD`	No	Optional password for Sentinel control connections	empty
`M8TY_RAGTY_REDIS_KEY_PREFIX`	No	Prefix for Ragty-owned Redis keys and the ARQ queue	`m8ty-rag:`
`M8TY_RAGTY_WORKER_COUNT`	No	Process-count setting for deployment launchers that consume it; the direct ARQ command starts one process	`1`
`M8TY_RAGTY_WORKER_MAX_JOBS`	No	Concurrent jobs per ARQ worker	`1`
`M8TY_RAGTY_WORKER_JOB_TIMEOUT_SECONDS`	No	Maximum runtime for one document-processing job (must be positive)	`3600`
`M8TY_RAGTY_WORKER_LEASE_HEARTBEAT_SECONDS`	No	Processing-lease refresh interval (must be lower than the lease timeout)	`15`
`M8TY_RAGTY_WORKER_LEASE_TIMEOUT_SECONDS`	No	Stale-processing lease timeout (must be below job timeout + ARQ's 10s grace)	`3000`
`M8TY_RAGTY_GPU_WORKER_CONCURRENCY`	No	Concurrent GPU parsing work	`1`

The worker health key belongs to the namespaced ARQ queue and is refreshed every 10 seconds. A shutting-down worker removes its registration; another running worker can then create the key on its next health interval. The processing-health endpoint reports availability, not the exact replica count.

Models and observability

Variable	Required	Description	Default
`M8TY_RAGTY_OPENAI_API_KEY`	No	Optional fallback key for OpenAI embeddings	empty
`M8TY_RAGTY_OLLAMA_URL`	No	Ollama endpoint	`http://localhost:11434`
`M8TY_RAGTY_LITELLM_URL`	No	Optional LiteLLM/OpenAI-compatible endpoint	`http://localhost:4000`
`M8TY_RAGTY_LITELLM_API_KEY`	No	Optional LiteLLM key	empty
`M8TY_RAGTY_LANGFUSE_PUBLIC_KEY`	No	Optional Langfuse public key	empty
`M8TY_RAGTY_LANGFUSE_SECRET_KEY`	No	Optional Langfuse secret key	empty
`M8TY_RAGTY_LANGFUSE_HOST`	No	Langfuse host	`https://cloud.langfuse.com`
`M8TY_RAGTY_EGRESS_ALLOWED_HOSTS`	No	Additional exact operator-allowlisted hosts for custom model, provider-verification, reranker, ingestion-provider, and Langfuse endpoints; non-allowlisted hosts fail closed	empty

Provider and model records configured in Settings → Providers take precedence for their respective workloads.

Email and connector OAuth

Variable	Required	Description	Default
`M8TY_RAGTY_SMTP_ENABLED`	No	Enable invitation email	`false`
`M8TY_RAGTY_SMTP_HOST`	Conditional — required when SMTP is enabled	SMTP host	empty
`M8TY_RAGTY_SMTP_PORT`	No	SMTP port	`587`
`M8TY_RAGTY_SMTP_USER`	No	SMTP username	empty
`M8TY_RAGTY_SMTP_PASSWORD`	No	SMTP password	empty
`M8TY_RAGTY_SMTP_FROM`	Conditional — required when SMTP is enabled	Sender address	empty
`M8TY_RAGTY_SMTP_TLS`	No	Enable SMTP TLS	`true`

OAuth connectors use matching M8TY_RAGTY_<PROVIDER>_OAUTH_CLIENT_ID and M8TY_RAGTY_<PROVIDER>_OAUTH_CLIENT_SECRET pairs. All OAuth client settings are optional and default to empty; the corresponding OAuth flow returns an error only when its client is required but unset. Supported provider prefixes are GOOGLE, SLACK, CONFLUENCE, JIRA, BOX, GITHUB, and DROPBOX.

Delegated end-user isolation

These settings gate and tune delegated end-user isolation. They are consumed by both the API and the ingestion worker, and the trusted registry is server-owned deployment configuration — never accept registry fields from request parameters or manifests. The feature is off by default; enabling it requires a non-empty trusted issuer registry and verified ownership storage, or startup fails closed.

Variable	Required	Description	Default
`M8TY_RAGTY_DELEGATED_ENABLED`	No	Single on/off gate. When `true`, member/staff exclusion, exact-subject retrieval, startup storage-readiness enforcement, the `delegated_manifest` connector, and the MCP gateway assertion path all activate together	`false`
`M8TY_RAGTY_TRUSTED_END_USER_ISSUERS`	Conditional — required when `M8TY_RAGTY_DELEGATED_ENABLED=true`	JSON array of trusted issuers; each entry requires `issuer_id`, `issuer`, `tenant_id`, `audience`, and `jwks_uri`, with `allowed_algorithms` defaulting to `["RS256"]`. Issuer/JWKS URLs must use HTTPS in production	`[]`
`M8TY_RAGTY_DELEGATED_SUBJECT_MAX_BYTES`	No	Raw-subject UTF-8 size limit before hashing (range 1–4096)	`512`
`M8TY_RAGTY_DELEGATED_ASSERTION_MAX_BYTES`	No	Maximum encoded end-user assertion size (range 1024–65536)	`16384`
`M8TY_RAGTY_DELEGATED_HEADER_MAX_BYTES`	No	Request-header budget for delegated auth; must be ≥ the assertion limit (range 1024–131072)	`32768`
`M8TY_RAGTY_DELEGATED_CLOCK_SKEW_SECONDS`	No	Assertion time-claim allowance (range 0–300)	`60`
`M8TY_RAGTY_DELEGATED_JWKS_CONNECT_TIMEOUT_SECONDS`	No	Connect timeout for pinned JWKS requests (0 < value ≤ 30)	`2.0`
`M8TY_RAGTY_DELEGATED_JWKS_READ_TIMEOUT_SECONDS`	No	Read timeout for pinned JWKS responses (0 < value ≤ 30)	`5.0`
`M8TY_RAGTY_DELEGATED_JWKS_CACHE_TTL_SECONDS`	No	Successful-JWKS cache TTL (range 30–3600)	`300`
`M8TY_RAGTY_DELEGATED_JWKS_MAX_RESPONSE_BYTES`	No	JWKS response size limit; oversized responses fail closed (range 1024–5242880)	`1048576`

The raw external subject and JWTs are never logged or persisted; startup diagnostics identify only safe issuer IDs, the enabled flag, and validation categories. Prepare and verify ownership storage with backend/scripts/migrate_delegated_subject_storage.py before setting M8TY_RAGTY_DELEGATED_ENABLED=true. Disabling the flag after delegated documents exist would re-expose them to member searches, so treat activation as one-way in production.

Frontend settings

Variable	Phase	Required	Description	Default
`NEXT_PUBLIC_BASE_PATH`	Build time	No	Next.js base path such as `/ragty`; changing it requires rebuilding the frontend	empty
`M8TY_RAGTY_BACKEND_URL`	Runtime, server side	No	Internal backend URL used by the Next.js administration proxy	`http://localhost:8000`

Browser administration calls are same-origin requests to <base-path>/admin-api/*. Do not expose the internal backend URL through a NEXT_PUBLIC_* variable.

HTTP boundaries

Boundary	Path	Exposure
Frontend and administration proxy	`/` and `/admin-api/*`	Browser-facing
Public integrations	`/api/v1/*`	Externally routable where required
MCP Streamable HTTP	`/mcp/`	Externally routable for MCP clients
Health	`/health`	Probe or operations boundary
Internal administration API	`/admin-api/v1/*`	Reached through the frontend proxy; do not publish as the browser API

/mcp redirects to /mcp/ because the MCP server is mounted as a sub-application. Configure clients with the trailing slash to avoid redirect-sensitive POST behavior.

Run with Docker Compose

Use this procedure for a local development or evaluation installation. The Compose defaults contain development credentials and must not be reused for a production deployment.

1. Install prerequisites

Install:

Docker Engine with the Docker Compose plugin, or Docker Desktop;
curl and unzip to prepare the DeepDoc model build context;
enough free disk space for the container images, model assets, and persistent PostgreSQL and MinIO data.

Run all following commands from the Ragty repository root—the directory that contains docker-compose.yml.

2. Download DeepDoc assets

The backend image is intentionally built for offline model execution. The ignored backend/deepdoc-models/ build context must therefore exist before the first build.

MODEL_BASE=https://modelscope.cn/models/Xorbits/deepdoc/resolve/master
mkdir -p backend/deepdoc-models/vision backend/deepdoc-models/xgb

for file in \
  vision/det.onnx \
  vision/layout.onnx \
  vision/layout.laws.onnx \
  vision/layout.manual.onnx \
  vision/layout.paper.onnx \
  vision/ocr.res \
  vision/rec.onnx \
  vision/tsr.onnx \
  xgb/updown_concat_xgb.model
do
  curl --fail --show-error --location --retry 5 \
    "$MODEL_BASE/$file" \
    --output "backend/deepdoc-models/$file"
done

mkdir -p \
  backend/deepdoc-models/nltk_data/tokenizers \
  backend/deepdoc-models/nltk_data/corpora \
  backend/deepdoc-models/nltk_data/taggers

for resource in \
  tokenizers/punkt \
  tokenizers/punkt_tab \
  corpora/wordnet \
  taggers/averaged_perceptron_tagger
do
  category="${resource%/*}"
  package="${resource#*/}"
  curl --fail --show-error --location --retry 5 \
    "https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/packages/${category}/${package}.zip" \
    --output "/tmp/${package}.zip"
  unzip -qo "/tmp/${package}.zip" \
    -d "backend/deepdoc-models/nltk_data/${category}/"
done

These are the same model and Natural Language Toolkit (NLTK) resources prepared by the GitLab image-build job. Repeat the download only when the model bundle is missing or deliberately refreshed.

3. Configure the first administrator

A fresh database has no login account, and public registration is disabled by default. Create a repository-root .env file with the initial administrator:

M8TY_RAGTY_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
M8TY_RAGTY_BOOTSTRAP_ADMIN_PASSWORD=replace-with-a-secret-of-at-least-12-characters
M8TY_RAGTY_BOOTSTRAP_ADMIN_NAME=superadmin

Docker Compose reads this .env file for variable interpolation. It is ignored by Git and must remain local. Bootstrap runs only while the user table is empty; later restarts do not reset the account or password.

4. Build and start the stack

docker compose up --build --detach

The first build can take several minutes because it installs the parser stack and copies the offline model bundle. The current Compose file starts:

Service	Host port	Purpose
`frontend`	`8080`	Next.js UI and same-origin administration proxy
`backend`	`8000`	FastAPI application, public API, and MCP
`worker`	none	ARQ parsing and data-source synchronization
`postgres`	`5432`	Relational metadata and default pgvector store
`redis`	`6379`	Queue, worker health, and application cache
`minio`	`9000`, console `9001`	S3-compatible artifacts

Inside Compose, use service DNS names such as postgres, redis, and minio. A provider running on the Docker host may require host.docker.internal; a provider in Compose should use its service name.

5. Verify startup

docker compose ps
curl --fail http://localhost:8000/health

A healthy default installation returns:

{"status":"ok","vector_backend":"pgvector"}

Open http://localhost:8080 and sign in with the bootstrap email and password. MinIO's administration console is available at http://localhost:9001 with the development credentials minioadmin/minioadmin.

If a service does not become healthy, inspect the API, worker, and frontend logs:

docker compose logs --follow backend worker frontend

Press Ctrl+C to stop following logs; the containers keep running in detached mode.

Rebuild or restart

Rebuild after pulling application or dependency changes:

docker compose up --build --detach

Restart existing containers without rebuilding images:

docker compose restart

Stop or reset

Stop containers while preserving PostgreSQL and MinIO named volumes:

docker compose down

To remove the local database and uploaded artifacts as well, explicitly delete the named volumes:

docker compose down --volumes

The --volumes form is destructive. The next start creates an empty database and runs bootstrap again from the configured environment.

Optional Qdrant backend

The supplied Compose stack uses pgvector and does not contain a Qdrant service. To use Qdrant, add a local docker-compose.override.yml that starts or reaches Qdrant and passes M8TY_RAGTY_QDRANT_URL to both backend and worker:

services:
  backend:
    environment:
      M8TY_RAGTY_QDRANT_URL: http://qdrant:6333
  worker:
    environment:
      M8TY_RAGTY_QDRANT_URL: http://qdrant:6333
  qdrant:
    image: qdrant/qdrant:latest
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  qdrant_data:

The override file is ignored by Git. Pin the Qdrant image version and replace all development credentials before using a derivative configuration outside a local environment. PostgreSQL remains required for Ragty application data.

Reverse proxies and base paths

Frontend and backend prefixes are independent:

Build the frontend with NEXT_PUBLIC_BASE_PATH=/ragty when it is served at /ragty.
Set M8TY_RAGTY_FRONTEND_URL=https://example.com/ragty so generated links and OAuth callbacks use the canonical public URL.
Keep M8TY_RAGTY_BACKEND_URL=http://backend:8000 unprefixed when the frontend proxy reaches the backend over the internal network.
Set M8TY_RAGTY_ROOT_PATH only when FastAPI itself is externally mounted beneath a prefix.

Preserve the frontend base path when proxying to Next.js. For example, a trailing slash on this proxy_pass would strip /ragty and is therefore intentionally omitted:

location = /ragty {
    return 308 /ragty/;
}

location /ragty/ {
    proxy_pass http://frontend:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /ragty;
}

Terminate TLS at the trusted ingress or reverse proxy and overwrite forwarded host and protocol headers there. Register OAuth callback URLs against the same canonical hostname and frontend base path.

Kubernetes guidance

Scale stateless backend replicas behind a service.
Scale worker replicas by queue demand while keeping per-worker GPU concurrency bounded.
Use managed PostgreSQL, Redis/Sentinel, and object storage where availability requirements justify it.
Give Qdrant persistent storage when it is selected as the vector backend.
Route only the documented public boundaries; keep /admin-api/v1/* internal.
Use GET /health for the backend readiness signal and the internal GET /admin-api/v1/health/processing endpoint for worker availability.

Health responses

GET /health reports the selected vector backend after initialization:

{"status":"ok","vector_backend":"pgvector"}

If vector-store initialization failed, it reports a degraded result:

{"status":"degraded","vector_store":"unreachable"}

12 September 2026