J3vb/OwnCord
1
0
Fork 0
mirror of https://github.com/J3vb/OwnCord.git synced 2026-09-03 03:50:00 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
OwnCord/docs/server-configuration.md
T
J3vbandClaude Fable 5 8cb0ec9e35 feat(b3-6): contract drift — generated route, table and config-key indexes with a CI drift check (#1456) 
* feat(b3-6): contract drift — generated route, table and config-key indexes

B3-6 item 9 (workstream 10). `check:server` already diffs the two
generators; this adds a third for the three server contracts that only
prose described until now.

`Server/cmd/gendocs` rewrites one marked block per document:

- `docs/api.md` "Route index (generated)" — 111 rows from `chi.Walk` over
  the production router built with uploads, voice and the GIF proxy on,
  the same scaffolding `api/absence_contract_test.go` uses. Carries that
  test's vacuity guards: fewer than 100 routes, or no `/admin/` route,
  fails the run.
- `docs/schema.md` "Table index (generated)" — 34 rows from `sqlite_master`
  and `pragma_table_info` on an in-memory database with the migrations
  applied. sqlc exposes no catalog, so the migrated schema is the catalog.
- `docs/server-configuration.md` "Key index (generated)" — 56 keys from the
  koanf struct tags, each mapped to the `###` section of the hand-written
  reference that names it. A key documented nowhere fails the run by name.

Output is padded exactly the way Prettier formats a table, so the drift
check and the hygiene gate agree instead of undoing each other.

Wiring, copied from protocol-verify: `make docs-generate` / `make
docs-verify`, a `DOCS_VERIFY` step in `check:server` and the generator in
`generate` (`scripts/run.mjs`), a CI step on the ubuntu leg of
`server-build-test`, and a `.githooks/pre-commit` block on router, handler,
migration, config and generator paths.

Everything hand-written in the three documents is untouched. The new
`cmd/gendocs` file imports `db` for the catalog, so it takes a boundary row
in the B3-0 inventory and `server-boundaries.md` is regenerated with it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KmiqjgTuov1stBTB6uGkvo

* docs(b3-6): evidence block for item 9 (machine-readable contract drift)

Records the three RED controls and their restore, the counts (111 routes,
34 tables, 56 config keys, 0 undocumented), and two corrections to the item's
spec: the configuration reference table lives in docs/server-configuration.md,
not docs/deployment.md, and sqlc exposes no catalog — the migrated in-memory
schema is the catalog.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KmiqjgTuov1stBTB6uGkvo

* fix(b3-6): gendocs — exclude ANALYZE artifacts, honest hook message, admin routes trigger the hook, generate order, width ceiling

Review findings on item 9.

1. The table index dropped `sqlite_stat1` / `sqlite_stat4`. `db.Migrate` runs
   ANALYZE after applying migrations, so those hold planner statistics, not
   schema — and `sqlite_stat4` exists only because the current
   modernc.org/sqlite build has STAT4, so a driver bump would have failed the
   docs drift check on an unrelated dependency PR. Filtered with GLOB (LIKE's
   `_` is a wildcard), block regenerated, header line's justification
   corrected: 34 -> 32 tables.
2. The pre-commit message now covers both failure modes — stale blocks are
   regenerated and staged, a key the tool named as undocumented is documented
   in docs/server-configuration.md.
3. `Server/admin/.*\.go` added to the hook's trigger: the 34 `/admin/api/*`
   routes are registered there, not in api/router.go, so a new admin route
   could commit stale docs locally.
4. `run.mjs` `generate` runs gendocs after `sqlc generate` — gendocs compiles
   the api package, which imports db/dbgen.
5. The vacuity guard now requires a traversed `/admin/api/` subroute rather
   than any `/admin/` path, which the per-method mount catch-alls satisfied on
   their own, so its message is true. `writeTable` gained a comment naming its
   ceiling: padding counts runes, Prettier counts display width, so a
   full-width cell would diverge — none exists in the generated content.

Evidence block updated for the new table count.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KmiqjgTuov1stBTB6uGkvo

* fix(b3-6): gendocs — generate the route index from the full-tag build with telemetry on; the hook triggers on every api/ and admin/ Go file (Codex P2s on #1456)

1. `/metrics` was missing from the route index. It mounts only when
   `telemetry.PrometheusHandler()` returns non-nil (api/router.go:431-437),
   which needs the otel build tag AND telemetry enabled at runtime; the
   generator ran in the default build with telemetry unset, so the index
   omitted a production route.

   The route index is now the superset build. The scaffold config enables
   telemetry with the Prometheus exporter and the tool calls telemetry.Init
   the way main.go does, and every invocation passes -tags otel,wazero:
   Makefile docs-generate/docs-verify, scripts/run.mjs (DOCS_VERIFY and
   generate), .githooks/pre-commit, the regenCmd quoted into all three block
   header lines, and the CLAUDE.md row. ci.yml inherits it through
   `make docs-verify`. The route block's header line now says which build it
   came from and what is enabled.

   Rather than a build-tag constant, the tool checks the condition that
   actually gates the route: if telemetry.Init leaves no Prometheus handler
   it exits non-zero naming the tags, so the default build cannot quietly
   generate a short index.

   Nothing under Server/api or Server/admin carries a build constraint, so
   wazero adds and removes no route; it rides along so one build serves the
   whole repository. Route count 111 -> 121 (ten per-method rows for the
   /metrics mount, the same shape chi gives /admin and /livekit).

2. The pre-commit trigger named individual api/ files and missed
   client_update.go, whose MountClientUpdateRoute registers a route directly.
   It is now the whole of Server/api/ and Server/admin/ — naming files
   individually is how a trigger goes stale — plus the existing migrations/,
   config/config.go and cmd/gendocs/ patterns.

Evidence block updated: route count and the tagged-build decision.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KmiqjgTuov1stBTB6uGkvo

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-30 14:18:54 +00:00

373 lines
36 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Server Configuration Reference
Complete reference for all OwnCord server configuration options.
## Overview
OwnCord server reads configuration from `config.yaml` in the working directory. On first run, if the file does not exist, a default `config.yaml` is created automatically.
Configuration is loaded in three layers (later layers override earlier ones):
1. **Built-in defaults** (compiled into the binary)
2. **YAML file** (`config.yaml`)
3. **Environment variables** (prefix: `OWNCORD_`)
### First-run setup wizard
The admin panel's first-time setup wizard (shown at `/admin` until the Owner
account exists) writes a subset of these keys into `config.yaml` for you:
`server.port`, `server.name`, `tls.mode`, `tls.domain`, `upload.max_size_mb`,
`voice.quality` and `voice.auto_download_livekit`. It also persists the auto-generated
`voice.livekit_api_key` / `voice.livekit_api_secret` (only when the file has
none) so voice tokens survive restarts. The wizard patches the file in place —
comments and hand-edited values it doesn't manage are preserved — and restarts
the server automatically when a startup-only value changed. Note that
`OWNCORD_*` environment variables still override anything the wizard writes.
## Config Key Reference
### Server (`server`)
| Key | Type | Default | Description |
| -------------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.port` | int | `8443` | HTTP(S) listen port |
| `server.name` | string | `"OwnCord Server"` | Server display name (shown in `/api/v1/info` and admin panel) |
| `server.data_dir` | string | `"data"` | Directory for database, certs, uploads, backups |
| `server.max_ws_connections` | int | `0` | Cap on concurrently connected WebSocket clients; further upgrades get 503 until connections free up. `0` = unlimited. Every connection costs goroutines and buffered send queues — set a ceiling that matches the host's memory before opening the server to a large community. |
| `server.metrics_allowed_cidrs` | []string | `[]` | Separate allowlist for `/api/v1/metrics` and the Prometheus `/metrics` exporter, so a central scraper can be admitted without widening `/admin` to its network. Empty = falls back to `admin_allowed_cidrs`. |
| `server.livekit_webhook_allowed_cidrs` | []string | `[]` | Separate allowlist for the LiveKit webhook/health endpoints (which also authenticate cryptographically) — an externally-hosted LiveKit's IP goes here, not in the admin allowlist. Empty = falls back to `admin_allowed_cidrs`. |
| `server.allowed_origins` | string[] | `[]` | WebSocket CORS allowed origins for **web/browser** clients; empty list DENIES all cross-origin (set to `["*"]` to allow any origin). The OwnCord desktop client needs no entry here — its webview origins (`http(s)://tauri.localhost`, `tauri://localhost`) are always accepted. |
| `server.trusted_proxies` | string[] | `[]` | CIDRs of trusted reverse proxies (for X-Forwarded-For) |
| `server.admin_allowed_cidrs` | string[] | private networks | CIDRs allowed to access `/admin` routes. Default: `127.0.0.0/8`, `::1/128`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` |
| `server.waf_enabled` | bool | `false` | Enable the Coraza WAF middleware (inline rules + OWASP Core Rule Set) |
| `server.waf_paranoia_level` | int | `2` | OWASP CRS paranoia level 1–4; values outside that range fall back to 2 |
| `server.waf_crs_mode` | string | `"detect"` | CRS layer mode: `off` (inline rules only), `detect` (matches logged, never blocks), `block` (anomaly-scoring blocking). Unknown values fall back to `detect`. |
| `server.restart_mode` | string | `"auto"` | How self-restarts (update apply, backup restore, setup wizard) hand off after the server drains: `supervised` exits cleanly and relies on systemd/NSSM/Docker to relaunch; `spawn` starts the replacement binary directly; `auto` picks `supervised` when a supervisor or container is detected, else `spawn`. NSSM deployments must set `supervised` explicitly (see [Deployment](deployment.md)). |
### TLS (`tls`)
| Key | Type | Default | Description |
| -------------------- | ------ | ------------------- | ------------------------------------------------------------ |
| `tls.mode` | string | `"self_signed"` | TLS mode: `self_signed`, `acme`, `manual`, `off` |
| `tls.cert_file` | string | `"data/cert.pem"` | Path to TLS certificate (used by `manual` and `self_signed`) |
| `tls.key_file` | string | `"data/key.pem"` | Path to TLS private key |
| `tls.domain` | string | `""` | Domain for ACME/Let's Encrypt (required when `mode: acme`) |
| `tls.acme_cache_dir` | string | `"data/acme_certs"` | Directory for cached Let's Encrypt certificates |
### Database (`database`)
| Key | Type | Default | Description |
| ---------------------- | ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database.type` | string | `"sqlite"` | Database backend. `sqlite` (or empty) is the only supported value — any other value makes the server refuse to start. |
| `database.path` | string | `"data/chatserver.db"` | Path to SQLite database file |
| `database.max_readers` | int | `0` | Bound on the read-only connection pool. `0` = automatic (`max(4, CPU count)`); clamped to 1–64. Readers beyond the CPU count mostly buy queueing, not throughput. |
### Backups (`backup`)
| Key | Type | Default | Description |
| ------------ | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `backup.dir` | string | `"data/backups"` | Directory where database backups are written and pruned. Point it at another disk or an off-host mount so backups don't share a single point of failure with the live database. The admin panel's Backup Schedule and Retention settings operate on this directory. |
### Security (`security`)
| Key | Type | Default | Description |
| ------------------------------------- | ----- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `security.auth_rate_limit_multiplier` | float | `1.0` | Scales the per-IP auth rate limits and failure thresholds (registration, login, TOTP, sensitive endpoints). The defaults assume roughly one person per IP; raise this for communities behind a shared NAT (office, school). Clamped to 0.1–100. |
### Uploads (`upload`)
| Key | Type | Default | Description |
| -------------------- | ------ | ---------------- | ----------------------------------------- |
| `upload.max_size_mb` | int | `100` | Maximum file upload size in megabytes |
| `upload.storage_dir` | string | `"data/uploads"` | Directory where uploaded files are stored |
### Voice / LiveKit (`voice`)
| Key | Type | Default | Description |
| ----------------------------- | ------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `voice.livekit_api_key` | string | _(random per run)_ | LiveKit API key. Set a stable value for persistent voice tokens. |
| `voice.livekit_api_secret` | string | _(random per run)_ | LiveKit API secret (min 32 chars). Set a stable value for persistent tokens. |
| `voice.livekit_url` | string | `"ws://localhost:7880"` | LiveKit server WebSocket URL |
| `voice.livekit_binary` | string | `""` | Path to an existing `livekit-server` binary; set to skip auto-download and run your own build |
| `voice.auto_download_livekit` | bool | `false` (compiled) / `true` in the generated config | When no `livekit_binary` is set, download a pinned `livekit-server` release from the official LiveKit GitHub releases (verified against the release `checksums.txt`) into `data/livekit/` and run it automatically |
| `voice.livekit_version` | string | `""` | Override the pinned `livekit-server` version used by auto-download (e.g. `"1.13.5"`); empty = built-in pin |
| `voice.node_ip` | string | `""` | Public IP for WebRTC ICE candidates; empty = auto-detect. Required for remote users behind NAT. |
| `voice.advertise_internal_ip` | bool | `false` | Also advertise internal (LAN) IPs as ICE candidates. Enable when the server is reachable via both a LAN IP and a public IP so local-network clients can connect to voice. |
| `voice.quality` | string | `"medium"` | Voice quality preset: `low`, `medium`, `high` |
> **Warning:** If `livekit_api_key` or `livekit_api_secret` are left empty, random credentials are generated on each startup. This means voice tokens break on restart. Always set stable credentials in production. See [LiveKit Setup](livekit-setup.md) for details.
#### Server with both a LAN and a public IP
If your server is dual-homed (e.g. `192.168.1.10` on the LAN and `47.x.x.x` public), set `voice.node_ip` to the public IP **and** `voice.advertise_internal_ip: true`. LiveKit then advertises the LAN address in addition to the public one, so clients on the local network connect directly while remote clients use the public IP.
For LiveKit options OwnCord does not model, you can take ownership of the auto-started server's config: edit `data/livekit.yaml` and delete the header line containing the auto-generated marker — OwnCord will stop regenerating the file on startup (your `keys:` entry must still match `voice.livekit_api_key` / `voice.livekit_api_secret`).
### GitHub / Updates (`github`)
| Key | Type | Default | Description |
| -------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `github.token` | string | `""` | Optional GitHub API token for higher rate limits on update checks (5000 req/hr vs 60) |
| `github.owner` | string | `"J3vb"` | Owner of the GitHub repository server and client updates are fetched from |
| `github.repo` | string | `"OwnCord"` | Repository whose releases carry update assets. Must stay publicly readable — both the server self-update and the client auto-update chain fetch release assets from it |
### Event Persistence (`event_persistence`)
Controls the tiered event log used for WebSocket reconnection replay. When enabled, missed events are stored in the database so clients that reconnect after the in-memory ring buffer window (`replay_ring_size` events) can still replay missed events from the DB tier.
| Key | Type | Default | Description |
| ------------------------------------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_persistence.enabled` | bool | `true` | Enable cold-storage event persistence. When `false`, only the in-memory ring buffer is used (lower durability). |
| `event_persistence.retention_hours` | int | `24` | How long persisted events are kept before the pruner deletes them |
| `event_persistence.batch_size` | int | `50` | Maximum events per database flush |
| `event_persistence.batch_flush_ms` | int | `100` | Maximum delay between flushes (milliseconds) |
| `event_persistence.pruner_interval_minutes` | int | `60` | How often the pruner goroutine wakes up to delete expired events |
| `event_persistence.replay_ring_size` | int | `1000` | Capacity of the in-memory reconnect replay ring. Larger rings bridge longer disconnects without touching the database, at ~1 message payload of memory per slot. |
| `event_persistence.replay_cold_limit` | int | `5000` | Maximum persisted events a single reconnect may replay; a larger gap falls back to a full resync. Watch the `reconnect_tier_full` metric before raising it. |
### Telemetry / OpenTelemetry (`telemetry`)
Controls the OpenTelemetry SDK. Requires building with `-tags otel` (see [Contributing](contributing.md)). When disabled, the server uses no-op tracer/meter providers; the legacy JSON `/api/v1/metrics` endpoint exists regardless of this setting (it is admin-IP-restricted, like all metrics surfaces).
| Key | Type | Default | Description |
| ------------------------- | ------ | ------------------ | ------------------------------------------------------------------------------------------------------- |
| `telemetry.enabled` | bool | `false` | Enable the OTel SDK |
| `telemetry.exporter` | string | `"none"` | Exporter backend: `none`, `prometheus`, `otlp` |
| `telemetry.otlp_endpoint` | string | `""` | gRPC endpoint for the OTLP exporter (e.g. `localhost:4317`). Only used when `exporter: otlp`. |
| `telemetry.otlp_insecure` | bool | `false` | Disable TLS for the OTLP gRPC connection. Only set `true` in development / private-network deployments. |
| `telemetry.service_name` | string | `"owncord-server"` | OTel `service.name` resource attribute |
> **Local development:** Run `make otel-up` (from `Server/`) to start Jaeger + Prometheus via Docker.
> Jaeger UI: `http://localhost:16686` — Prometheus UI: `http://localhost:9090`
### Plugins (`plugins`)
Controls the Wazero WASM plugin runtime. Requires building with `-tags wazero`. When disabled, no plugins are loaded; plugin admin lifecycle endpoints return `503 Service Unavailable` and the plugin list endpoint returns an empty list.
| Key | Type | Default | Description |
| ------------------------ | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `plugins.enabled` | bool | `false` | Enable plugin loading at startup |
| `plugins.directory` | string | `"data/plugins"` | Directory scanned for plugin packages on startup |
| `plugins.max_memory_mb` | int | `64` | Maximum WASM linear memory per plugin (megabytes) |
| `plugins.cpu_budget_ms` | int | `100` | Maximum CPU time per plugin invocation (milliseconds) |
| `plugins.http_allowlist` | string[] | `[]` | Host suffixes plugins may reach via the `host_http` capability (e.g. `["api.steampowered.com"]`). Empty = no outbound HTTP. |
### GIF Picker (`gif`)
Powers the client's GIF picker. The server proxies the Klipy API so the key
never ships in the desktop bundle — the client only ever calls
`/api/v1/gif/*` on its own server.
**Disabled by default.** With no `gif.api_key` set, `/api/v1/gif/*` returns
`503 GIF_DISABLED` and clients hide their GIF button. Nothing else changes.
| Key | Type | Default | Description |
| ------------- | ------ | ------- | ---------------------------------------------------------------------------------------------- |
| `gif.api_key` | string | `""` | Klipy API key. Get one at [partner.klipy.com](https://partner.klipy.com). Empty = feature off. |
> **Treat this as a credential.** Prefer `OWNCORD_GIF_API_KEY` (or a secrets
> manager) over writing it into `config.yaml`, and rotate it if it has ever
> been exposed to a client build.
### Logging (`logging`)
Controls server log verbosity. The level gates both stdout and the in-memory
ring buffer that backs the admin panel's live log view.
| Key | Type | Default | Description |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `logging.level` | string | `"info"` | Minimum level logged: `debug`, `info`, `warn`, `error`. Empty = `info`; an unrecognised value falls back to `info` with a startup warning. |
## Key index (generated)
<!-- gendocs:config:start -->
Generated from the `koanf` tags of `config.Config` by `cd Server && go run -tags otel,wazero ./cmd/gendocs` — do not edit by hand; `make docs-verify` fails when it drifts, and the tool exits non-zero when a key is documented nowhere above. 56 keys.
| Key | Documented in |
| ------------------------------------------- | --------------------------------------- |
| `backup.dir` | Backups (`backup`) |
| `database.max_readers` | Database (`database`) |
| `database.path` | Database (`database`) |
| `database.type` | Database (`database`) |
| `event_persistence.batch_flush_ms` | Event Persistence (`event_persistence`) |
| `event_persistence.batch_size` | Event Persistence (`event_persistence`) |
| `event_persistence.enabled` | Event Persistence (`event_persistence`) |
| `event_persistence.pruner_interval_minutes` | Event Persistence (`event_persistence`) |
| `event_persistence.replay_cold_limit` | Event Persistence (`event_persistence`) |
| `event_persistence.replay_ring_size` | Event Persistence (`event_persistence`) |
| `event_persistence.retention_hours` | Event Persistence (`event_persistence`) |
| `gif.api_key` | GIF Picker (`gif`) |
| `github.owner` | GitHub / Updates (`github`) |
| `github.repo` | GitHub / Updates (`github`) |
| `github.token` | GitHub / Updates (`github`) |
| `logging.level` | Logging (`logging`) |
| `plugins.cpu_budget_ms` | Plugins (`plugins`) |
| `plugins.directory` | Plugins (`plugins`) |
| `plugins.enabled` | Plugins (`plugins`) |
| `plugins.http_allowlist` | Plugins (`plugins`) |
| `plugins.max_memory_mb` | Plugins (`plugins`) |
| `security.auth_rate_limit_multiplier` | Security (`security`) |
| `server.admin_allowed_cidrs` | Server (`server`) |
| `server.allowed_origins` | Server (`server`) |
| `server.data_dir` | Server (`server`) |
| `server.livekit_webhook_allowed_cidrs` | Server (`server`) |
| `server.max_ws_connections` | Server (`server`) |
| `server.metrics_allowed_cidrs` | Server (`server`) |
| `server.name` | Server (`server`) |
| `server.port` | Server (`server`) |
| `server.restart_mode` | Server (`server`) |
| `server.trusted_proxies` | Server (`server`) |
| `server.waf_crs_mode` | Server (`server`) |
| `server.waf_enabled` | Server (`server`) |
| `server.waf_paranoia_level` | Server (`server`) |
| `telemetry.enabled` | Telemetry / OpenTelemetry (`telemetry`) |
| `telemetry.exporter` | Telemetry / OpenTelemetry (`telemetry`) |
| `telemetry.otlp_endpoint` | Telemetry / OpenTelemetry (`telemetry`) |
| `telemetry.otlp_insecure` | Telemetry / OpenTelemetry (`telemetry`) |
| `telemetry.service_name` | Telemetry / OpenTelemetry (`telemetry`) |
| `tls.acme_cache_dir` | TLS (`tls`) |
| `tls.cert_file` | TLS (`tls`) |
| `tls.domain` | TLS (`tls`) |
| `tls.key_file` | TLS (`tls`) |
| `tls.mode` | TLS (`tls`) |
| `upload.max_size_mb` | Uploads (`upload`) |
| `upload.storage_dir` | Uploads (`upload`) |
| `voice.advertise_internal_ip` | Voice / LiveKit (`voice`) |
| `voice.auto_download_livekit` | Voice / LiveKit (`voice`) |
| `voice.livekit_api_key` | Voice / LiveKit (`voice`) |
| `voice.livekit_api_secret` | Voice / LiveKit (`voice`) |
| `voice.livekit_binary` | Voice / LiveKit (`voice`) |
| `voice.livekit_url` | Voice / LiveKit (`voice`) |
| `voice.livekit_version` | Voice / LiveKit (`voice`) |
| `voice.node_ip` | Voice / LiveKit (`voice`) |
| `voice.quality` | Voice / LiveKit (`voice`) |
<!-- gendocs:config:end -->
## Environment Variable Overrides
Every config key can be overridden via environment variables using the prefix `OWNCORD_`.
**Format:** `OWNCORD_<SECTION>_<KEY>` — the first `_` after the prefix maps to
the section/key dot; the scheme covers **every** key in the file, including ones
absent from the table below (it is a representative subset, not the full list).
| Environment Variable | Config Path |
| ------------------------------------------- | ----------------------------------- |
| `OWNCORD_SERVER_PORT` | `server.port` |
| `OWNCORD_SERVER_NAME` | `server.name` |
| `OWNCORD_SERVER_DATA_DIR` | `server.data_dir` |
| `OWNCORD_SERVER_RESTART_MODE` | `server.restart_mode` |
| `OWNCORD_DATABASE_PATH` | `database.path` |
| `OWNCORD_TLS_MODE` | `tls.mode` |
| `OWNCORD_TLS_CERT_FILE` | `tls.cert_file` |
| `OWNCORD_TLS_DOMAIN` | `tls.domain` |
| `OWNCORD_UPLOAD_MAX_SIZE_MB` | `upload.max_size_mb` |
| `OWNCORD_UPLOAD_STORAGE_DIR` | `upload.storage_dir` |
| `OWNCORD_VOICE_LIVEKIT_API_KEY` | `voice.livekit_api_key` |
| `OWNCORD_VOICE_LIVEKIT_API_SECRET` | `voice.livekit_api_secret` |
| `OWNCORD_VOICE_LIVEKIT_URL` | `voice.livekit_url` |
| `OWNCORD_VOICE_NODE_IP` | `voice.node_ip` |
| `OWNCORD_VOICE_ADVERTISE_INTERNAL_IP` | `voice.advertise_internal_ip` |
| `OWNCORD_VOICE_QUALITY` | `voice.quality` |
| `OWNCORD_GITHUB_TOKEN` | `github.token` |
| `OWNCORD_EVENT_PERSISTENCE_ENABLED` | `event_persistence.enabled` |
| `OWNCORD_EVENT_PERSISTENCE_RETENTION_HOURS` | `event_persistence.retention_hours` |
| `OWNCORD_TELEMETRY_ENABLED` | `telemetry.enabled` |
| `OWNCORD_TELEMETRY_EXPORTER` | `telemetry.exporter` |
| `OWNCORD_TELEMETRY_OTLP_ENDPOINT` | `telemetry.otlp_endpoint` |
| `OWNCORD_TELEMETRY_SERVICE_NAME` | `telemetry.service_name` |
| `OWNCORD_PLUGINS_ENABLED` | `plugins.enabled` |
| `OWNCORD_PLUGINS_DIRECTORY` | `plugins.directory` |
| `OWNCORD_GIF_API_KEY` | `gif.api_key` |
| `OWNCORD_SERVER_WAF_ENABLED` | `server.waf_enabled` |
| `OWNCORD_DATABASE_TYPE` | `database.type` |
| `OWNCORD_TELEMETRY_OTLP_INSECURE` | `telemetry.otlp_insecure` |
| `OWNCORD_LOGGING_LEVEL` | `logging.level` |
## Example config.yaml
```yaml
# OwnCord Server Configuration
server:
port: 8443
name: "OwnCord Server"
data_dir: "data"
allowed_origins: [] # empty = deny all cross-origin; set to ["*"] to allow any
trusted_proxies: [] # e.g. ["10.0.0.0/8"] if behind a reverse proxy
admin_allowed_cidrs:
- "127.0.0.0/8"
- "::1/128"
- "10.0.0.0/8"
- "172.16.0.0/12"
- "192.168.0.0/16"
database:
path: "data/chatserver.db"
tls:
mode: "self_signed" # self_signed | acme | manual | off
cert_file: "data/cert.pem"
key_file: "data/key.pem"
domain: "" # required for acme mode
acme_cache_dir: "data/acme_certs"
upload:
max_size_mb: 100
storage_dir: "data/uploads"
voice:
livekit_api_key: "your-api-key"
livekit_api_secret: "your-secret-at-least-32-characters-long"
livekit_url: "ws://localhost:7880"
livekit_binary: "" # path to livekit-server binary
node_ip: "" # public IP for remote users behind NAT
advertise_internal_ip: false # also advertise LAN IPs (dual-homed servers)
quality: "medium" # low | medium | high
github:
token: "" # optional GitHub PAT for update check rate limits
owner: "J3vb" # update source repo owner
repo: "OwnCord" # repo holding release assets (binaries + source snapshots)
# Event persistence (tiered reconnect replay)
event_persistence:
enabled: true
retention_hours: 24
batch_size: 50
batch_flush_ms: 100
pruner_interval_minutes: 60
# OpenTelemetry (requires build tag: -tags otel)
telemetry:
enabled: false
exporter: "none" # none | prometheus | otlp
otlp_endpoint: "" # e.g. "localhost:4317" for OTLP gRPC
service_name: "owncord-server"
# Plugin runtime (requires build tag: -tags wazero)
plugins:
enabled: false
directory: "data/plugins"
max_memory_mb: 64
cpu_budget_ms: 100
http_allowlist: [] # host suffixes plugins may reach, e.g. ["api.steampowered.com"]
# GIF picker (server-side Klipy proxy). Empty key = feature off.
# Prefer OWNCORD_GIF_API_KEY over storing the key in this file.
gif:
api_key: ""
# Logging. "level" gates what is logged, to stdout and the admin panel's live
# log view alike. Override without editing this file via OWNCORD_LOGGING_LEVEL.
logging:
level: "info" # debug | info | warn | error
```
## See Also
- [Deployment Guide](deployment.md) -- production deployment guide
- [LiveKit Setup](livekit-setup.md) -- voice/video setup
- [Quick Start](quick-start.md) -- getting started
Reference in New Issue View Git Blame Copy Permalink