Installation

Rokks runs as a Docker Compose stack. All services are containerized. You need Docker Desktop (Mac/Windows) or Docker Engine + Compose (Linux).

Prerequisites

Requirement	Minimum version
Docker Engine	24.0
Docker Compose	2.20
Node.js (host, for dev tooling)	20 LTS
4 GB RAM	Available to Docker
10 GB disk	For data volumes

A Google Cloud Platform project with Firestore and Cloud Storage is required for the default document and blob backend. Alternative: use MonIO (the bundled MongoDB-based document backend) if you prefer fully on-prem storage.

Clone and configure

git clone https://github.com/example/Rokks.git
cd Rokks
cp .env.example .env

Edit .env to fill in:

REGISTRY_MASTER_KEY — a random secret, 32+ characters
INTERNAL_SERVICE_SECRET — a random secret, 32+ characters
All *_BOOTSTRAP_TOKEN values — one per service, each unique

Bootstrap tokens are one-time startup credentials. Generate them with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Run the command once per token.

First boot

docker compose up -d

On first boot:

The Registry service initializes its SQLite database and seeds default service entries.
Each service fetches its configuration from the Registry via GET /discover/:serviceId.
The frontend is available at http://localhost:3000.

Wait ~30 seconds for all services to pass their health checks:

docker compose ps

All services should show healthy.

Connect to Firestore

Navigate to http://localhost:3000 → Settings → Environments → Edit → Credentials tab.

Enter your Firebase / GCP credentials:

firebase_api_key
firebase_project_id
firebase_auth_domain
gcp_storage_bucket

Save. The Doc Gateway will reconnect automatically.

Development mode

For hot-reload on both frontend (Vite HMR) and backends (nodemon polling):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Backend source is live-mounted into each container. Edit a backend file and the service reloads within 2 seconds.

Frontend is served by Vite at http://localhost:3000. HTTPS with HTTP/2 is available at https://localhost:3443 (install the dev CA from http://localhost:3000/ca.crt).

Production deployment

For production, build the frontend image and deploy all services:

docker compose build
docker compose up -d

The frontend container runs nginx, serves the compiled SPA, and proxies API traffic to the backend mesh. No Node.js runtime is needed at runtime.