Development Guide

The rules behind these commands live in AGENTS.md; this page is the how-to.

First runCopy Anchor Link

git clone https://github.com/krizaka/orochia.git && cd orochia
npm install
npm run setup        # .env + PostgreSQL 16 + migrations + seed
npm run dev          # http://localhost:3000

npm run setup is idempotent: run it again after pulling, or whenever the databases were stopped.

Clone the admin console and the design system next to this repository with npm run workspace -- clone, then npm run workspace -- status shows the three repositories at a glance.

Accounts of the development seedCopy Anchor Link

The databaseCopy Anchor Link

PostgreSQL runs in the orochia-postgres-dev container (deploy/docker/docker-compose.dev.yml, data in a named Docker volume).

db:reset, db:restore and db:psql work only on the local container: they refuse NODE_ENV=production and any DATABASE_URL that does not point at this machine.

Changing the schemaCopy Anchor Link

1. Edit the tables in packages/db/src/schema/*.ts (and their relations in schema/index.ts).
2. npm run db:generate -- --name short_description writes packages/db/drizzle/NNNN_short_description.sql.
3. Read the SQL. Renames are generated as drop + add — rewrite them as ALTER … RENAME by hand when data must survive.
4. npm run db:migrate, then npm run db:check.
5. npm run docs:generate — docs/DATABASE.md follows the schema.
6. Commit the schema, the migration and the docs together. Never edit a migration that was already applied anywhere.

The seedCopy Anchor Link

packages/db/src/seed.ts builds a small, coherent platform that exercises every feature. It is idempotent (rows are keyed by e-mail, Bunny video id, gateway reference…), so npm run db:seed can run any time; it writes ledger rows exactly as settlement does (10 % platform fee) and refuses to run with NODE_ENV=production.

TestsCopy Anchor Link

npm run check                    # lint + types + unit tests + generated docs up to date
npm run db:reset -- --yes        # the scenarios change data: start them from the seed
npm run test:e2e                 # needs the app running (npm run dev); OROCHIA_URL to target another one

EnvironmentCopy Anchor Link

One .env at the repository root (created by npm run setup from .env.example). Everything starts without any external account: the feed, profiles, followers, contacts, collections, comments, image stories and the seeded videos' pages work on the local database, files are stored on disk (STORAGE_DRIVER=local), e-mail is logged instead of sent, and with OROCHIA_DEMO_MODE=true unlocks settle immediately when no gateway is configured. In production every secret is mandatory (see Deployment).

Video features locally (Bunny Stream)Copy Anchor Link

Uploading and playing videos, video stories and editor drafts need a Bunny Stream library — video never passes through the app. A free trial library is enough:

1. Create a Stream library; in API, copy the library id, the API key and the Read-Only key; note the CDN hostname (vz-….b-cdn.net).
2. In Security, turn on CDN token authentication (copy its key) and add localhost to the allowed domains.
3. In Encoding, keep Keep original files on (drafts reopen from the original).
4. Fill BUNNY_STREAM_API_KEY, BUNNY_STREAM_LIBRARY_ID, BUNNY_STREAM_HOSTNAME, BUNNY_STREAM_TOKEN_AUTH_KEY and BUNNY_WEBHOOK_SECRET (the Read-Only key), then restart npm run dev.

Bunny cannot call localhost, and a library has one webhook URL — a library shared by several environments (local and dev) notifies only one of them. Without the webhook, video stories still go live: the stories rail asks the Stream API about any video story unsettled for 20 s (reconcileStoryVideos, lib/stories.ts) and settles it as the webhook would, and the author sees their story as Processing meanwhile. Videos and drafts still wait for the webhook: to exercise it, expose the app with a tunnel (cloudflared tunnel --url http://localhost:3000, ngrok http 3000) and set the library's webhook to <tunnel>/api/webhooks/bunny. The in-browser editor (ffmpeg.wasm) needs nothing: its engine is fetched once from a CDN.

E-mail templatesCopy Anchor Link

Every e-mail is a template in apps/web/mail-templates/<id>/<locale>/ (subject.txt, body.html, body.txt), inside the shared _layout/ (rules: AGENTS.md §3.G). Locally they are read from those files (MAIL_TEMPLATES_SOURCE=local) and the messages go to the log; MAIL_DELIVERY=on with a Resend or Mailgun key really sends them.

npm run mail:templates:preview   # apps/web/.mail-preview/index.html — every template, en and fr
npm run mail:templates:push      # dry run against Bunny Storage; -- --apply publishes (production credentials)

TroubleshootingCopy Anchor Link

Présentation du produit →