Skip to content

Local Development Setup

Get your development environment running in under 10 minutes.

Time to read: ~5 min Prerequisites: Python 3.14+, Node.js 20.19+ or 22.12+, Docker/Podman

This document provides a streamlined guide for setting up local development. For comprehensive setup details, see Development Setup.

Quick Setup

# Clone repository
git clone https://github.com/your-org/home-security-intelligence.git
cd home-security-intelligence

# Run automated setup
python setup.py

The setup script:

  1. Creates Python virtual environment (.venv)
  2. Installs backend dependencies
  3. Installs frontend dependencies
  4. Configures pre-commit hooks

Manual Setup

1. Backend

# Install dependencies using uv (recommended - 10-100x faster than pip)
# Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --extra dev

# This creates .venv and installs all dependencies from pyproject.toml
# Activate the environment for manual commands
source .venv/bin/activate

2. Frontend

cd frontend
npm install
cd ..

3. Pre-commit Hooks

# Install hooks (CRITICAL - never bypass)
pre-commit install
pre-commit install --hook-type pre-push

4. Infrastructure

# Start PostgreSQL and Redis
podman-compose -f docker-compose.prod.yml up -d postgres redis

# Verify
podman ps

5. Environment

# Run the setup script to generate .env with secure credentials (recommended)
python setup.py

# Or manually copy and edit:
cp .env.example .env

# Generate a secure password: openssl rand -base64 32
# Then edit .env:
# DATABASE_URL=postgresql+asyncpg://security:<your-password>@localhost:5432/security
# REDIS_URL=redis://localhost:6379/0

Running the Stack

Backend:

source .venv/bin/activate
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Frontend:

cd frontend
npm run dev

Full stack with AI (optional):

./scripts/dev.sh

Verification

# Run validation suite
./scripts/validate.sh

# Backend tests
pytest backend/tests/ -v

# Frontend tests
cd frontend && npm test

Next Steps

See Also

Back to Developer Hub