> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment

> How Noxus environment configuration is structured across deployment models

Noxus configuration is split between:

* **runtime env vars** (URLs, deployment mode, non-sensitive settings)
* **secrets** (credentials and keys)
* **admin-managed platform settings** (global configuration in the Noxus admin portal)

## Configuration Sources

```mermaid theme={null}
flowchart LR
  GIT[Helm values / Compose / IaC] --> ENV[Runtime Env Vars]
  SM[Secret Manager / K8s Secret / Env files] --> SEC[Secrets]
  ADM[Noxus Admin Portal] --> CFG[server_settings and auth config]
  ENV --> APP[Noxus services]
  SEC --> APP
  CFG --> APP
```

## Environment Variable Layers

| Layer                | Example                                             |
| -------------------- | --------------------------------------------------- |
| Base platform env    | deployment env, URLs, storage mode, feature toggles |
| Service-specific env | frontend-only host binding, worker subscribe mode   |
| Secrets              | DB/Redis credentials, auth keys, provider secrets   |

## Environment Variable Reference

### Platform

| Variable          | Default   | Description                                                         |
| ----------------- | --------- | ------------------------------------------------------------------- |
| `DEPLOYMENT_ENV`  | `"prod"`  | Environment name for logging purposes                               |
| `DEPLOYMENT_NAME` | `"NOXUS"` | Display name for the deployment instance                            |
| `ON_PREM`         | `"false"` | Set to `"true"` for non-cloud based deployments                     |
| `ADMIN_EMAIL`     | —         | Admin email used during initial bootstrap - only used on first boot |

### URLs

| Variable       | Default | Description                                                                                                             |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `BACKEND_URL`  | —       | Public URL for the backend API (e.g. `https://api.example.com`). Can be set to an internal LB for the frontend instance |
| `FRONTEND_URL` | —       | Public URL for the frontend (e.g. `https://example.com`)                                                                |
| `RELAY_URL`    | —       | Public URL for the relay service (e.g. `https://relay.example.com`)                                                     |

### Database Configuration

| Variable                    | Default  | Description                                   |
| --------------------------- | -------- | --------------------------------------------- |
| `DATABASE`                  | `"spot"` | PostgreSQL database name                      |
| `POSTGRES_POOL_SIZE`        | `"64"`   | Connection pool size for the primary database |
| `VECTOR_POSTGRES_POOL_SIZE` | `"128"`  | Connection pool size for the vector database  |
| `RUN_MIGRATIONS`            | `"1"`    | Run Alembic migrations on startup             |

### Redis

| Variable               | Default   | Description                                                                             |
| ---------------------- | --------- | --------------------------------------------------------------------------------------- |
| `REDIS_PORT`           | `"6379"`  | Redis server port                                                                       |
| `REDIS_SSL`            | `""`      | Enable SSL for Redis connections                                                        |
| `REDIS_SINGLE_DB_ONLY` | `""`      | Restrict to a single Redis database, for compatibility with some managed Redis services |
| `CACHE_LOCATION`       | `"redis"` | Cache backend location                                                                  |

### Object Storage

| Variable                | Default       | Description                                  |
| ----------------------- | ------------- | -------------------------------------------- |
| `BUCKET_CLIENT`         | `"s3"`        | Storage provider: `gcloud`, `s3`, or `minio` |
| `STORAGE_BUCKET`        | —             | Primary storage bucket name                  |
| `PUBLIC_STORAGE_BUCKET` | —             | Public assets bucket name                    |
| `S3_ENDPOINT_URL`       | `""`          | Custom S3 endpoint (leave empty for AWS S3)  |
| `AWS_REGION`            | `"eu-west-1"` | AWS region for S3 operations                 |

### Observability

| Variable                   | Default  | Description                                   |
| -------------------------- | -------- | --------------------------------------------- |
| `OTEL_COLLECTOR_ENDPOINT`  | `""`     | OpenTelemetry collector endpoint              |
| `PROMETHEUS_MULTIPROC_DIR` | `"/tmp"` | Directory for Prometheus multiprocess metrics |
| `PROM_REMOTE_WRITE_URL`    | `""`     | Prometheus remote write endpoint              |
| `ENABLE_LLM_OBSERVABILITY` | `"true"` | Enable LLM call tracing in OTEL               |

### Worker Configuration (per deployment)

| Variable                      | Default        | Description                                            |
| ----------------------------- | -------------- | ------------------------------------------------------ |
| `WORKER_SUBSCRIBE`            | `"all_but_kb"` | Queue type: `all`, `all_but_kb`, `flow`, `chat`, `kb`  |
| `WORKER_SUBSCRIBE_TENANTS`    | `""`           | Comma-separated tenant IDs to process (empty = all)    |
| `WORKER_SUBSCRIBE_WORKSPACES` | `""`           | Comma-separated workspace IDs to process (empty = all) |

### Plugin Server

| Variable            | Default | Description                                                 |
| ------------------- | ------- | ----------------------------------------------------------- |
| `PLUGIN_SERVER_URL` | `""`    | URL of the plugin server. Empty disables the plugin system. |

***

## Deployment-Independent Principles

* Keep non-sensitive settings in environment config
* Keep credentials in secrets only
* Keep environment names simple (`local`, `staging`, `prod`)
* Do not expose internal-only controls (such as billing internals) in user-facing docs

<Note>
  Noxus supports extensive runtime configuration from the admin portal when the user has global admin permissions. This includes global server settings and auth behavior.
</Note>

## Practical Mapping In Your Stack

* VM compose: `env_file` and explicit env mounts
* Helm: `env`, `extraEnv`, `secrets`, plus service-specific secret variants
* Terraform stage3: secret/env materialization and namespace-scoped injection

<CardGroup cols={2}>
  <Card title="Secrets" icon="key-round" href="/deployment/configuration/secrets">
    Secret handling, provider credentials, and worker secret injection
  </Card>

  <Card title="Workers" icon="server" href="/deployment/configuration/workers">
    Worker pools, task routing, tenant isolation, and autoscaling
  </Card>

  <Card title="Database" icon="database" href="/deployment/configuration/database">
    PostgreSQL and pgvector requirements
  </Card>

  <Card title="Storage" icon="hard-drive" href="/deployment/configuration/storage">
    Object storage, vector databases, and caching layers
  </Card>
</CardGroup>