188 lines
8.9 KiB
Markdown
188 lines
8.9 KiB
Markdown
# Configuration
|
|
|
|
Most installations can keep the defaults. Settings come from environment
|
|
variables and an env file:
|
|
|
|
| How you start Fluksio | Env file |
|
|
|---|---|
|
|
| `fluksio serve` | `<data-dir>/env`, unless `FLUKSIO_ENV_FILE` names another file |
|
|
| Docker with the Makefile | `.env` in this repository's root |
|
|
|
|
Exported variables override the file. `fluksio serve` flags override both.
|
|
For CLI installations, select storage with `--data-dir`, `FLUKSIO_HOME` or
|
|
`--global`; see [The fluksio command](../code/cli.md).
|
|
|
|
## Storage
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `DATA_DIR` | `flow-data`; CLI uses `./.fluksio` or `~/.fluksio` with `--global` | base directory for instance data |
|
|
| `DATABASE_URL` | SQLite at `$DATA_DIR/fluksio.db` | SQLite URL; other database engines are unsupported |
|
|
| `FLOWS_DIR` | `$DATA_DIR/flows` | flow git repository |
|
|
| `SECRETS_FILE` | `$DATA_DIR/secrets.enc` | encrypted credentials |
|
|
| `ALERTS_FILE` | `$DATA_DIR/alerts.json` | alert channels and rules |
|
|
| `WEBPUSH_FILE` | `$DATA_DIR/webpush.json` | push keys and browser subscriptions |
|
|
| `PROVISIONERS_FILE` | `$DATA_DIR/provisioners.json` | optional worker provisioning configuration |
|
|
| `PANELS_FILE` | `$DATA_DIR/panels.json` | wall-panel pairings |
|
|
| `OAUTH_PRIVATE_KEY_FILE` | `$DATA_DIR/oauth-key.pem` | agent and worker signing key |
|
|
| `CLOUD_CONFIG_FILE` | `$DATA_DIR/cloud.json` | optional portal enrollment |
|
|
| `AI_CONFIG_FILE` | `$DATA_DIR/ai.json` | optional assistant provider configuration |
|
|
| `CHATS_DIR` | `$DATA_DIR/chats` | assistant transcripts |
|
|
| `NODE_VENV` | `auto` | interpreter for node code |
|
|
|
|
Changing `DATA_DIR` moves the derived paths unless you set them individually.
|
|
Docker stores instance data under `/data` on the `app-flow-data` volume.
|
|
|
|
| `NODE_VENV` value | Behavior |
|
|
|---|---|
|
|
| `auto` | keeps an existing managed venv; otherwise uses the installation's venv when available, or creates a managed one |
|
|
| `managed` | creates a venv under `DATA_DIR`; the Modules screen manages its packages |
|
|
| interpreter or venv path | uses the specified Python environment |
|
|
|
|
Docker uses `managed`. When Fluksio adopts your own venv, the Modules screen
|
|
is read-only; install packages into that environment yourself.
|
|
|
|
Back up the whole data directory and the persistent `SECRET_KEY`. In Docker,
|
|
keep `.env` and `app-flow-data`; back up `app-redis-data` too when preserving
|
|
live state. Compose prefixes volume names with the project name `fluksio-app`.
|
|
Keep runtime files on persistent storage so rebuilds preserve credentials,
|
|
pairings and subscriptions.
|
|
|
|
## Live state
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `REDIS_HOST` | unset | unset uses memory; a Redis host enables persistent flow state |
|
|
| `REDIS_PORT` | `6379` | Redis port |
|
|
|
|
Live state includes message values, node memory and queued work. In-memory
|
|
state is lost on restart. The Docker stack uses Redis with append-only
|
|
persistence on its own `app-redis-data` volume. Its default sync policy may
|
|
lose about a second of recent writes after an unclean shutdown.
|
|
|
|
## Accounts and access
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `SECRET_KEY` | generated | signs sessions and encrypts the secrets store; the CLI persists it and `make init` writes it to `.env` |
|
|
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `11520` (8 days) | session-token lifetime |
|
|
| `FIRST_SUPERUSER` | unset | initial administrator email; the CLI creates an account if needed |
|
|
| `FIRST_SUPERUSER_PASSWORD` | unset | initial password; the CLI generates and prints one if needed |
|
|
| `DOMAIN` | `localhost` | API hostname and OAuth issuer; Docker also uses it for routing |
|
|
| `FRONTEND_HOST` | `http://localhost:5173` | interface URL for links and metadata |
|
|
| `BACKEND_CORS_ORIGINS` | `[]` | allowed origins, as comma-separated URLs or a JSON list; `FRONTEND_HOST` is also allowed |
|
|
| `FORWARDED_ALLOW_IPS` | `127.0.0.1` | trusted proxies; Docker adds `172.16.0.0/12` |
|
|
| `SIGNUP_ENABLED` | `false` | allows account creation from the login page; otherwise use **Admin → Users** |
|
|
|
|
!!! warning "Keep your secret key"
|
|
|
|
Changing `SECRET_KEY` signs everyone out and makes existing encrypted
|
|
secrets unreadable. Back it up with your data.
|
|
|
|
## Interface API address
|
|
|
|
`VITE_API_URL` is a frontend **build argument**, so changing it requires
|
|
rebuilding the frontend image.
|
|
|
|
| Setup | Value |
|
|
|---|---|
|
|
| Production Docker | set `.env` to `https://api.<your-domain>` |
|
|
| `make dev-local` | overlay sets `http://api.localhost` by default |
|
|
| `make dev-lan` | overlay sets an empty value, using `/api` on the page's own origin |
|
|
|
|
Without an explicit value, the production Compose file falls back to
|
|
`https://api.${DOMAIN}`. Set `FRONTEND_HOST` and `BACKEND_CORS_ORIGINS` to
|
|
match your deployment as well; `make init` generates secrets, not deployment
|
|
URLs.
|
|
|
|
The LAN overlay also configures nginx to proxy `/api` and WebSocket requests
|
|
to the backend. An empty value needs that proxy when the frontend and backend
|
|
are served separately. See [facility automation](../getting-started/facility-automation.md#run-it-long-term)
|
|
for deployment settings.
|
|
|
|
## Environment
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `ENVIRONMENT` | `local` | `local`, `staging` or `production` |
|
|
| `PRIVATE_API_ENABLED` | `false` | test endpoints; also requires `ENVIRONMENT=local` |
|
|
| `API_DOCS_ENABLED` | `false` | opens `/docs`, `/redoc` and `/api/v1/openapi.json` to network callers outside production |
|
|
| `TZ` | host timezone; Docker defaults to `UTC` | timezone used by cron schedules |
|
|
|
|
API documentation is available to loopback callers outside production.
|
|
`API_DOCS_ENABLED=true` opens it to other callers, as the Docker development
|
|
stack does. Production disables it entirely. Staging and production also
|
|
refuse `changethis` values for the session key or administrator password.
|
|
|
|
Set `TZ` in `.env` for schedules that should follow local time, such as
|
|
`Europe/Berlin`.
|
|
|
|
## Engine and resources
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `FLOW_MAX_WORKERS` | `4` | local node-code subprocesses |
|
|
| `FLOW_MAX_CASCADES` | `4` | concurrent live message cascades |
|
|
| `FLOW_MAX_RUNS` | `4` | concurrent batch runs |
|
|
| `FLOW_NODE_TIMEOUT` | `0` | maximum node silence in seconds, unless the node overrides it; `0` disables |
|
|
| `FLOW_CPUS` | `0` | CPU budget; `0` detects cores and reserves two for the engine |
|
|
| `FLOW_GPUS` | `0` | local GPU count; `0` detects NVIDIA device nodes |
|
|
| `FLOW_RAM` | `0` | memory budget in MB; `0` detects host/container memory and reserves 1 GiB |
|
|
| `FLOW_WORKER_MAX_RSS_MB` | `0` | retire a local worker above this memory use after a call; `0` disables |
|
|
| `OBS_RETENTION_DAYS` | `30` | retention for metrics, events and run records |
|
|
|
|
The three concurrency limits must be at least `1`. They also have CLI flags:
|
|
`--max-workers`, `--max-cascades` and `--max-runs`. Resource flags are `--gpus`,
|
|
`--ram` and `--worker-max-rss`.
|
|
|
|
Nodes with declared resources are scheduled against the available budget.
|
|
Undeclared nodes use the shared pool and receive thread caps. Attached workers
|
|
report their own inventory; the engine's resource settings describe only its
|
|
own machine. See [Remote workers](../code/workers.md) and the **Workers** screen.
|
|
|
|
## Artifacts
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `MAX_ARTIFACT_BYTES` | `2147483648` (2 GiB) | upload limit; `0` removes it |
|
|
| `ARTIFACT_GC_INTERVAL_S` | `3600` | cleanup interval; `0` disables |
|
|
| `ARTIFACT_GC_GRACE_S` | `3600` | minimum age before cleanup |
|
|
| `ARTIFACT_VOLATILE_DIR` | auto-detected | live-media directory under `/dev/shm`, or the temporary directory |
|
|
| `ARTIFACT_VOLATILE_BYTES` | `50331648` (48 MiB) | live-media ring size; `0` stores volatile saves durably |
|
|
|
|
Cleanup removes durable artifacts no longer referenced by recorded runs or
|
|
current messages, and pauses while a run is active. Volatile artifacts use a
|
|
bounded ring; the oldest disappear as it fills. Recorded run outputs are
|
|
copied into durable storage. If you increase the ring size in Docker, increase
|
|
`shm_size` too.
|
|
|
|
## Agents
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `MCP_ENABLED` | `false` | enables `/mcp` and OAuth client registration; `.env.example` sets it to `true` |
|
|
| `MCP_TOKEN_EXPIRE_MINUTES` | `60` | access-token lifetime |
|
|
| `MCP_REFRESH_EXPIRE_DAYS` | `30` | refresh-token lifetime |
|
|
| `OAUTH_CODE_EXPIRE_SECONDS` | `60` | authorization-code lifetime |
|
|
|
|
See [Agents over MCP](../code/agents.md).
|
|
|
|
## Mail and monitoring
|
|
|
|
Password-reset mail requires `SMTP_HOST` and `EMAILS_FROM_EMAIL`.
|
|
|
|
| Variable | Default |
|
|
|---|---|
|
|
| `SMTP_HOST` | unset |
|
|
| `SMTP_PORT` | `587` |
|
|
| `SMTP_USER` / `SMTP_PASSWORD` | unset |
|
|
| `SMTP_TLS` / `SMTP_SSL` | `true` / `false` |
|
|
| `EMAILS_FROM_EMAIL` | unset |
|
|
| `EMAILS_FROM_NAME` | `PROJECT_NAME`, normally `Fluksio` |
|
|
| `EMAIL_RESET_TOKEN_EXPIRE_HOURS` | `48` |
|
|
| `SENTRY_DSN` | unset; enables error reporting when configured |
|
|
|
|
`GET /api/v1/utils/health/` checks the event loop and state backend. Docker
|
|
uses it as a health check; `make up` also starts the autoheal service to restart
|
|
an unhealthy backend.
|