Local Development Setup

This guide walks you through getting Objectuve running locally for development.

Prerequisites

Tool	Version	Notes
Ruby	4.0+	Managed via rbenv or asdf recommended
Node.js	20+	LTS recommended
PostgreSQL	15+	Homebrew: brew install postgresql@15
Redis	7+	Homebrew: brew install redis
Bundler	Latest	gem install bundler

Option A: Quick setup script

The fastest way to get running:

git clone https://github.com/objectuve-softworks/enkidu.git
cd enkidu
./setup.sh

This script:

1. Installs Bundler and Rails
2. Runs bundle install in rails_api/
3. Creates and seeds the database (rails db:setup)
4. Runs npm install in ionic_frontend/

Option B: Docker

If you prefer containers:

docker-compose up --build

This starts:

• PostgreSQL on port 5432
• Redis on port 6379
• Rails API on port 3000
• Frontend on port 8282
• LiteLLM proxy on port 4000
• Agent Runner (AI Workforce) on port 4001

Option C: Manual setup

Backend

cd rails_api

# Install dependencies
bundle install

# Create and seed database
# Ensure PostgreSQL is running first
bin/rails db:setup

# Start the server
bin/rails server
# → http://localhost:3000

Frontend (Ionic App)

cd ionic_frontend

# Install dependencies
npm install

# Start Vite dev server
npm run dev
# → http://localhost:5173

Admin Dashboard

cd admin_dashboard

# Install dependencies
npm install

# Start Vite admin server
npm run dev
# → http://localhost:5174 (Vite auto-increments from 5173 if the frontend
#   dev server above is already running; starting standalone lands on 5173)

Environment variables

Backend (rails_api/.env)

Create a .env file in rails_api/ with these values:

# Required
CLERK_SECRET_KEY=sk_test_...          # Clerk secret key for JWT verification

# Database (defaults work for local PostgreSQL)
DATABASE_HOST=localhost
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=

# Optional
REDIS_URL=redis://localhost:6379/1    # For Sidekiq and ActionCable
FALLBACK_AUTH_SECRET=...              # Enables /sign-in?fallback for testing
MAILTRAP_API_TOKEN=...                # Transactional email (dev can skip)
SENTRY_DSN=...                        # Error tracking (dev can skip)
GOOGLE_API_KEY=...                    # Google API integration

Frontend (ionic_frontend/.env)

VITE_API_URL=http://localhost:3000
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

Admin Dashboard (admin_dashboard/.env)

VITE_API_URL=http://localhost:3000/graphql
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

Get Clerk keys from the Clerk Dashboard.

Running services

After setup, start the backend and frontend in separate terminals:

# Terminal 1: Backend
cd rails_api
bin/rails server

# Terminal 2: Frontend App
cd ionic_frontend
npm run dev

# Terminal 3: Admin Dashboard
cd admin_dashboard
npm run dev

# Optional — Terminal 4: Sidekiq (background jobs)
cd rails_api
bundle exec sidekiq

Running tests

# Backend
cd rails_api
bundle exec rspec

# Frontend
cd ionic_frontend
npm run test:unit -- --run

# Lint
cd rails_api && bundle exec rubocop
cd ionic_frontend && npm run lint

See Testing for full test infrastructure details and coverage targets.

Storybook & Design System

The deployed Storybook is at storybook.objectuve.com and the design system gallery at design.objectuve.com.

To run Storybook locally:

cd ionic_frontend
npm run storybook
# → http://localhost:6006

AI Development (Coach, Moderation, Workforce)

The AI subsystems (coach, content moderation, AI Workforce agents) call an LLM proxy on port 4000. Three tiers are available for local dev — pick whichever fits your task:

Tier	Command	Cost	What it does
Mock (default)	dev/start-ai.sh mock	Free	Smart mock server returning realistic, schema-valid responses
LiteLLM	dev/start-ai.sh litellm	Real $	Native LiteLLM proxy routing to Gemini/Claude (mirrors staging)
Direct Anthropic	Set env vars in agent_runner/.env	Real $	Agent Runner talks directly to Anthropic API

Tier 1: Smart Mock (recommended for daily dev)

No API keys, no Docker, no Python. Returns goal-specific milestones, valid insight cards, and moderation JSON:

# Terminal 1: Mock LLM server
dev/start-ai.sh mock         # port 4000

# Terminal 2: Rails API
cd rails_api && rails s       # port 3000

# Terminal 3: Frontend
cd ionic_frontend && npm run dev  # port 5173

The mock moderation endpoint flags content containing trigger words (spam, hate, violence) so you can test both clean and flagged paths.

Tier 2: Real LiteLLM (integration testing)

Uses real LLM providers via the same LiteLLM proxy used in staging, running natively (no Docker):

pip install litellm           # one-time
GOOGLE_API_KEY=xxx ANTHROPIC_API_KEY=xxx dev/start-ai.sh litellm

Config: infra/litellm/config.local.yaml (no Postgres/Redis dependency).

Tier 3: AI Workforce Agent Runner

The Agent Runner is a separate TypeScript service that executes AI employee tasks:

# Terminal: Agent Runner with hot reload
dev/start-ai.sh agent        # port 4001, uses tsx watch

Configure agent_runner/.env (copy from agent_runner/.env.example):

• Mock mode: ANTHROPIC_BASE_URL=http://localhost:4000 (points at Tier 1 or 2)
• Real mode: ANTHROPIC_BASE_URL=https://api.anthropic.com + real ANTHROPIC_API_KEY

Testing the webhook loop

Test the Rails webhook receiver without running a real agent:

# 1. Create a run in Rails console:
#    result = AiWorkforce::TriggerRun.call(employee_id: AiEmployee.first.public_id, triggered_by: 'console')
#    run_id = result.details[:run_id]  # or: AiRun.last.public_id

# 2. Simulate the webhook callback:
dev/start-ai.sh webhook <run_public_id>          # success
dev/start-ai.sh webhook <run_public_id> failed    # failure

Environment variables

Add to rails_api/.env:

LITELLM_URL=http://localhost:4000
LITELLM_MASTER_KEY=sk-local-dev-only
RAILS_WEBHOOK_SECRET=local-dev-webhook-secret
AGENT_RUNNER_URL=http://localhost:4001
AGENT_RUNNER_SECRET=local-dev-webhook-secret

See rails_api/.env.example and agent_runner/.env.example for full variable reference.

Common issues

Database connection errors

Ensure PostgreSQL is running: brew services start postgresql@15 (macOS) or sudo systemctl start postgresql (Linux).

Clerk token errors

If you see JWT verification failures, ensure CLERK_SECRET_KEY is set in rails_api/.env and VITE_CLERK_PUBLISHABLE_KEY is set in ionic_frontend/.env.

Port conflicts

The default ports are 3000 (API), 5173 (frontend), and 6006 (Storybook). If any are in use, Vite will auto-increment the frontend port. For the API, use bin/rails server -p 3001.

Demo login

Visit /sign-in?demo to use the demo account without Clerk credentials. Requires FALLBACK_AUTH_SECRET to be set in the backend .env.

Last updated: 2026-07-10 (docs-drift remediation — added missing redis, litellm, agent_runner services to the docker-compose up --build list)