Local setup

This page takes a clean machine to the point where every service is installed and its dependencies are running. It does not start the services — that's the next page, running the stack. The goal here is: toolchain in place, all four repos cloned, MongoDB and Redis up, dependencies synced, and a .env ready for each service.

The platform is four cooperating services — Console, Backend API, Voice fleet, and Dialler — around a shared data layer. If that split is new to you, read the system architecture first; it explains why the runtime services hold no durable state and re-fetch config every call.

Prerequisites

Install these once. The two Python services and the Dialler all run on the same toolchain; the Console runs on Node.

# git ships with Xcode CLT; otherwise:
brew install git

# uv — the Python package manager for all three Python services
brew install uv

# Node (current LTS) — for the Console
brew install node

# Docker Desktop — for local MongoDB + Redis
brew install --cask docker

# git
sudo apt-get update && sudo apt-get install -y git

# uv (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Node via nvm (current LTS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

# Docker Engine — follow https://docs.docker.com/engine/install/

Verify the toolchain before you go further:

git --version
uv --version          # should resolve Python 3.12 for these projects
node --version        # current LTS
docker --version

Clone the repositories

All four repos live in the oriserve1 Bitbucket workspace. Make sure your SSH key is added to your Bitbucket account, then clone them side by side into one parent directory — they reference each other at runtime over the network, not the filesystem, but keeping them together makes life easier.

The prose names map to the real Bitbucket repos like this:

# pick a workspace dir
mkdir -p ~/ori && cd ~/ori

git clone git@bitbucket.org:oriserve1/vox-backend.git    # Backend API
git clone git@bitbucket.org:oriserve1/vox-frontend.git   # Console
git clone git@bitbucket.org:oriserve1/vox-agents.git     # Voice fleet
git clone git@bitbucket.org:oriserve1/vox-dialler.git    # Dialler

Start the local data layer

The Backend stores all durable records in MongoDB and uses Redis for queues and runtime cache. The Dialler shares the same MongoDB database as the Backend. Run both in Docker — it's the quickest way to get the exact ports the services expect.

services:
  mongo:
    image: mongo:7
    container_name: ori-mongo
    ports:
      - "27017:27017"
    volumes:
      - ori-mongo-data:/data/db

  redis:
    image: redis:7
    container_name: ori-redis
    ports:
      - "6379:6379"
    volumes:
      - ori-redis-data:/data

volumes:
  ori-mongo-data:
  ori-redis-data:

docker compose up -d          # start both in the background
docker compose ps             # confirm both are healthy
docker compose down           # stop (data is kept in the volumes)

docker run -d --name ori-mongo \
  -p 27017:27017 \
  -v ori-mongo-data:/data/db \
  mongo:7

docker run -d --name ori-redis \
  -p 6379:6379 \
  -v ori-redis-data:/data \
  redis:7

These map straight onto the connection defaults the services ship with — mongodb://localhost:27017 and redis://localhost:6379 — so no extra wiring is needed for local work.

First-time install per service

Each repo installs independently. The three Python services use uv sync; the Console uses npm install. Every service also reads a .env, which you copy from the checked-in .env.example. The variable meanings live on the configuration page — we point you there rather than repeat them, so there's a single source of truth.

cd ~/ori/vox-backend
uv sync
cp .env.example .env

cd ~/ori/vox-frontend
npm install
cp .env.example .env     # then set VITE_API_URL to http://localhost:8080

cd ~/ori/vox-agents
uv sync
cp .env.example .env

cd ~/ori/vox-dialler
uv sync
cp .env.example .env

Telephony and the Dialler are optional for local

What this means in practice for local development:

What's next

Everything is installed and the data layer is up. Now bring the services to life.