Quick Start Guide¶

Get FireBreak up and running in 5 minutes. Actually 5 minutes.

Beginner Updated

What You'll Build

By the end of this guide, you'll have:

✅ FireBreak running locally on your machine
✅ Backend API responding to requests
✅ Frontend UI displaying in your browser
✅ All tests passing

Estimated time: 5-8 minutes (depending on your internet speed)

Prerequisites Check¶

Before we begin, make sure you have the tools. Halfway through without them hurts.

FireBreak Tip

Check versions with one command:

node --version && npm --version && python --version && git --version

We'll wait here.

Required:

# Check Node.js version (need 20+)
node --version  # v20.x.x or higher

# Check npm version (need 10+)
npm --version  # 10.x.x or higher

# Check Python version (need 3.11+)
python --version  # Python 3.11.x or 3.12.x

# Check Git
git --version  # Any recent version

Wrong Version?

Got an older version? No worries:

Node.js: Download from nodejs.org
Python: Download from python.org
Git: Download from git-scm.com

Step 1: Clone the Repository¶

git clone https://github.com/firebreakrisk/firestorm.git
cd firestorm

Step 2: Install Dependencies¶

Backend Dependencies¶

cd backend
npm install  # Install Wrangler and Node deps
pip install -r requirements.txt  # Install Python deps
pip install -r requirements-dev.txt  # Install dev/test deps
cd ..

Frontend Dependencies¶

cd frontend/core
npm install
cd ../..

QA Dependencies¶

cd qa
pip install -r requirements.txt
npx playwright install --with-deps
cd ..

Step 3: Start Local Development¶

Terminal 1: Backend API¶

cd backend
npx wrangler dev --env local

Access at: http://localhost:8787

Terminal 2: Frontend¶

cd frontend/core
npm run dev

Access at: http://localhost:5173

Step 4: Verify Installation¶

Test Backend Health¶

curl http://localhost:8787/api/v1/health

Expected response:

{
  "status": "healthy",
  "version": "v1",
  "environment": "local",
  "service": "firestorm-backend"
}

Test Frontend¶

Open http://localhost:5173 in your browser. You should see the FireBreak landing page.

Step 5: Run Tests¶

Backend Tests¶

cd backend
pytest tests/ -v

Frontend Tests¶

cd frontend/core
npm test

E2E Tests¶

cd qa
npx playwright test

Common Issues¶

Troubleshooting

Things don't always go smoothly. That's okay. Here's how to fix the usual suspects.

Port Already in Use¶

Port 8787 in use? Naturally.

# Find and kill the process
lsof -ti:8787 | xargs kill -9  # Backend
lsof -ti:5173 | xargs kill -9  # Frontend

# Or just use a different port
npx wrangler dev --env local --port 8788  # Backend on 8788

Python Module Not Found¶

# Ensure you're in the right directory
cd backend
pip install -r requirements.txt -r requirements-dev.txt

# Still not working? Try a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt

Playwright Browser Not Found¶

cd qa
npx playwright install --with-deps

# This downloads Chromium, Firefox, and WebKit
# Takes a few minutes. Grab coffee.

Why So Many Dependencies?

FireBreak uses geospatial libraries (numpy, rasterio, shapely) for terrain analysis. These have native dependencies. That's why the install takes longer than a typical Node.js app. It's worth it for the performance.

Next Steps¶

Now that you have FireBreak running locally:

Configuration Guide - Configure your environment variables
Local Development - Set up your development workflow
First Deployment - Deploy to staging
API Documentation - Explore the API

Quick Reference¶

Component	URL	Port
Backend API	http://localhost:8787	8787
Frontend	http://localhost:5173	5173
API Health	http://localhost:8787/api/v1/health	-
API Docs	http://localhost:8787/api/v1	-

Nice Work!

Congratulations! You now have FireBreak running locally.

Not bad, right? Test before production, though.

What's Next?¶

:material-cog:

Configuration

Set up environment variables and config files

Configure →

:material-code-braces:

Local Development

IDE setup, dev workflow, and debugging tips

Dev Setup →

:material-rocket-launch:

First Deployment

Deploy to Cloudflare Workers (staging)

Deploy →

:material-api:

API Docs

Explore endpoints and try API calls

API Reference →