Configuration
InsightSpace uses environment variables for deployment settings and read-only files for secrets. The configuration template supplied with your release is the source of truth for the installation.
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 |
|---|---|
LOCAL_INFERENCE_BASE_URL |
Endpoint of the agreed local inference service |
LOCAL_INFERENCE_ENABLE_CHAT |
Whether local inference is available 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.
| Setting | Purpose |
|---|---|
SMTP_SERVER |
SMTP server hostname |
SMTP_PORT |
SMTP submission port; the mail service must support STARTTLS |
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.
Validate configuration before handover
Section titled “Validate configuration before handover”- Open the application from a normal user device and sign in.
- Test an invitation or account-recovery email and open its link from the intended network.
- Upload the tutorial PDF and wait for indexing to complete.
- Ask a question, open a citation, and export a working document.
- Confirm that database, source files, extraction artifacts, and protected keys are covered by the agreed backup and restore procedure.
Keep the release version and configuration changes in the operator’s own change record. Use the supplied release procedure for installation and upgrades; an environment file alone is not a complete installation.