Development Setup

Overview

This guide covers setting up a complete development environment for the Olis monorepo, including all necessary tools, configurations, and best practices.

System Requirements

Operating Systems

Windows 10/11
macOS 12+
Ubuntu 20.04+ / Debian-based Linux

Hardware

8GB RAM minimum (16GB recommended)
10GB free disk space
Multi-core processor

Required Tools

Core Development Tools

Node.js & pnpm
Python
Rust
Git

# Install Node.js v18+ from https://nodejs.org/

# Verify installation
node --version  # Should be v18.0.0 or higher

# Install pnpm globally
npm install -g pnpm@9.15.4

# Verify pnpm
pnpm --version

Why pnpm?

Efficient disk space usage
Faster installs than npm/yarn
Better monorepo support
Strict dependency resolution

# Install Python 3.9+ from https://python.org/

# Verify installation
python --version  # Should be 3.9.0 or higher

# Install pip (usually included)
python -m ensurepip --upgrade

# Optional: Install poetry for better dependency management
pip install poetry

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# On Windows, download from: https://rustup.rs/

# Verify installation
rustc --version
cargo --version

# Add common targets
rustup target add wasm32-unknown-unknown

# Install Git from https://git-scm.com/

# Verify installation
git --version

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Optional: Set up SSH keys
ssh-keygen -t ed25519 -C "your.email@example.com"

IDE Setup

Visual Studio Code (Recommended)

Install VS Code

Download from code.visualstudio.com

Install recommended extensions

// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-python.python",
    "rust-lang.rust-analyzer",
    "bradlc.vscode-tailwindcss",
    "nrwl.angular-console"
  ]
}

Install all at once:

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type “Extensions: Show Recommended Extensions”
Click “Install All”

Configure workspace settings

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "python.linting.enabled": true,
  "python.formatting.provider": "black",
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  }
}

Repository Setup

Clone the repository

git clone https://github.com/yourusername/olis-monorepo.git
cd olis-monorepo

Install dependencies

# Install JavaScript/TypeScript dependencies
pnpm install

# Install Python dependencies
pip install -r requirements.txt

# Or with poetry
poetry install

Set up environment variables

# Copy example env file
cp .env.example .env

# Edit with your values
nano .env  # or use your preferred editor

Key variables to configure:

# API Configuration
OLIS_API_URL=http://localhost:8000

# Intent Detection
OLIS_INTENT_MODEL=phi3
OLIS_INTENT_REMOTE_URL=http://localhost:11434

# Document Folder
OLIS_DOCS_FOLDER=/path/to/your/docs

# Database (for API server)
DATABASE_URL=postgresql://user:pass@localhost/olis
REDIS_URL=redis://localhost:6379

Build native modules

cd apps/electron-client
pnpm run sidecar:build
cd ../..

Verify installation

# Run tests
pnpm test

# Lint code
pnpm lint

# View project graph
pnpm nx graph

Docker Setup (Optional)

For containerized development:

Docker Desktop
Docker Compose Services

Install Docker Desktop

Verify installation:

docker --version
docker-compose --version

Start Docker Desktop

# docker-compose.local.yml
version: '3.8'

services:
  api:
    build: ./apps/api-server
    ports:
      - "8000:8000"
    volumes:
      - ./apps/api-server:/app
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=redis://redis:6379

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  postgres:
    image: postgres:15-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: olis
      POSTGRES_PASSWORD: olis
      POSTGRES_DB: olis

  vector-db:
    image: qdrant/qdrant
    ports:
      - "6333:6333"

Start services:

docker-compose -f docker-compose.local.yml up -d

Workflow Tools

Nx Console

Nx Console provides a GUI for running Nx commands:

Install extension

Search for “Nx Console” in VS Code extensions

Access the console

Click the Nx icon in the sidebar or use Command Palette

Run tasks visually

Select a project
Choose a task (build, serve, test, lint)
Click Run

Pre-commit Hooks

Set up Git hooks for quality checks:

# Install husky
pnpm add -D husky

# Initialize husky
pnpm husky install

# Add pre-commit hook
pnpm husky add .husky/pre-commit "pnpm lint-staged"

Configure lint-staged in package.json:

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
    "*.py": ["black", "isort"],
    "*.{json,md,yml,yaml}": ["prettier --write"]
  }
}

Development Workflow

Daily Development

Running Applications

Electron Client
API Server
Chrome Extension

cd apps/electron-client

# Development mode with hot reload
pnpm run electron:dev

# Or just the Next.js dev server
pnpm run dev

cd apps/api-server

# With uvicorn
uvicorn main:app --reload

# With Docker Compose
docker-compose -f ../../docker-compose.local.yml up api

cd apps/chrome-extension

# Build once
pnpm run build

# Or watch mode for development
pnpm run watch

Then load from chrome://extensions/

Running Tests

# Run all tests
pnpm test

# Run tests for specific app
pnpm nx test electron-client
pnpm nx test api-server

# Watch mode
pnpm nx test electron-client --watch

# With coverage
pnpm nx test electron-client --coverage

Troubleshooting

pnpm install fails

# Clear pnpm cache
pnpm store prune

# Delete node_modules and lockfile
rm -rf node_modules pnpm-lock.yaml

# Reinstall
pnpm install

# If still failing, check Node version
node --version  # Should be 18+

Rust build errors

# Update Rust
rustup update

# Check for missing build tools
# Windows: Install Visual Studio Build Tools
# macOS: xcode-select --install
# Linux: sudo apt install build-essential

# Clean and rebuild
cargo clean
cargo build --release

Python dependency conflicts

# Use virtual environment
python -m venv venv
source venv/bin/activate  # Unix
.\venv\Scripts\activate   # Windows

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

Nx commands not working

# Clear Nx cache
pnpm nx reset

# Reinstall dependencies
pnpm install

# Update Nx
pnpm add -D nx@latest

Next Steps

Building

Learn how to build for production

Testing

Write and run tests

Contributing

Contribution guidelines

Architecture

Understand the architecture

Get Started

Applications

Development

Features

API Documentation

Endpoints

Overview

System Requirements

Operating Systems

Hardware

Required Tools

Core Development Tools

IDE Setup

Visual Studio Code (Recommended)

Repository Setup

Docker Setup (Optional)

Workflow Tools

Nx Console

Pre-commit Hooks

Development Workflow

Daily Development

Running Applications

Running Tests

Troubleshooting

Next Steps

Building

Testing

Contributing

Architecture

​Overview

​System Requirements

Operating Systems

Hardware

​Required Tools

​Core Development Tools

​IDE Setup

​Visual Studio Code (Recommended)

​Repository Setup

​Docker Setup (Optional)

​Workflow Tools

​Nx Console

​Pre-commit Hooks

​Development Workflow

​Daily Development

​Running Applications

​Running Tests

​Troubleshooting

​Next Steps

Building

Testing

Contributing

Architecture

Overview

System Requirements

Required Tools

Core Development Tools

IDE Setup

Visual Studio Code (Recommended)

Repository Setup

Docker Setup (Optional)

Workflow Tools

Nx Console

Pre-commit Hooks

Development Workflow

Daily Development

Running Applications

Running Tests

Troubleshooting

Next Steps