mirror of
https://github.com/J3vb/OwnCord.git
synced 2026-09-03 03:50:00 +03:00
J3vbandClaude Opus 5
2a37f386f9
* chore(format): one Prettier config at the repository root Every formatting rule in this repository lived under Client/ and covered exactly two globs: Client/src/**/*.ts and Client/tests/**/*.ts. Root Markdown, all of docs/, every YAML and JSON, all CSS, the root scripts and tools/mcp-introspect were formatted by nothing. There was no .editorconfig. The obvious fix -- a second Prettier config at the root for "everything else" -- gives two configs and two ignore files that can silently disagree about the same file. So the root takes ownership instead: config, ignore file and gate move up, and Client/ folds in. Client's inline "prettier" block, its .prettierignore, its format/format:check scripts and its now-unused prettier devDependency are all deleted; knip would have failed client-check on that last one. The .prettierrc.json values are lifted byte-for-byte from Client/package.json, which is what keeps the reformat commit free of client TypeScript churn: 87 tracked files need reformatting and not one of them is under Client/src or Client/tests. .prettierignore carries only what .gitignore does not. Prettier 3 reads the root .gitignore by default, so node_modules/, dist/, coverage/, Client/src/generated/ and docs/security-findings/ need no entry. It does NOT read nested .gitignore files, which is why .remember/ is listed explicitly -- 38 untracked per-machine scratch files were otherwise able to turn a shared gate red. graphify-out/ is listed because its seven files are tracked and .graphify_labels.json is signed byte-for-byte by its .sig, so formatting it would silently invalidate the signature. check:hygiene is registered in scripts/run.mjs and folded into check and release:preflight. It deliberately contains no `gofmt -l` step: gofmt -l prints offenders and still exits 0, so it cannot fail a build. Go formatting is enforced separately. shellcheck and actionlint take their file lists from `git ls-files`, never a filesystem glob -- .claude/worktrees/ holds a gitignored pre-flatten copy of the tree with three .sh files a glob would happily lint. This commit leaves the tree non-conformant on purpose. The reformat is the next commit, so the 87-file diff is reviewable separately from the rule that caused it. Not included: editorconfig-checker. .editorconfig is the editor baseline the audit asked for; Prettier, gofmt and rustfmt already fail CI on the same indentation and newline rules, so a fourth tool checking them again is a gate with no failure mode of its own. Verified: `npx prettier --check .` names 87 tracked files and zero untracked ones; the same command listed 38 .remember/ scratch files before the ignore entry and none after. `node scripts/run.mjs --list` resolves check:hygiene to 8 shell targets and 4 workflow targets. Both package.json files parse. Refs RL-19 / L-13, S-05. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(format): reformat the tree to the repository Prettier rules Mechanical. This commit is `npx prettier --write .` and nothing else -- the rule that caused it landed in the previous commit so this diff can be reviewed as a transformation rather than as 84 files of hunks. 84 tracked files: 54 Markdown, 7 .mjs, 7 JSON, 6 YAML, 4 .js, 3 CSS, 2 TypeScript (the two Playwright configs at Client's root, which the old Client/src + Client/tests globs never covered). No file under Client/src or Client/tests moves, because .prettierrc.json carries Client's former inline values byte-for-byte. Prettier rewrote 87 files, not 84. The three in .github/ISSUE_TEMPLATE/ had CRLF on disk and differ only in line endings, which .gitattributes (`* text=auto eol=lf`) already normalises, so their committed blobs are unchanged. Worth knowing before someone reconciles the two numbers. The largest single diff is .superpowers/findings-ledger.json at 7976 lines rewritten. That is safe to format: nothing writes the ledger programmatically -- render-ledger.mjs reads it and writes only FINDINGS.md -- so no tool will fight Prettier over its style on the next hunt. FINDINGS.md itself is ignored as generated. Verified: `npx prettier --check .` reports "All matched files use Prettier code style", so the pass is both complete and idempotent. All 7 reformatted JSON files were parsed before and after and compared as values: semantically identical, zero content changes. `node .superpowers/render-ledger.mjs --check` still reports 348 valid findings and leaves FINDINGS.md untouched. `node scripts/check-doc-counts.mjs` still passes its selftest and still agrees on 27 claims across 9 watched documents -- table realignment did not break the patterns it matches on. `node scripts/run.mjs --list` still parses. Refs RL-19 / L-13, S-05. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(lint): enforce Go formatting in the Server linter S-05: repository-wide Go formatting was not a required gate. The only gofmt enforcement anywhere was .githooks/pre-commit, which is opt-in per clone (`npm run hooks:install`), only sees staged files, and warns-and-skips when gofmt is off PATH. The obvious fix -- a `gofmt -l` step in CI -- does not work: `gofmt -l` prints its offenders and still exits 0, so the step passes no matter what it finds. scripts/run.mjs has the same problem, which is why check:hygiene has no Go step either. So gofmt goes where it can actually fail something: Server/.golangci.yml. The file was already `version: "2"` but had no `formatters:` block at all, so the 19 enabled linters ran with zero formatters. In v2 gofmt/gofumpt/goimports moved out of `linters.enable` into their own section with its own exclusions. Adding it there means the gate reports through the Lint step of "Server Build & Test", which is already pinned as required on dev -- no new job and no new pin. Every tracked .go file is under Server/ (551 of them, one go.mod), so Server-scoped is repository-wide here. One file was genuinely misformatted: a one-space struct field alignment in Server/admin/handlers_users_broadcast_test.go, fixed in the same commit because a single line does not need its own reformat commit. Trap worth recording: `gofmt -l .` on a Windows working tree lists every file that has CRLF on disk, because gofmt normalises line endings. That reported 18 offenders here, 17 of them ghosts. The blobs are all LF -- .gitattributes forces `eol=lf` -- so CI never saw them, and the honest test is to run gofmt over `git show HEAD:<file>` rather than the working copy. Doing that across all 551 tracked Go files found exactly the one real offender above. Verified both directions with golangci-lint v2 locally: `golangci-lint run ./...` reports 0 issues on the formatted tree; appending a misformatted function to Server/auth/constants.go produces 2 gofmt findings; appending the same misformatted function to Server/db/dbgen/admin.sql.go produces 0, so the exclusion holds. Both files restored and verified clean afterwards. Refs RL-19 / L-13, S-05. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scripts): escape the NUL separator instead of embedding one The `tracked()` helper added earlier in this branch splits `git ls-files -z` output on NUL. The separator was written as a literal NUL byte rather than the two-character JavaScript escape, so scripts/run.mjs became a binary file: `git diff` refused to show it, `grep` reported "Binary file matches" instead of the line, and `* text=auto` in .gitattributes stops normalising line endings for a blob it detects as binary. The code worked -- splitting on a raw NUL and splitting on "\0" are the same operation -- which is exactly why this is worth fixing before it is inherited. A source file that tooling classifies as binary is a file nobody can review. Verified: zero NUL bytes remain, `grep -n "split("` now prints line 50 instead of "Binary file matches", `node scripts/run.mjs --list` still resolves the same 8 shell and 4 workflow targets, and prettier still reports the file clean. * chore(lint): enforce Rust formatting Rust had no formatting gate of any kind: no rustfmt.toml, no `cargo fmt` anywhere in CI, in scripts/run.mjs, in the Makefile or in the git hooks. Clippy was the only Rust gate, and clippy does not check layout. `cargo fmt --all -- --check` now runs in the rust-tests job, ahead of clippy: a formatting failure is cheap to produce and cheap to fix, and there is no reason to spend a clippy pass to surface one. The stable toolchain in that job requested `components: clippy` only, so rustfmt is added there. Only that job. ci.yml has a second, byte-identical `Install Rust` block in tauri-build; it stays clippy-only, because a full desktop build is the wrong place to discover a misplaced brace. No rustfmt.toml. The default profile is the point of a baseline -- a config file here would be a second opinion about style with nothing to say. Client/src-tauri is a single `[package]`, not a workspace, so `--all` is a safeguard against a future member rather than a fan-out today. Verified: `node scripts/run.mjs --list` resolves check:rust to three steps with `cargo fmt --all -- --check` first, `npm run format` now also runs `cargo fmt --all`, and prettier reports ci.yml, run.mjs and the ci-check skill clean. `cargo fmt --all -- --check` currently fails on 13 files -- that is the reformat, and it is the next commit. Refs RL-19 / L-13. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(format): reformat the Rust crate to rustfmt defaults Mechanical. This commit is `cargo fmt --all` and nothing else; the gate that demands it landed in the previous commit so this diff is reviewable on its own. 13 of the 17 tracked .rs files, +343/-164. The crate had never been formatted, so the changes are the usual first-run set: aligned trailing comments collapsed to single spaces, single-element slice literals folded onto one line, long method chains broken across lines, closure bodies expanded into blocks. Verified: `cargo fmt --all -- --check` is clean, so the pass is complete and idempotent. `cargo clippy --all-targets -- -D warnings` finishes with no warnings, and `cargo test --lib` reports 115 passed / 0 failed -- identical to before the reformat, which is what "mechanical" has to mean for a commit that touches this much of the crate. Refs RL-19 / L-13. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scripts): make the root facade actually run on Windows Adding the first gate that a contributor would run from the repository root exposed two bugs in the facade, both of which made it silently wrong on the platform this project is developed on. 1. Every npm and npx step failed. bin() appends `.cmd` on Windows, but Node refuses to spawn a .cmd or .bat with shell:false -- the CVE-2024-27980 mitigation -- and fails with EINVAL and a *null* exit status. run.mjs only special-cased ENOENT, so the result was `FAILED: npx prettier --check . exited null` with nothing to explain it. check:client has three npm steps and has never been able to run here. Fixed by spawning only the npm shims through a shell. They are concatenated into a single command string rather than passed as an args array, because shell:true plus a separate array is deprecated (DEP0190) and prints a warning on every invocation; no argument in this file contains a space. 2. Every optional() step was skipped, always. onPath() shelled out to `where` on Windows, but where.exe lives in C:\WINDOWS\System32, which a Git Bash PATH does not necessarily contain -- on this machine PATH carries System32\Wbem, System32\WindowsPowerShell\v1.0 and System32\OpenSSH but not System32 itself. The probe could not start, `probe.status === 0` was false, and golangci-lint and sqlc reported as "not installed" while installed. Fixed by resolving against PATH and PATHEXT directly. No subprocess, and no dependency on which directories happen to be on PATH. A spawn error other than ENOENT now reports its code instead of surfacing as a null exit status. Verified: before, `node scripts/run.mjs check:hygiene` died with "exited null" and both optional steps printed SKIP with the tools present on PATH. After, the same command runs prettier, shellcheck and actionlint and prints "check:hygiene: passed", with no deprecation warning. `golangci-lint` is detected by the new onPath where the old one missed it. Refs RL-20 / L-14. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(format): ignore build output that nested gitignores hide Prettier honours the root .gitignore and no other. Every build and scratch directory in this repository is ignored by a *nested* one -- Client/.gitignore, .serena/.gitignore, .superpowers/sdd/.gitignore -- so none of them were excluded from the new repository-wide gate. The effect is not subtle. Running `cargo test` once drops roughly 850 formattable files into Client/src-tauri/target/, and the hygiene gate goes from clean to "Code style issues found in 939 files". CI never sees it, because a fresh checkout has no build output; every contributor sees it on their second command. Mirrors the three nested files rather than inventing a list: dist, coverage, playwright-report, test-results, .vite, src-tauri/target and src-tauri/gen from Client/.gitignore, plus .serena/ and .superpowers/sdd/. node_modules needs no entry -- Prettier ignores it by default. Verified: `npx prettier --check .` reports "All matched files use Prettier code style" with a fully populated Client/src-tauri/target/ present on disk, and still names README.md when a misformatted table is appended to it. Refs RL-19 / L-13. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(ci): shellcheck, actionlint, and a repository hygiene job The last two gates RL-19 asks for. Neither existed: the shell scripts were never linted, the workflows were never syntax-checked, and .githooks/pre-commit carried hand-written `# shellcheck disable=` directives that nothing had ever read. New `hygiene` job, ubuntu-only and root-scoped, modelled on docs-consistency for the same reason: every gate in it is platform-independent text analysis, and .gitattributes pins eol=lf so a second OS would only re-prove line endings. It runs `npm run check:hygiene` -- the same entry point a contributor runs, not a parallel copy of the commands. shellcheck ships in the runner image. actionlint does not, so it is pinned by version and verified by sha256: an installer script piped from a branch would be the one unverified download in a workflow file that pins every action by commit SHA. Prettier's step moves here from client-check, where it no longer belongs. Both linters found real defects. shellcheck, 3 findings in 8 scripts. Two are SC1125 errors in .githooks/pre-commit: `# shellcheck disable=SC2086 - repo paths contain no spaces` is not a valid directive. Trailing prose makes shellcheck discard the rest of the line, so neither suppression was ever in effect -- and one of the two was written earlier in this same branch, which is a fair demonstration of why the gate is worth having. The prose moves to its own line above. The third is SC2015 in start-server.sh, rewritten as an explicit if. actionlint, 5 findings, all inside `run:` blocks it shellchecks once shellcheck is on PATH. Three SC2015 in load-baseline.yml, rewritten as explicit ifs. Two SC2035 in release.yml, where `sha256sum *` should not become `sha256sum ./*`: the comment four lines above records that ParseChecksumFile exact-matches the last field, so a "./" prefix would strand every deployed server exactly as a "windows/" prefix would. `sha256sum -- *` satisfies the linter and leaves the output bytes identical. Verified all three gates in both directions with shellcheck 0.10.0 and actionlint 1.7.7 on PATH. Passing: `node scripts/run.mjs check:hygiene` prints "check:hygiene: passed" with all three steps run, not skipped. Failing: appending `bait_fn() { cat $1; }` to Server/scripts/voice-test.sh fails on SC2086; changing a runs-on to `ubunt-latest` fails on runner-label; appending a misformatted table to README.md fails prettier. All three files restored and confirmed clean afterwards. actionlint validates the new job in ci.yml itself. Refs RL-19 / L-13, S-05. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(plans): record B1 progress through B1-3 The header still read "B1-0 is complete; B1-1 is the next step" three merged phases later. A plan that misstates where it is costs a reader the same confusion whether it is stale by one phase or three. B1-0 (#1410), B1-1 (#1411), B1-2 (#1412) and B1-3 (this branch) are done; B1-4, dependency automation, is next. Verified: `node scripts/check-doc-counts.mjs` still agrees on 27 claims across 9 watched documents -- this file is one of them -- and prettier reports it clean. * chore(ci): pin Repository Hygiene as a required check on dev The second half of S-05. Its acceptance criterion is "tree is formatted AND a fast required gate fails future drift" -- a check that runs but is not pinned lets a formatting regression merge, so the gate is not a gate until this lands. The name was read off PR #1414 with `gh pr checks` after the job reported `pass` in 26s, not copied out of ci.yml. That order matters: the B0 script records that three pinned names exist in no workflow file at all, and that a required check which never reports blocks every PR forever. Extends the existing script rather than adding a second one, per the B1 plan. Also records, in the "deliberately NOT pinned" list, that Docs & Ledger Consistency reports and passes on a dev PR yet is unpinned. That reads as an oversight from the 2026-08-25 pass rather than a decision, but it belongs to G-04, so it is documented here and not changed. NOT APPLIED YET. Running this script now would pin a check that PR #1413 cannot report -- its branch predates the hygiene job, so the job does not exist in its workflow file and the check would never arrive. Run it after #1414 merges; #1413 needs a rebase onto dev regardless. Verified: shellcheck clean, the embedded JSON parses, and `check:hygiene` passes with prettier, shellcheck and actionlint all running. Refs S-05, RL-14 / G-03. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
30 KiB
30 KiB
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):
- Built-in defaults (compiled into the binary)
- YAML file (
config.yaml) - 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). |
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_keyorlivekit_api_secretare 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 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). 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(fromServer/) 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. Empty = feature off. |
Treat this as a credential. Prefer
OWNCORD_GIF_API_KEY(or a secrets manager) over writing it intoconfig.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. |
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
# 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 -- production deployment guide
- LiveKit Setup -- voice/video setup
- Quick Start -- getting started