Deployment
This guide matches the docker-compose.prod.yml and .env.example files in the repository. For day-to-day local development, see Installation.
Requirements
Section titled “Requirements”| Dependency | Minimum |
|---|---|
| Docker | 24+ |
| Docker Compose v2 | 2.20+ |
| RAM (app + Postgres + Redis) | 2 GB recommended (1 GB minimum tight) |
TLS termination is usually handled by a reverse proxy (Nginx, Traefik, Caddy) or your platform (Coolify, Kubernetes ingress).
Quick start
Section titled “Quick start”1. Clone and configure
Section titled “1. Clone and configure”git clone https://github.com/orimora-app/orimora.git orimoracd orimoracp .env.example .envFill all variables marked as required in .env. The Compose file expects at least:
APP_URL— public HTTPS URL, e.g.https://wiki.example.comPOSTGRES_PASSWORD— a strong random value (interpolated intoDATABASE_URL)SESSION_SECRET,MAGIC_LINK_SECRET,LLM_ENCRYPTION_KEY— 64-character hex strings (32 bytes each)SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASSWORD,SMTP_FROM— a real mail server, unless you configure single sign-on
Signing in works by emailed link, so the first sign-in needs a working mail server (the SMTP_* variables) or single sign-on configured through the environment. Without one of the two, nobody can get in. The app says so in its startup log and on the login page.
2. Generate secrets
Section titled “2. Generate secrets”Use the same pattern as in the root DEPLOYMENT.md:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" # repeat for each *64 hex* secretKeep generated values in a password manager; never commit .env.
3. Build and start
Section titled “3. Build and start”docker compose -f docker-compose.prod.yml up -d --build4. Run database migrations
Section titled “4. Run database migrations”Required on first deploy and after upgrades that ship new migration files:
docker compose -f docker-compose.prod.yml exec app yarn db:migrate5. Verify
Section titled “5. Verify”curl -s http://localhost:3000/api/readyThen open APP_URL in the browser and complete onboarding if this is a fresh database.
Environment variables (production)
Section titled “Environment variables (production)”The table below aligns with .env.example. Variable names differ from older drafts that used SECRET_KEY or PUBLIC_BASE_URL.
Required (typical production)
Section titled “Required (typical production)”| Variable | Purpose |
|---|---|
APP_URL |
Canonical public URL — used in links, OAuth redirects, magic-link URLs |
DATABASE_URL |
Set automatically in Compose from POSTGRES_*; custom installs must point to PostgreSQL 16+ |
REDIS_URL |
Points at the bundled redis service in Compose (redis://redis:6379, no password) |
SESSION_SECRET |
Signs session cookies |
MAGIC_LINK_SECRET |
Signs magic-link tokens |
LLM_ENCRYPTION_KEY |
AES-256-GCM for stored LLM API keys (required even if AI is off) |
POSTGRES_PASSWORD |
Database user password (Compose) |
Optional but common
Section titled “Optional but common”| Variable | Purpose |
|---|---|
CRON_SECRET |
Bearer token for POST /api/admin/cron.cleanup (scheduled trash purge, reminders) |
COLLAB_SECRET |
Shared secret for Yjs / Hocuspocus collaboration |
COLLAB_MAX_CONNECTIONS |
Cap simultaneous collab sockets (default 50) |
SMTP_* |
Outbound email for magic links (SMTP_PASSWORD in .env.example) |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Google OAuth |
OIDC_* |
Generic OIDC provider |
STORAGE_DRIVER / S3_* |
Upload storage backend. Default local (disk). Set STORAGE_DRIVER=s3 + S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY (+ optional S3_ENDPOINT/S3_FORCE_PATH_STYLE/S3_PRESIGN_TTL_SECONDS) to store attachments/avatars/logos in an S3-compatible bucket, served via presigned URLs — see Configuration. (Separate from off-site backups, which use BACKUP_RCLONE_REMOTE; BACKUP_S3_BUCKET is parsed but not wired up.) |
Full column-style reference: DEPLOYMENT.md in the repo.
Reverse proxy
Section titled “Reverse proxy”Terminate TLS at Nginx, Caddy, or Traefik and proxy to the app container (port 3000 inside the network). You must preserve:
HostX-Forwarded-ForX-Forwarded-Proto(HTTPS detection)- WebSocket upgrade headers for
/collab
Example Nginx location (HTTP → app):
location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;}Updates
Section titled “Updates”git pulldocker compose -f docker-compose.prod.yml build appdocker compose -f docker-compose.prod.yml up -ddocker compose -f docker-compose.prod.yml exec app yarn db:migrateWatch application logs during the first request after a schema change.
Backups & disaster recovery
Section titled “Backups & disaster recovery”Do not run production without backups. BACKUP_ENABLED defaults to true in the production compose file (daily encrypted DB dumps + weekly Markdown exports), but you still need to:
- Set
CRON_SECRET(drives the scheduled backup + cleanup jobs). - Configure an off-site target (
BACKUP_RCLONE_REMOTE) so a host loss doesn’t lose everything. - Store the recovery code (shown once under Settings → Admin → Backups) — off-site copies are encrypted and cannot be decrypted without it.
Then rehearse a restore. See Backups and the Disaster Recovery runbook.
Troubleshooting
Section titled “Troubleshooting”| Issue | Checks |
|---|---|
| OAuth redirect mismatch | APP_URL must exactly match the URL in Google / OIDC console |
| Redis connection errors | REDIS_URL reachable; redis container healthy |
| 502 from proxy | App not listening on expected port; WebSocket path blocked |
| Migrations fail | Backup DB first; ensure only one migration runner at a time |
Further reading
Section titled “Further reading”- Configuration — SMTP, AI, S3, MCP OAuth
- Backups · Disaster Recovery — encrypted off-site backups + restore
- REST API overview — rate limits and auth
- Architecture — stack overview