Installation (development)

This guide gets Orimora running on your computer for development and evaluation. You do not need prior Docker experience for the recommended path.

For production on your own server see Deployment. For Coolify see Coolify Setup.

Choose your path

Path	Best for	What you install
A — Docker Compose (recommended)	Beginners, quick start	Docker Desktop only — Postgres, Redis, and Mailpit start automatically
B — Native Yarn	Active development on the codebase	Node.js 22+, Yarn, PostgreSQL 16+, Redis 7+ on your machine

Both paths use the same .env file. The variable reference at the bottom applies to both.

---

Path A — Docker Compose (recommended)

1. Install Docker Desktop (Mac/Windows) or Docker Engine + Compose on Linux. Verify:

   docker compose version

2. Clone the repository and install Node dependencies:

   git clone https://github.com/defcon1702/orimora.git orimora
   cd orimora
   yarn install

3. Start infrastructure (PostgreSQL, Redis, Mailpit):

   docker compose up -d

   This reads docker-compose.yml in the repo root. Services:

   Service	Purpose	Host port
   postgres	Database	5433 → container 5432
   redis	Sessions, queues, rate limits	6379
   mailpit	Catches outgoing email (magic links)	SMTP 1026, Web UI 9025

   Optional Redis GUI (profile tools): docker compose --profile tools up -d → http://localhost:8081

4. Create your .env file:

   cp .env.example .env

   Paste this minimum working dev configuration (secrets are examples — generate your own for anything shared):

   # ── Required ─────────────────────────────────────────────
   DATABASE_URL=postgresql://kb:kb_dev_password@localhost:5433/knowledgebase
   REDIS_URL=redis://localhost:6379
   APP_URL=http://localhost:5173
   SESSION_SECRET=PASTE_64_HEX_CHARS_HERE
   MAGIC_LINK_SECRET=PASTE_ANOTHER_64_HEX_CHARS_HERE
   LLM_ENCRYPTION_KEY=PASTE_THIRD_64_HEX_CHARS_HERE
   PUBLISHING_ENCRYPTION_KEY=PASTE_FOURTH_64_HEX_CHARS_HERE
   
   # ── Email via Mailpit (optional but useful) ──────────────
   SMTP_HOST=localhost
   SMTP_PORT=1026
   SMTP_FROM=noreply@orimora.local
   
   # ── Dev defaults ─────────────────────────────────────────
   NODE_ENV=development
   ALLOW_REGISTRATION=true

   Generate four independent secrets (run four times):

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

5. Run database migrations:

   yarn db:migrate

   Repeat after every git pull that adds files under src/lib/server/db/migrations/.

6. Start the dev server:

   yarn dev

7. Open the app at http://localhost:5173 and complete onboarding (creates your workspace admin).

8. Verify health:

   curl -s http://localhost:5173/api/health

   Magic-link emails appear in the Mailpit UI: http://localhost:9025

---

Path B — Native Yarn (without Docker)

1. Install prerequisites:

   Tool	Version
   Node.js	22 LTS or 24
   Yarn	as used in repo scripts
   PostgreSQL	16+
   Redis	7+

2. Clone and install (same as Path A steps 2).

3. Create PostgreSQL database:

   createdb knowledgebase
   redis-cli ping   # must return PONG

4. Configure .env — adjust DATABASE_URL to your local Postgres user/password/port (default port 5432, not 5433):

   DATABASE_URL=postgresql://YOUR_USER:YOUR_PASSWORD@localhost:5432/knowledgebase
   REDIS_URL=redis://localhost:6379
   APP_URL=http://localhost:5173
   # … same secrets as Path A

5. Migrate, dev server, verify — same as Path A steps 5–8.

---

Environment variables — complete reference

The canonical list lives in .env.example. Below: every variable in plain language.

Note

Older docs mentioned SECRET_KEY or PUBLIC_BASE_URL. The correct names are SESSION_SECRET and APP_URL.

Required for local dev — 7 variables

Minimum to boot the dev server.

Variable	What it does	Example / how to set
DATABASE_URL	PostgreSQL connection string	Path A: postgresql://kb:kb_dev_password@localhost:5433/knowledgebase
REDIS_URL	Redis for sessions, queues, rate limits	redis://localhost:6379
APP_URL	Public URL of the app (magic links, OAuth redirects)	http://localhost:5173 in Vite dev
SESSION_SECRET	Signs HTTP-only session cookies (min 32 bytes)	64 hex chars via randomBytes(32)
MAGIC_LINK_SECRET	Signs passwordless login tokens	Separate 64 hex value
LLM_ENCRYPTION_KEY	Encrypts stored LLM API keys at rest	64 hex chars — required even if AI is unused
PUBLISHING_ENCRYPTION_KEY	Encrypts webhook secrets and publishing credentials	64 hex chars

Docker Compose helper

Variable	What it does	Default
COMPOSE_FILE	Which compose file docker compose uses locally	docker-compose.yml (set in .env.example)

Optional auth hardening

Variable	What it does	Default if unset
API_KEY_SECRET	Hashes API keys at rest	MAGIC_LINK_SECRET
EMAIL_CHANGE_SECRET	Signs email-change tokens	MAGIC_LINK_SECRET
ACCOUNT_DELETION_SECRET	Signs account-deletion tokens	SESSION_SECRET
SESSION_IDLE_TIMEOUT_DAYS	Log out idle sessions after N days; 0 = disabled	7

OAuth (optional)

Register redirect URIs in each provider console as {APP_URL}/auth/google/callback, /auth/microsoft/callback, /auth/oidc/callback.

Variable	What it does
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google sign-in
MICROSOFT_TENANT_ID	Azure tenant ID or common
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET	Microsoft sign-in
OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET	Generic OpenID Connect
OIDC_SCOPE	Space-separated scopes (default: openid email profile)

Email / SMTP

Leave empty to skip email (use OAuth instead). With Mailpit (Path A): SMTP_HOST=localhost, SMTP_PORT=1026.

Variable	What it does
SMTP_HOST	Mail server hostname
SMTP_PORT	Usually 587 (STARTTLS) or 465
SMTP_USER / SMTP_PASSWORD	Credentials (empty for Mailpit)
SMTP_FROM	Sender address

App behaviour

Variable	What it does	Default
NODE_ENV	development or production	development
ALLOW_REGISTRATION	Allow open sign-up	false in .env.example; use true locally
DOCS_URL	Redirect target for /docs in the app	https://docs.orimora.com
EXTRA_ALLOWED_ORIGINS	Extra allowed origins for WebSocket /collab (comma-separated)	—

Collaboration (real-time editing)

Variable	What it does	Default
COLLAB_SECRET	Optional shared secret for collab WebSocket	unset in dev
COLLAB_MAX_CONNECTIONS	Max simultaneous collab connections	50
COLLAB_MAX_YJS_STATE_BYTES	Max persisted Yjs document size (DoS guard)	8388608 (8 MB)

Real-time editing uses WebSocket path /collab on the same origin as the app. Vite handles the upgrade in dev.

Operations (mostly production)

Variable	What it does
CRON_SECRET	Protects POST /api/admin/cron.cleanup (trash purge, invite reminders)
ORIMORA_API_KEY	For local MCP CLI (yarn mcp) — create in Settings → Developers

AI, S3, backups, push, quotas

Group	Variables
AI & publishing	LLM_ENCRYPTION_KEY, PUBLISHING_ENCRYPTION_KEY, GIT_MIRROR_ALLOWED_HOSTS
Upload storage (opt-in: STORAGE_DRIVER=s3)	STORAGE_DRIVER, S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_ENDPOINT, S3_FORCE_PATH_STYLE, S3_PRESIGN_TTL_SECONDS
Backups	BACKUP_ENABLED, BACKUP_PATH, BACKUP_RETENTION_DAILY, BACKUP_RETENTION_WEEKLY, BACKUP_SCHEDULE, BACKUP_S3_BUCKET, BACKUP_PG_DUMP_TIMEOUT_MS
Web Push	VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT — generate with node scripts/generate-vapid-keys.mjs
Webhook/publishing tuning	WEBHOOK_*, PUBLISHING_* — see Configuration
Storage quota	DEFAULT_TEAM_STORAGE_QUOTA_BYTES, STORAGE_QUOTA_WARN_PERCENT

---

Common issues

Symptom	Fix
DATABASE_URL connection refused	Path A: run docker compose up -d; use port 5433 not 5432
Redis errors	Check REDIS_URL; redis-cli ping
Migrations fail	Same DATABASE_URL as running app; DB user needs DDL rights
Magic link never arrives	Configure SMTP or open Mailpit at http://localhost:9025
WebSocket / collab fails	Firewall must allow WS to APP_URL; check EXTRA_ALLOWED_ORIGINS
Boot error about encryption keys	Set both LLM_ENCRYPTION_KEY and PUBLISHING_ENCRYPTION_KEY
401 on /api/v1/*	Use Authorization: Bearer kb_… from Settings → Developers

Next steps

• Deployment — production Docker Compose stack
• Coolify Setup — hosted deployment with Traefik
• Configuration — grouped reference with OAuth redirect examples
• Editor — writing and formatting documents