Skip to content
InsightSpaceInsightSpace

Configuration

InsightSpace uses environment variables for deployment settings and read-only files for secrets. The application repository’s .env.template is the source of truth for the release you deploy.

Application addresses

Section titled “Application addresses”
Setting Purpose
FRONTEND_PUBLIC_ORIGIN Public browser origin allowed by CORS and used in generated links
BACKEND_BASE_URL Public API address used by the frontend and email links
BACKEND_ALLOWED_HOSTS Hosts accepted by the ASP.NET Core application
FRONTEND_CONTAINER_PORT Internal frontend port
BACKEND_CONTAINER_PORT Internal backend port

Origins must include the correct scheme and port. Inconsistent public addresses commonly cause CORS, cookie, redirect, and email-link failures.

Database

Section titled “Database”
Setting Purpose
POSTGRES_DB Database name
POSTGRES_USER Database user
POSTGRES_CONTAINER_PORT PostgreSQL service port

The password is read from the postgres_password secret file. Apply database migrations explicitly before starting the regular backend process after an upgrade.

Object storage

Section titled “Object storage”
Setting Purpose
S3_ENDPOINT_URL S3 API endpoint; empty only for AWS S3
S3_PUBLIC_ENDPOINT_URL Optional endpoint used where a public or host-reachable URL differs
S3_REGION Storage region
S3_BUCKET Bucket used by InsightSpace
S3_FORCE_PATH_STYLE Enables path-style addressing for compatible services such as Garage

Credentials are read from s3_access_key_id and s3_secret_access_key secret files.

Extraction and indexing

Section titled “Extraction and indexing”
Setting Purpose
EXTRACTOR_BASE_URL Backend-to-extractor address
EXTRACTOR_MAX_CONCURRENCY Maximum simultaneous extraction subprocesses
INDEXING_MAX_CHUNK_TOKENS Maximum token target for indexed chunks

The backend and extractor share a bearer token through the extractor_token secret file. More concurrent extractor workers increase throughput but also increase peak memory because each worker loads its own model set.

Inference and retrieval

Section titled “Inference and retrieval”
Setting Purpose
OLLAMA_LOCAL_BASE_URL Local or remote Ollama endpoint; empty for a cloud-only deployment
OLLAMA_LOCAL_ENABLE_CHAT Whether local Ollama models can be used for chat
EMBEDDING_PROVIDER Provider used to create document embeddings
EMBEDDING_MODEL Embedding model identifier
EMBEDDING_DIMENSIONS Vector dimension expected from the embedding model
RERANKING_PROVIDER Provider used to rerank retrieved evidence
RERANKING_MODEL Reranking model identifier

The embedding dimension must match the selected model and the index configuration. Changing an embedding provider, model, or dimension requires a deliberate reindexing plan.

Optional chat providers are enabled by their token files and any provider-specific non-secret settings. Supported provider names and models come from the release’s model catalog.

Email

Section titled “Email”
Setting Purpose
SMTP_SERVER SMTP server hostname
SMTP_USER SMTP account name
SMTP_FROM_EMAIL Sender address
SMTP_DOMAIN Domain used for email behavior and policy

The SMTP password is read from the smtp_password secret file. Confirm that public frontend and backend addresses are correct before testing invitation, confirmation, or reset links.

Reverse proxy and trusted forwarding

Section titled “Reverse proxy and trusted forwarding”
Setting Purpose
CADDY_FRONTEND_ADDRESS Frontend address handled by Caddy
CADDY_BACKEND_ADDRESS Backend address handled by Caddy
BACKEND_KNOWN_PROXY Trusted proxy IP address
BACKEND_KNOWN_PROXY_NETWORK Trusted proxy network in CIDR notation
EXTERNAL_NETWORK_NAME Shared Docker network for web-tier services

Leave trusted-proxy settings unset when no proxy is present. Never trust arbitrary forwarded headers; audit and rate-limiting data must reflect the real client address.

Secrets and protected keys

Section titled “Secrets and protected keys”

The Compose topology expects secret files for:

  • PostgreSQL password;
  • SMTP password;
  • license key;
  • extractor token;
  • S3 access key ID and secret access key;
  • data-protection certificate and its password; and
  • optional provider tokens.

Keep restrictive filesystem permissions, mount secrets read-only, and rotate them using the release’s operator procedure. A configured but missing, unreadable, or empty secret file should be treated as a startup error, not as permission to silently disable the protected capability.

Select modular components

Section titled “Select modular components”

The modular Compose prototype uses COMPOSE_PROFILES to enable local infrastructure:

COMPOSE_PROFILES=garage,caddy,ollama,extractor

Remove a profile when that capability is supplied externally, then update the corresponding endpoint and credentials. The application core remains enabled.