Development Environment Setup¶

This guide walks you through setting up a complete development environment for the Home Security Intelligence project.

Prerequisites¶

Before starting, ensure you have the following installed:

Required Software¶

Optional (for GPU features)¶

Hardware Recommendations¶

• RAM: 16GB minimum, 32GB recommended
• GPU: NVIDIA RTX A5500 or equivalent (24GB VRAM) for full AI pipeline
• Disk: 50GB free space for models, containers, and data

Quick Setup¶

The fastest way to set up your development environment:

# Clone the repository
git clone https://github.com/mikesvoboda/home_security_intelligence.git
cd home_security_intelligence

# Run the automated setup script
./scripts/setup.sh

This script (scripts/setup.sh) automatically:

1. Checks all prerequisites
2. Creates a Python virtual environment (.venv)
3. Installs backend dependencies
4. Installs frontend dependencies
5. Sets up pre-commit hooks
6. Verifies the installation

Manual Setup¶

If you prefer step-by-step control or the automated script fails:

1. Clone the Repository¶

git clone https://github.com/mikesvoboda/home_security_intelligence.git
cd home_security_intelligence

2. Backend Setup¶

Create and activate a Python virtual environment:

# 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
# Development tools (pre-commit, ruff, mypy, pytest) are included

Note: This project uses uv for Python dependency management with pyproject.toml as the dependency source. The uv.lock file ensures reproducible builds.

3. Frontend Setup¶

cd frontend
npm install
cd ..

Script dependency graph showing relationships between setup scripts, validation tools, and test runners.

4. Pre-commit Hooks¶

Install pre-commit hooks to enforce code quality on every commit:

# Install standard pre-commit hooks
pre-commit install

# Install pre-push hooks for tests (CRITICAL - do not skip)
pre-commit install --hook-type pre-push

The pre-commit configuration (.pre-commit-config.yaml) includes:

5. Environment Configuration¶

Create a .env file from the example:

cp .env.example .env

Key environment variables to configure:

# Database (PostgreSQL required)
# IMPORTANT: Run python setup.py to generate .env with a secure password, or set manually:
# Generate password: openssl rand -base64 32
DATABASE_URL=postgresql+asyncpg://security:<your-password>@localhost:5432/security

# Redis
REDIS_URL=redis://localhost:6379/0

# Camera upload directory
FOSCAM_BASE_PATH=/export/foscam

# AI service endpoints (optional for dev)
YOLO26_URL=http://localhost:8095
NEMOTRON_URL=http://localhost:8091

6. Start Infrastructure Services¶

Using Docker or Podman:

# Docker
docker compose -f docker-compose.prod.yml up -d postgres redis

# OR Podman
podman-compose -f docker-compose.prod.yml up -d postgres redis

Or configure local services manually.

Verifying the Setup¶

Run the verification script:

./scripts/validate.sh

This runs (scripts/validate.sh):

1. Ruff linting - Python code style
2. Ruff formatting - Python code formatting
3. MyPy - Python type checking
4. Pytest - Backend tests with 95% combined coverage
5. ESLint - Frontend linting
6. TypeScript - Frontend type checking
7. Prettier - Frontend formatting
8. Vitest - Frontend tests

All checks must pass before committing code.

Development Workflow¶

Starting the Development Servers¶

Backend:

source .venv/bin/activate
python -m backend.main

# Or with hot reload
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Frontend:

cd frontend
npm run dev

Full stack with AI services:

./scripts/dev.sh

Running Tests¶

# Backend tests
pytest backend/tests/ -v

# Frontend tests
cd frontend && npm test

# Full test suite with coverage
./scripts/test-runner.sh

See testing.md for comprehensive test documentation.

IDE Configuration¶

VS Code (Recommended)¶

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "python.formatting.provider": "none",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "eslint.workingDirectories": ["frontend"],
  "typescript.tsdk": "frontend/node_modules/typescript/lib"
}

Recommended extensions:

• Python: ms-python.python, charliermarsh.ruff
• Frontend: esbenp.prettier-vscode, dbaeumer.vscode-eslint
• General: bradlc.vscode-tailwindcss, eamodio.gitlens

PyCharm / WebStorm¶

1. Set Python interpreter to .venv/bin/python
2. Enable Ruff as external tool for linting
3. Configure ESLint in frontend directory
4. Enable Prettier for TypeScript files

Common Issues¶

Pre-commit Fails on First Run¶

Pre-commit may need to download hooks on first run:

pre-commit run --all-files

If hooks fail, fix the issues before committing. Never use --no-verify.

Database Connection Errors¶

Ensure PostgreSQL is running:

# Docker
docker compose -f docker-compose.prod.yml up -d postgres

# OR Podman
podman-compose -f docker-compose.prod.yml up -d postgres

Check connection:

psql postgresql://security:<your-password>@localhost:5432/security

Import Errors in Tests¶

Activate the virtual environment:

source .venv/bin/activate

The test configuration automatically adds backend to the Python path.

Node Modules Issues¶

Clear and reinstall:

cd frontend
rm -rf node_modules package-lock.json
npm install

Enabling HTTPS¶

For secure local development or production deployment, you can enable HTTPS:

# Generate self-signed certificate for development
./scripts/generate-certs.sh

# Enable HTTPS
echo "SSL_ENABLED=true" >> .env

# Restart frontend
docker compose -f docker-compose.prod.yml restart frontend

Access at https://localhost:443. See SSL/HTTPS Configuration for complete documentation.

Next Steps¶

• Testing Guide - Learn the test strategy and how to write tests
• Contributing Guide - Understand the PR process
• Code Patterns - Learn key patterns used in the codebase
• SSL/HTTPS Configuration - Enable HTTPS for secure connections

Related Documentation¶

• CLAUDE.md - Project instructions and rules
• Backend AGENTS.md - Backend architecture overview
• Frontend AGENTS.md - Frontend architecture overview