RitualOSDocs
referenceintermediate

PORT_CONFIGURATION

Documentation for PORT_CONFIGURATION

5 min read
v3.0
reference

RitualOS Ecosystem Port Configuration

This document defines all ports used across the RitualOS ecosystem to avoid conflicts.

Application Ports

ServicePortTypeNotes
id.ritualos.com (frontend)3000Vite dev server
id.ritualos.com (backend)3001Express server
api.ritualos.com3002Express server
path.ritualos.com3003Next.js app
scroll.ritualos.com3004(assumed)
governance.ritualos.com3005(assumed)
ledger.ritualos.com (frontend)3013Next.js app
ledger.ritualos.com (backend)3010Express server

Database Ports

ServicePortDatabasePurpose
id.ritualos.com / api.ritualos.com5432ritualos_idPrimary identity database
path.ritualos.com5434ritualos_gameGame/quest database
ledger.ritualos.com5441ritualos_ledgerImmutable ledger database

Note: Port 5433 is mentioned in some configs but should be avoided to prevent conflicts.

Prisma Studio Ports

ServicePortURL
id.ritualos.com5555http://localhost:5555
path.ritualos.com5556http://localhost:5556

Production URLs

All services use HTTPS in production:

ServiceProduction URL
id.ritualos.comhttps://id.ritualos.com
api.ritualos.comhttps://api.ritualos.com
path.ritualos.comhttps://path.ritualos.com
ledger.ritualos.comhttps://ledger.ritualos.com

Cross-Service Integration URLs (Development)

From ServiceTo ServiceURL
path.ritualos.comid.ritualos.comhttp://localhost:3001
path.ritualos.comapi.ritualos.comhttp://localhost:3002
path.ritualos.comledger.ritualos.comhttps://ledger.ritualos.com (uses production URL)
path.ritualos.comlearn.ritualos.comhttp://localhost:3002
path.ritualos.comscroll.ritualos.comhttp://localhost:3004
path.ritualos.comgovernance.ritualos.comhttp://localhost:3005

Port Conflicts to Avoid

Do not use these ports for new services:

  • 3000-3005 - Reserved for core services
  • 5432-5441 - Reserved for databases
  • 5555-5556 - Reserved for Prisma Studio

Recommended ranges:

  • New applications: 3100-3199
  • New databases: 5500-5599
  • New studio instances: 5600-5699

Starting Services in Order

To avoid connection errors, start services in this order:

  1. Databases - PostgreSQL instances on ports 5432, 5434, 5441
  2. ID Service Backend - Port 3001 (auth, OAuth, credentials)
  3. API Service - Port 3002 (credentials, badges, cards)
  4. Ledger Service Backend - Port 3010 (receipt writes)
  5. Path Service - Port 3003 (game logic, depends on ID/API)
  6. ID Service Frontend - Port 3000 (optional for local dev)
  7. Ledger Service Frontend - Port 3013 (optional admin UI)

Troubleshooting

"Port already in use" error

Windows:

netstat -ano | findstr :3001
# Kill process with: taskkill /PID <PID> /F

Linux/Mac:

lsof -ti:3001
# Kill process with: kill -9 <PID>

Connection refused

Check that the target service is running:

curl http://localhost:3001/health

Last Updated

2025-01-24 - Initial documentation

Last updated: 3/10/2026

Edit this page on GitHub →