Installation (development)

import { Aside } from ‘@astrojs/starlight/components’;

This guide is for local development and for anyone who wants to evaluate Orimora without Docker. Production deployment is covered in Deployment.

Prerequisites

Requirement	Version
Node.js	22 LTS or 24
Yarn	Classic (v1) or Berry — repo uses yarn in scripts
PostgreSQL	16+
Redis	7+

Optional but recommended: direnv or a tool to load .env per project.

1. Clone and install

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

2. Create databases

Create an empty PostgreSQL database and ensure Redis is reachable:

# Example: create DB (adjust user/host as needed)
createdb knowledgebase
# Redis — default local URL is usually sufficient
redis-cli ping   # → PONG

3. Environment variables

Copy the template and edit values:

cp .env.example .env

Minimum for a working dev server:

Variable	Purpose
DATABASE_URL	postgresql://user:password@localhost:5432/knowledgebase
REDIS_URL	redis://localhost:6379
APP_URL	Public base URL of the app — use http://localhost:5173 in Vite dev mode
SESSION_SECRET	64 hex chars — node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
MAGIC_LINK_SECRET	Same length as above (separate value)
LLM_ENCRYPTION_KEY	64 hex chars — required even if you disable AI; encrypts stored LLM API keys

Leave SMTP_HOST empty if you do not need magic-link email in dev (you can use OAuth or seed users depending on your setup).

The canonical description of every variable is in [Configuration](/guides/configuration/). Names match **`.env.example`** in the repository root — older docs that referred to `SECRET_KEY` or `PUBLIC_BASE_URL` are outdated; use `SESSION_SECRET` / `APP_URL`.

4. Run migrations

Schema changes are applied with Drizzle:

yarn db:migrate

Run this after every pull if the repository includes new migration files.

5. Start the dev server

yarn dev

Then open APP_URL in the browser (default Vite: http://localhost:5173). Complete the onboarding flow to create your workspace.

6. Verify

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

You should get a JSON payload indicating the service is healthy.

Collaboration WebSocket (optional)

Real-time editing uses a WebSocket upgrade on the same origin as the app (path /collab). In development this is handled by the Vite plugin; ensure nothing blocks WebSockets to your dev URL.

If you configure COLLAB_SECRET, the collab endpoint expects it — see .env.example.

Common issues

Symptom	What to check
DATABASE_URL connection refused	Postgres running? Host/port/user match?
Redis errors on startup	REDIS_URL correct? redis-cli ping
Migrations fail	Same DATABASE_URL as the running app; user has DDL rights
Magic link never arrives	Configure SMTP or use Google/OIDC sign-in
401 on /api/v1/*	Use Authorization: Bearer kb_... with an API key from Settings → Developers

Next steps

• Deployment — Docker Compose and production checklist
• REST API overview — authentication, rate limits, response shapes
• MCP & AI integrations — Model Context Protocol server for Cursor and other clients
• OpenAPI reference — machine-readable spec and interactive operations