RitualOS Quick Start Guide

Get the RitualOS ecosystem running locally in under 10 minutes.

---

Prerequisites

• Node.js 18+
• PostgreSQL 16+
• npm or yarn
• Git

---

Step 1: Clone the Repository

git clone <repository-url>
cd ritualos_ecosystem

---

Step 2: Start Core Services

The ecosystem has a dependency chain. Start services in this order:

2.1 Identity Service (Foundation)

cd id.ritualos.com

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your DATABASE_URL and secrets

# Setup database
npm run db:push
npm run db:seed

# Start services
npm run dev:all  # Frontend (3000) + Backend (3001)

2.2 Ledger Service (Archive)

cd ledger.ritualos.com

npm install
cp .env.example .env
# Set DATABASE_URL, ID_SERVICE_URL

npm run db:push
npm run dev:all  # Backend (3011) + Frontend (3013)

2.3 Path Service (Quest Engine)

cd path.ritualos.com

npm install
cp .env.example .env
# Set DATABASE_URL, OAUTH_CLIENT_ID=path, OAUTH_CLIENT_SECRET, ID_SERVICE_URL

npm run db:push
npm run dev  # Port 4000

---

Step 3: Start Other Services (Parallel)

Once ID, Ledger, and Path are running, start other services in parallel:

# Terminal 1: Scroll
cd scroll.ritualos.com
npm install && npm run dev  # Port 3004

# Terminal 2: Learn
cd learn.ritualos.com
npm install && npm run dev  # Port 3005

# Terminal 3: Governance
cd governance.ritualos.com
npm install && npm run dev  # Port 3007

# Terminal 4: Guild
cd guild.ritualos.com
npm install && npm run dev  # Port 3009

# Terminal 5: Market
cd market.ritualos.com
npm install && npm run dev  # Port 3008

# Terminal 6: Realm
cd realm.ritualos.com
npm install && npm run dev  # Port 3006

# Terminal 7: Portal
cd ritualos.com
npm install && npm run dev  # Port 3012

---

Step 4: Verify Services

Check each service is running:

---

Step 5: Register OAuth Clients

Run the OAuth client registration script from the ID service directory:

cd apps/id.ritualos.com
pnpm oauth:register-clients

This registers all ecosystem services (demo, home, path, way, guild, governance, learn, market, realm, scroll) as OAuth clients and writes credentials to oauth-credentials.json. Add each app's OAUTH_CLIENT_SECRET from that file to the app's .env.

To register a single client (e.g. home or demo) and auto-write its secret to the app's .env:

pnpm oauth:register-clients -- --client home
pnpm oauth:register-clients -- --client demo

Requires DATABASE_URL in apps/id.ritualos.com/.env.

---

Environment Variables Reference

Required for All Services

DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
SESSION_SECRET=min-32-character-secret

OAuth Configuration

OAUTH_CLIENT_ID=<service-name>  # demo, home, scroll, learn, path, etc.
OAUTH_CLIENT_SECRET=<from oauth:register-clients or oauth-credentials.json>
ID_SERVICE_URL=http://localhost:7000

For Credential Issuance

ID_ISSUER_API_KEY=<from-registration>
ID_ISSUER_ID=<service-name>

For Ledger Writes

LEDGER_API_URL=http://localhost:3011
ISSUER_API_KEY=<from-id-service>

---

Database Setup

Each service has its own database. Use Docker Compose for easy setup:

# From each service directory
docker-compose up -d

# Or create databases manually
createdb ritualos_id
createdb ritualos_path
createdb ritualos_ledger
# ... etc

Prisma Commands

npm run db:generate  # Generate Prisma client
npm run db:push      # Apply schema to database
npm run db:migrate   # Run migrations
npm run db:studio    # Open Prisma Studio GUI
npm run db:seed      # Seed test data (if available)

---

Testing the Flow

1. Visit Portal: http://localhost:3012
2. Click "Mark your name" → Redirects to ID service
3. Create account with wallet or email
4. Complete House Initiation → Assigned a House
5. Complete Archetype Revelation → Assigned an Archetype
6. Explore Path: http://localhost:4000 → Complete quests
7. Check Ledger: http://localhost:3013 → See receipts
8. Write a Scroll: http://localhost:3004 → Cultural expression

---

Common Issues

Port Already in Use

# Find process using port
lsof -i :3000
# Kill it
kill -9 <PID>

Database Connection Failed

# Check PostgreSQL is running
pg_isready

# Check connection string
psql $DATABASE_URL

OAuth Redirect Failed

1. Check ID_SERVICE_URL is correct
2. Check OAuth client is registered
3. Check redirect URIs include localhost

Prisma Client Not Generated

npm run db:generate
# Then restart the service

---

Next Steps

• Read the Ecosystem PRD
• Explore Architecture docs
• Review Security patterns

---

Last Updated: January 2026