chat/docs/OPERATIONS.md

Operations

Environment

Copy .env.example to .env. Full list:

Variable	Default	Purpose
NODE_ENV	development	production under the NixOS module (and CI); gates the DRIVER_DEBUG default
PORT / HOST	3000 / 127.0.0.1	listen address (keep localhost behind nginx)
APP_PASSWORD	(required)	admin access key — generate with openssl rand -base64 24
SESSION_TTL_HOURS	720	Bearer session lifetime (30 days)
DATA_DIR	./data	holds kisassistant.db (SQLite — unused when POSTGRESQL_URL is set)
POSTGRESQL_URL	(empty)	Postgres fallback, e.g. postgres://kisassistant:secret@localhost:5432/kisassistant (typically a docker container). Empty = local SQLite. Boot fails fast when unreachable.
CDN_DIR	./cdn	local file CDN storage (avatars; NixOS: under state dir)
OCR_LANG	eng	tesseract language(s) for the OCR tool
OCR_MAX_CHARS	100000	transcription cap (longer results are truncated + flagged)
TESSERACT_BIN	tesseract	path to the tesseract binary (NixOS module puts it on PATH; missing binary cleanly disables OCR with 501)
DRIVER_DEBUG	true dev / false prod	per-driver debug logging to stdout
WIKI_URL	https://git.kisakay.com/k/chat/wiki	remote docs wiki — GET /wiki redirects (302) there
SMTP_HOST / SMTP_PORT / SMTP_SECURE	(empty) / 587 / false	key-recovery mailer — empty host disables it (false = STARTTLS, true = implicit TLS/465)
SMTP_USER / SMTP_PASS	(empty)	SMTP auth (omit both for open relays / local catchers)
SMTP_FROM	KisAssistant <[email protected]>	sender address
APP_URL	http://localhost:3000	public base URL used in reset links — must be the real origin in prod
RESET_TTL_MIN	60	reset-link lifetime (single use)
RATE_LIMIT_MAX / RATE_LIMIT_WINDOW_MIN	5 / 10	login rate limit per IP
OLLAMA_HOST / OLLAMA_ENABLED	http://10.66.66.4:11434 / true	local-model driver
MISTRAL_*, GLM_*, DEEPSEEK_*, ANTHROPIC_*, OPENAI_*, GEMINI_*	disabled	API drivers: set *_ENABLED=true and *_API_KEY
GLM_BASE_URL	https://api.z.ai/api/paas/v4	Zhipu platform override (mainland China: https://open.bigmodel.cn/api/paas/v4)

Local development

bun install
bun run dev              # backend watch mode (restarts on edit), :3000
bun run dev:frontend     # Vite HMR + /api proxy, :5173 (use this for UI work)
bun run dev:all          # both at once
bun run build:frontend   # production build into public/

Smoke tests: start the backend on a free non-3000 port with a throwaway DATA_DIR (port 3000 is the owner's dev server — do not touch it), then drive the API with curl/python: login → models → conversations → chat → share → unshare. See AGENTS.md.

Postgres fallback (docker)

SQLite is the default. For Postgres, run a container and point the app at it:

docker run -d --name kisassistant-pg --restart unless-stopped \
  -e POSTGRES_USER=kisassistant -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=kisassistant -p 127.0.0.1:5432:5432 \
  -v kisassistant-pgdata:/var/lib/postgresql/data \
  postgres:17-alpine

POSTGRESQL_URL=postgres://kisassistant:[email protected]:5432/kisassistant \
  DATA_DIR=/tmp/ka-pg-throwaway \
  bun run src/index.ts

Notes:

• The app uses Bun's native bun:sql driver — no extra dependency.
• Schema is created idempotently at boot (same tables as SQLite; timestamps are BIGINT, auto ids BIGSERIAL). A fresh database starts empty except the bootstrapped admin row — there is no SQLite→Postgres data migration (re-create accounts or keep SQLite).
• Switching back is just unsetting POSTGRESQL_URL (the SQLite file is untouched while Postgres is active).
• Back up with pg_dump (SQLite: copy kisassistant.db, or .backup while running under WAL).

Managing accounts

1. Log in as admin with the APP_PASSWORD key.
2. Open Accounts → New account → username (+ display name).
3. Copy the one-time ka_… key and hand it to the owner (chat, QR code, …).
4. Users set their display name, avatar (upload a picture in the profile settings — hosted on the built-in CDN), theme, accent color and feature flags in the settings.
5. Rotate a compromised key with the regenerate button (old sessions die); delete removes the account with all its chats and shares.

Admin Center (/admin) & self-registration

The sidebar Admin Center button (admin only) opens the /admin page with four tabs: Accounts (same manager as before, incl. the Ollama model catalog), Access (access-request wishlist triage, see below), Features (server-side switches), Mail (SMTP credentials viewer + connectivity tester: GET /api/admin/mail, POST /api/admin/mail/verify, POST /api/admin/mail/test, admin Bearer only).

• registration_enabled (default off): when on, the login page shows a working Register button — anyone can create an account (key shown once) via POST /api/auth/register. When off, the button is greyed with the tooltip "Registration currently disabled on this platform" and the endpoint answers 403. Flipped live, no restart. Turning it on retires the access-request wishlist automatically.
• registration_request_enabled (default on): shows Request access on the login page (wishlist). Only switchable on while public registration is off — the two are mutually exclusive (API answers 409 otherwise).
• tools_ocr_enabled (default on): admin kill-switch for the OCR tool.
• reports_enabled (default on): admin kill-switch for message reports — the chat flag button turns grey with a "Report disabled" tooltip and POST /api/reports answers 403. Surfaced to clients via GET /api/tools.
• username_change_enabled (default on): lets users rename themselves (PATCH /api/me username); off answers 403 and locks the Settings field. Admins bypass it (PATCH /api/admin/users/:id still works). Surfaced to clients via GET /api/tools.
• Flags live in the settings SQLite table, edited via GET/PATCH /api/admin/settings (admin Bearer only).

Model access policy (kill-switch + rate limits)

The Admin Center Models tab lists every model across enabled drivers (grouped, Ollama library moved there too). Per model id ("driver:model"): an Enabled switch and hourly / daily per-user request caps (0 = unlimited, admins always bypass). Policy lives in the settings table (model_policy JSON blob, default entries pruned); usage counters in model_usage (fixed UTC hour/day windows, old buckets pruned on write).

• Disabled models vanish from GET /api/models for users (admins still see everything) and POST /api/chat rejects them (403) — attempts count toward limits even when generation later fails; over-limit answers 429.
• Routes: GET /api/admin/model-policy[?refresh=1], PATCH /api/admin/model-policy ({model, enabled?, hourly?, daily?}). Ollama library: POST /api/admin/ollama/pull (NDJSON progress), DELETE /api/admin/ollama/models/:name, and the connectivity probe GET /api/admin/ollama/status (reachability, version, on-disk models — surfaced in Admin Center → Models).

Personal providers (BYOK)

Users can connect their own OpenAI / Anthropic / DeepSeek / Gemini API keys in Settings → Providers (per account, no admin involved). Connected providers add their models to that user's model menu at the top (no page refresh needed); usage is billed to the user's own provider account, and the admin model policy (kill-switch + rate limits) still applies.

• Keys are stored server-side in user_provider_keys and never returned to any client (GET /api/me/providers exposes presence + last 4 chars only; never logged). A stored key greys out its field (Replace to rotate, Remove to disconnect). Deleting the account wipes its keys.
• Routes: GET /api/me/providers, PUT /api/me/providers/:id ({apiKey}, 8–256 chars), DELETE /api/me/providers/:id (all Bearer, owner-scoped).

Access-request wishlist (registration approval queue)

When public registration is off, visitors can still reserve a username via Request access on the login page: username + email (required) + a motivation message (10+ chars). This creates a ticket (access_requests + access_messages tables) with a personal page at /review/<id> (unguessable UUID, same pattern as share links).

• Requester: follows the decision, argues their case and replies on the /review page. Closed tickets (accepted/refused) are read-only.
• Admin: Access tab in the Admin Center — filter by status, open a ticket, reply (emailed to the requester), and set pending → reviewing → accepted / refused with a reason. Accepting creates the account and returns the access key once (also emailed). Terminal tickets can't be reopened.
• Email (needs SMTP_*): received-confirmation, reviewing/accepted/refused notices, and every admin reply — all HTML, all stating email is notification-only and replies belong on the /review page.
• Routes: POST /api/access/request (public, rate-limited), GET /api/access/ticket/:id + POST .../message (public, ticket bearer), GET /api/admin/access, GET/PATCH /api/admin/access/:id, POST /api/admin/access/:id/message (admin).
• Live updates ride WebSockets (no polling): GET /api/access/ws/:id (ticket bearer — pushes access_message + access_status for that ticket) and GET /api/admin/ws?token=… (admin Bearer in query string, browsers can't set WS headers — pushes access_message + access_status + access_created for every ticket plus report_created + report_status, driving the AdminCenter badges and the triage lists). Every event carries its full payload (access_created bundles the ticket, its first message and the message count), so clients apply it straight to state — HTTP resync only happens on (re)connect to cover the offline gap. Clients ping every 25 s ({"type":"ping"} → {"type":"pong"}) with a pong watchdog that redials half-dead sockets.

Content reports (flagged AI responses)

Every assistant message carries three actions: Copy, Search the web (DuckDuckGo, new tab) and Report. Reporting opens a modal with a reason picker (copyright, gore, falseinfo, bug) plus optional details, and creates a row in the reports table with a content snapshot (survives later edits/deletion of the chat), the triggering user prompt, the model, and the reporter.

• Reporter: capped at 20 open (open + reviewing) reports (429 beyond). Reporting the same message twice returns the existing report (409 already reported).
• Admin: Reports tab in the Admin Center (badge counts open reports, excluding shadow-banned reporters) — filter by status, expand for the full snapshot + reporter details, and set open → reviewing → resolved / dismissed with an internal note. An admin can also shadow-ban a noisy reporter (toggle on the report detail, with confirm): their reports are still accepted but flagged unreliable and hidden from the badge.
• Routes: POST /api/reports (Bearer), GET /api/admin/reports, PATCH /api/admin/reports/:id, POST /api/admin/users/:id/shadowban (admin).

Key recovery via email (optional)

Set the SMTP_* vars (and the real public APP_URL) to enable it; otherwise the login page hides the "Forgot your access key?" link.

1. Admin sets a recovery email at account creation (or the user sets their own in profile settings).
2. User clicks the link on the login page and enters their username. The API always answers {ok:true} (no account enumeration) and, if the account has an email, sends a one-time /reset/<token> link (60 min, single use).
3. Opening the link shows a confirm page; confirming rotates the key immediately — the new ka_… key is displayed once, old sessions die. (admin itself is excluded: its key lives in .env.)

Local file CDN (avatars)

PUT /cdn/<ns>/<key> (Bearer) / GET /cdn/<ns>/<key>.<ext> (public), e.g. /cdn/avatar/<account-id>.png. Namespaces live in CDN_NAMESPACES (src/cdn.ts) — add one to extend (future usage).

• Allowed types only jpg/png/webp, verified by magic bytes, never by extension (client filename is ignored; the stored extension comes from detection). Everything else → 415, unknown namespace/ext → 404.
• avatar rules: 5 MB max (413 above), 5 uploads max per 2 h per account (429 + Retry-After), ownership enforced (own id, or admin).
• Served with fixed Content-Type, nosniff, Cache-Control: public, max-age=3600. No listing, no traversal (strict charsets + SPA fallback).

Platform tools & attachments

Uploads always go through platform tools (GET /api/tools lists them with availability). Today: OCR (POST /api/tools/ocr, tesseract).

• Images (jpg/png/webp, 5 MB max, magic-verified, 20 jobs/hour/account) are transcribed on the backend to TXT — the model never receives image bytes. Text files ride the text CDN namespace (UTF-8 validated, 500 KB max, keys prefixed with the account id).
• The UI (paperclip menu in the composer) explains this and always shows a pre-transcription preview: the user reviews/edits the text, then attaches it. Attachments travel as labeled text blocks inside the message, so they persist in history and work with every model.

NixOS deployment (chat.kisakay.com)

Full step-by-step guide: NIXOS-HOSTING.md.

flake.nix exposes packages.<system>.default (backend + prebuilt frontend, frontend compiled offline from frontend/bun.lock via a fixed-output bun install) and nixosModules.default.

imports = [ kisassistant.nixosModules.default ];
services.kisassistant = {
  enable = true;
  package = kisassistant.packages.${pkgs.system}.default;  # required
  domain = "chat.kisakay.com";   # legacy switch: implies nginx + ACME
  enableNginx = true;            # explicit; requires domain
  passwordFile = "/run/secrets/kisassistant-password";  # agenix/sops-nix
  ollamaHost = "http://10.66.66.4:11434";
  extraEnv = { MISTRAL_ENABLED = "true"; };              # optional
};
security.acme.acceptTerms = true;  # required for the ACME/TLS vhost

The module sets NODE_ENV=production, CDN_DIR=/var/lib/kisassistant/cdn and DRIVER_DEBUG=false for the systemd service. enableNginx is a tri-state: true/false force the bundled reverse proxy on/off, null (the default) keeps the legacy behaviour (nginx iff domain is set).

Secrets (passwordFile, API keys) must come from files (agenix/sops-nix), never baked into the Nix store. The service stores SQLite under /var/lib/kisassistant/data; nginx terminates TLS and proxies to 127.0.0.1:3000.