Skip to content

Installation Guide

Complete installation guide for setting up FireBreak on your local machine.

System Requirements

Hardware Requirements

  • CPU: 2+ cores recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 2GB free space

Software Requirements

Software Version Purpose
Node.js 20+ JavaScript runtime for frontend and Wrangler
npm 10+ Package manager
Python 3.11+ Backend runtime
pip Latest Python package manager
Git Latest Version control

Optional Tools

  • Wrangler CLI: For Cloudflare Workers (installed via npm)
  • Playwright: For E2E testing (installed via npm)
  • pytest: For backend testing (installed via pip)

Installation Steps

1. Install Node.js and npm

# Using Homebrew
brew install node@20

# Verify installation
node --version  # Should be 20.x.x
npm --version   # Should be 10.x.x

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version
  1. Download Node.js installer from nodejs.org
  2. Run installer and follow prompts
  3. Verify in PowerShell: 
    node --version
npm --version

2. Install Python

# Using Homebrew
brew install python@3.11

# Verify installation
python --version  # Should be 3.11.x
pip --version

# Add deadsnakes PPA for Python 3.11
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11 python3.11-venv python3-pip

# Verify installation
python3.11 --version
pip3 --version
  1. Download Python installer from python.org
  2. Run installer, check "Add Python to PATH"
  3. Verify in PowerShell: 
    python --version
pip --version

3. Clone the Repository

# Clone the repository
git clone https://github.com/firebreakrisk/firestorm.git
cd firestorm

# Verify structure
ls -la

You should see: 

backend/
frontend/
qa/
tenants/
infrastructure/
shared/
docs/

4. Install Backend Dependencies

cd backend

# Install Wrangler CLI and Node dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

# Install development/testing dependencies
pip install -r requirements-dev.txt

# Verify Wrangler installation
npx wrangler --version

# Verify Python packages
pip list | grep pytest
pip list | grep cloudflare

cd ..

5. Install Frontend Dependencies

cd frontend/core

# Install npm dependencies
npm install

# Verify installation
npm list --depth=0

cd ../..

6. Install QA Dependencies

cd qa

# Install Python testing dependencies
pip install -r requirements.txt

# Install Playwright browsers
npx playwright install --with-deps

# Verify Playwright installation
npx playwright --version

cd ..

Verify Installation

Backend Verification

cd backend

# Check Python syntax
python -c "import sys; print(f'Python {sys.version}')"

# Run a simple smoke test
pytest tests/test_smoke.py -v

# Start development server (Ctrl+C to stop)
npx wrangler dev --env local

Frontend Verification

cd frontend/core

# Check TypeScript compilation
npm run type-check

# Run tests
npm test

# Start development server (Ctrl+C to stop)
npm run dev

QA Verification

cd qa

# Run smoke tests
pytest -v -m smoke

# Run Playwright smoke tests
npx playwright test --grep smoke

Environment Setup

Create Environment Files

# Backend environment (local development)
cd backend
cp .env.example .env  # If .env.example exists

Edit .env with your local settings: 

ENVIRONMENT=local
API_VERSION=v1
DEBUG=true

# Optional: API keys for testing (can use mock data without these)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GOOGLE_API_KEY=...

Configure Wrangler

The backend includes a wrangler.jsonc configuration file. Review it:

cd backend
cat wrangler.jsonc

For local development, you don't need to modify this file.

Common Installation Issues

Issue: Node.js Version Too Old

Error: error: The engine "node" is incompatible with this module

Solution: 

# Check current version
node --version

# Update to Node 20+
brew upgrade node  # macOS
# OR download from nodejs.org

Issue: Python Module Not Found

Error: ModuleNotFoundError: No module named 'pytest'

Solution: 

cd backend
pip install -r requirements.txt -r requirements-dev.txt

# If using virtual environment:
python -m venv venv
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate  # Windows
pip install -r requirements.txt -r requirements-dev.txt

Issue: Playwright Browsers Not Installed

Error: browserType.launch: Executable doesn't exist

Solution: 

cd qa
npx playwright install --with-deps

Issue: Port Already in Use

Error: Error: listen EADDRINUSE: address already in use :::8787

Solution: 

# Find and kill process using port 8787
lsof -ti:8787 | xargs kill -9  # macOS/Linux

# OR use a different port
npx wrangler dev --env local --port 8788

Using Python virtual environments is recommended to isolate dependencies:

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate  # Windows

# Install dependencies
cd backend
pip install -r requirements.txt -r requirements-dev.txt

cd ../qa
pip install -r requirements.txt

# Deactivate when done
deactivate

Next Steps

Now that installation is complete:

  1. Configuration Guide - Configure your environment
  2. Quick Start - Start the development servers
  3. Local Development - Set up your development workflow
  4. First Deployment - Deploy to staging

Additional Resources