---
title: Developer Setup
description: Complete guide to setting up TraceRTM for local development
keywords: [development, setup, installation, local, docker, prerequisites]
audience: developer
difficulty: intermediate
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { FileTree } from 'fumadocs-ui/components/file-tree';

# Developer Setup

Set up TraceRTM for local development in under 15 minutes.

## Prerequisites

<Callout type="warn" title="Required Software">
**Must Have**:
- **Git** 2.30+
- **Docker** 20.10+ and **Docker Compose** 2.0+ (for services)
- **Python** 3.11+ (backend)
- **Node.js** 18+ or **Bun** 1.0+ (frontend)
- **PostgreSQL** 15+ (can use Docker)

**Recommended**:
- **Redis** 7+ (can use Docker)
- **Neo4j** 5+ (optional, for graph queries)
- **Make** (for convenience commands)
- **curl** or **httpie** (for API testing)
</Callout>

### Version Verification

<Steps>
<Step>
### Check installed versions

```bash
git --version          # git version 2.40.0
docker --version       # Docker version 24.0.0
docker-compose --version # Docker Compose version 2.20.0
python --version       # Python 3.11.5
node --version         # v20.5.0 (or use bun --version)
psql --version         # psql (PostgreSQL) 15.3
```

</Step>

<Step>
### Install missing dependencies

<Tabs items={['macOS', 'Ubuntu/Debian', 'Windows']}>
  <Tab value="macOS">
    ```bash
    # Using Homebrew
    brew install git docker python@3.11 postgresql@15 redis

    # Install Bun (recommended over Node)
    curl -fsSL https://bun.sh/install | bash

    # Or use Node.js
    brew install node@20
    ```
  </Tab>

  <Tab value="Ubuntu/Debian">
    ```bash
    # Update package list
    sudo apt update

    # Install dependencies
    sudo apt install -y \
      git \
      docker.io \
      docker-compose \
      python3.11 \
      python3.11-venv \
      python3-pip \
      postgresql-15 \
      redis-server

    # Install Bun
    curl -fsSL https://bun.sh/install | bash

    # Or install Node.js 20
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs
    ```
  </Tab>

  <Tab value="Windows">
    **Use WSL2** (Windows Subsystem for Linux) for best experience:

    ```powershell
    # Install WSL2
    wsl --install -d Ubuntu-22.04

    # Then follow Ubuntu instructions above
    ```

    **Or use Windows native**:
    - Download [Git for Windows](https://git-scm.com/download/win)
    - Download [Docker Desktop](https://www.docker.com/products/docker-desktop)
    - Download [Python 3.11](https://www.python.org/downloads/)
    - Download [Node.js 20](https://nodejs.org/) or [Bun](https://bun.sh/)
    - Download [PostgreSQL 15](https://www.postgresql.org/download/windows/)
  </Tab>
</Tabs>

</Step>
</Steps>

## Quick Setup (Docker)

The fastest way to get started:

<Steps>
<Step>
### Clone repository

```bash
git clone https://github.com/your-org/tracertm.git
cd tracertm
```

</Step>

<Step>
### Configure environment

```bash
# Copy example environment file
cp .env.example .env

# Generate secure secrets
openssl rand -hex 32  # Use for JWT_SECRET
openssl rand -hex 32  # Use for DATABASE_PASSWORD
```

**Edit `.env`**:
```bash
# Database
DATABASE_URL=postgresql://tracertm:your_password@localhost:5432/tracertm
POSTGRES_USER=tracertm
POSTGRES_PASSWORD=your_password
POSTGRES_DB=tracertm

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

# Security
JWT_SECRET=your_generated_secret_here
JWT_ALGORITHM=HS256
JWT_EXPIRY_HOURS=24

# Neo4j (optional)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Environment
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=DEBUG
```

<Callout type="tip">
**Security Best Practices**:
- Never commit `.env` to git (already in `.gitignore`)
- Use different secrets for dev/staging/production
- Rotate secrets regularly
</Callout>

</Step>

<Step>
### Start services

```bash
# Start all services (PostgreSQL, Redis, Neo4j)
docker-compose up -d

# Verify services are running
docker-compose ps

# Expected output:
# NAME                    STATUS
# tracertm-postgres-1     Up 30 seconds
# tracertm-redis-1        Up 30 seconds
# tracertm-neo4j-1        Up 30 seconds
```

</Step>

<Step>
### Initialize database

```bash
# Run database migrations
make db-migrate

# Or manually:
cd src/backend
python -m alembic upgrade head
```

</Step>

<Step>
### Verify setup

```bash
# Check database connection
psql $DATABASE_URL -c "SELECT version();"

# Check Redis
redis-cli ping
# Expected: PONG

# Check Neo4j (optional)
curl http://localhost:7474
# Expected: Neo4j browser
```

</Step>
</Steps>

## Local Development Setup

For active development with hot reload:

<Steps>
<Step>
### Install backend dependencies

<Tabs items={['uv (Recommended)', 'pip + venv']}>
  <Tab value="uv (Recommended)">
    **Install uv** (ultra-fast Python package installer):

    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    **Create environment and install**:

    ```bash
    cd src/backend

    # Create virtual environment
    uv venv

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

    # Install dependencies
    uv pip install -r requirements.txt
    uv pip install -r requirements-dev.txt  # Dev tools
    ```
  </Tab>

  <Tab value="pip + venv">
    ```bash
    cd src/backend

    # Create virtual environment
    python -m venv .venv

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

    # Upgrade pip
    pip install --upgrade pip

    # Install dependencies
    pip install -r requirements.txt
    pip install -r requirements-dev.txt
    ```
  </Tab>
</Tabs>

</Step>

<Step>
### Install frontend dependencies

<Tabs items={['Bun (Recommended)', 'npm', 'pnpm', 'yarn']}>
  <Tab value="Bun (Recommended)">
    ```bash
    cd frontend

    # Install dependencies
    bun install

    # Faster than npm/yarn/pnpm!
    ```
  </Tab>

  <Tab value="npm">
    ```bash
    cd frontend
    npm install
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    cd frontend
    pnpm install
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    cd frontend
    yarn install
    ```
  </Tab>
</Tabs>

</Step>

<Step>
### Run development servers

Open **two terminal windows**:

**Terminal 1 - Backend**:
```bash
cd src/backend
source .venv/bin/activate

# Start FastAPI with hot reload
uvicorn src.main:app --reload --port 8000 --log-level debug

# Expected output:
# INFO:     Uvicorn running on http://127.0.0.1:8000
# INFO:     Application startup complete.
```

**Terminal 2 - Frontend**:
```bash
cd frontend

# Start Next.js dev server
bun dev  # or: npm run dev

# Expected output:
# ▲ Next.js 14.0.0
# - Local:        http://localhost:3000
# - Environments: .env.local
# ✓ Ready in 2.3s
```

</Step>

<Step>
### Verify development environment

**Test Backend**:
```bash
# Health check
curl http://localhost:8000/health
# Expected: {"status":"healthy","version":"1.0.0"}

# API docs (interactive)
open http://localhost:8000/docs  # Swagger UI
open http://localhost:8000/redoc # ReDoc
```

**Test Frontend**:
```bash
# Open in browser
open http://localhost:3000
```

<Callout type="success">
**Development environment ready!** 🚀

Backend: http://localhost:8000
Frontend: http://localhost:3000
</Callout>

</Step>
</Steps>

## Project Structure

<FileTree>
  <FileTree.Folder name="tracertm" defaultOpen>
    <FileTree.Folder name="src" defaultOpen>
      <FileTree.Folder name="backend" defaultOpen>
        <FileTree.Folder name="src">
          <FileTree.File name="main.py" />
          <FileTree.Folder name="api">
            <FileTree.File name="routes.py" />
            <FileTree.File name="dependencies.py" />
          </FileTree.Folder>
          <FileTree.Folder name="models">
            <FileTree.File name="requirement.py" />
            <FileTree.File name="link.py" />
          </FileTree.Folder>
          <FileTree.Folder name="services">
            <FileTree.File name="traceability.py" />
            <FileTree.File name="matrix.py" />
          </FileTree.Folder>
          <FileTree.Folder name="repositories">
            <FileTree.File name="requirement_repo.py" />
          </FileTree.Folder>
        </FileTree.Folder>
        <FileTree.Folder name="alembic">
          <FileTree.Folder name="versions">
            <FileTree.File name="001_initial.py" />
          </FileTree.Folder>
        </FileTree.Folder>
        <FileTree.File name="requirements.txt" />
        <FileTree.File name="alembic.ini" />
      </FileTree.Folder>
    </FileTree.Folder>

    <FileTree.Folder name="frontend" defaultOpen>
      <FileTree.Folder name="app">
        <FileTree.File name="layout.tsx" />
        <FileTree.File name="page.tsx" />
        <FileTree.Folder name="projects">
          <FileTree.File name="page.tsx" />
        </FileTree.Folder>
      </FileTree.Folder>
      <FileTree.Folder name="components">
        <FileTree.File name="TraceabilityMatrix.tsx" />
        <FileTree.File name="RequirementForm.tsx" />
      </FileTree.Folder>
      <FileTree.Folder name="lib">
        <FileTree.File name="api-client.ts" />
      </FileTree.Folder>
      <FileTree.File name="package.json" />
      <FileTree.File name="next.config.js" />
    </FileTree.Folder>

    <FileTree.Folder name="tests">
      <FileTree.Folder name="unit">
        <FileTree.File name="test_models.py" />
      </FileTree.Folder>
      <FileTree.Folder name="playwright">
        <FileTree.Folder name="api">
          <FileTree.File name="test_requirements.spec.ts" />
        </FileTree.Folder>
      </FileTree.Folder>
    </FileTree.Folder>

    <FileTree.File name="docker-compose.yml" />
    <FileTree.File name=".env.example" />
    <FileTree.File name="Makefile" />
    <FileTree.File name="README.md" />
  </FileTree.Folder>
</FileTree>

## Development Workflow

### Making Changes

<Steps>
<Step>
### Create feature branch

```bash
git checkout -b feature/your-feature-name
```

</Step>

<Step>
### Make changes

Edit files in your IDE. Hot reload is enabled:
- **Backend**: Changes auto-reload (uvicorn `--reload`)
- **Frontend**: Changes auto-refresh (Next.js Fast Refresh)

</Step>

<Step>
### Run tests

```bash
# Backend tests
cd src/backend
pytest tests/ -v

# Frontend tests
cd frontend
bun test

# E2E tests
bun test:e2e
```

</Step>

<Step>
### Check code quality

```bash
# Backend linting
cd src/backend
ruff check .
mypy src/

# Frontend linting
cd frontend
bun run lint
bun run type-check
```

</Step>

<Step>
### Commit changes

```bash
# Stage changes
git add .

# Commit with conventional commits format
git commit -m "feat: add traceability matrix export"

# Commit types:
# feat: New feature
# fix: Bug fix
# docs: Documentation
# test: Tests
# refactor: Code refactoring
# perf: Performance improvement
```

</Step>
</Steps>

### Database Migrations

When you change database models:

<Steps>
<Step>
### Create migration

```bash
cd src/backend

# Auto-generate migration from model changes
alembic revision --autogenerate -m "Add custom_fields to requirements"

# Or create empty migration
alembic revision -m "Add indexes"
```

</Step>

<Step>
### Review migration

Check generated file in `alembic/versions/`:

```python
# Example: alembic/versions/002_add_custom_fields.py

def upgrade():
    op.add_column('requirements',
        sa.Column('custom_fields', sa.JSON(), nullable=True)
    )
    op.create_index('ix_requirements_custom_fields',
                    'requirements',
                    ['custom_fields'],
                    postgresql_using='gin')

def downgrade():
    op.drop_index('ix_requirements_custom_fields')
    op.drop_column('requirements', 'custom_fields')
```

<Callout type="warn">
**Always review auto-generated migrations!** They may need manual adjustments.
</Callout>

</Step>

<Step>
### Apply migration

```bash
# Apply migration
alembic upgrade head

# Or rollback if needed
alembic downgrade -1
```

</Step>

<Step>
### Test migration

```bash
# Test upgrade
alembic upgrade head

# Test downgrade
alembic downgrade -1

# Test upgrade again
alembic upgrade head

# Both directions should work without errors!
```

</Step>
</Steps>

## Useful Commands

### Makefile Commands

```bash
# Development
make dev              # Start dev servers (tmux)
make dev-backend      # Start backend only
make dev-frontend     # Start frontend only

# Database
make db-migrate       # Run migrations
make db-reset         # Reset database (⚠️  data loss)
make db-seed          # Load sample data
make db-backup        # Backup database

# Testing
make test            # Run all tests
make test-backend    # Backend tests only
make test-frontend   # Frontend tests only
make test-e2e        # E2E tests
make test-coverage   # Generate coverage report

# Code Quality
make lint            # Run all linters
make format          # Auto-format code
make type-check      # Type checking

# Docker
make docker-build    # Build Docker images
make docker-up       # Start services
make docker-down     # Stop services
make docker-logs     # View logs

# Cleanup
make clean           # Remove build artifacts
make clean-db        # Remove database
make clean-all       # Full cleanup
```

### Manual Commands

**Backend**:
```bash
# Start server
uvicorn src.main:app --reload --port 8000

# Run specific test
pytest tests/test_models.py::test_requirement_creation -v

# Check types
mypy src/

# Format code
black src/
ruff check --fix src/
```

**Frontend**:
```bash
# Start dev server
bun dev

# Build for production
bun run build

# Run tests
bun test

# Lint
bun run lint:fix
```

## Troubleshooting

### Port Already in Use

```bash
# Find process using port
lsof -ti:8000  # Backend port
lsof -ti:3000  # Frontend port

# Kill process
kill -9 $(lsof -ti:8000)
```

### Database Connection Issues

```bash
# Check PostgreSQL is running
docker-compose ps postgres

# Check connection string
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1;"
```

### Migration Conflicts

```bash
# Check current migration
alembic current

# Check pending migrations
alembic history

# Reset to specific version
alembic downgrade <revision>
```

### Module Import Errors

```bash
# Ensure virtual environment is activated
which python  # Should point to .venv/bin/python

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
```

## Next Steps

<Callout type="success">
**Development environment ready!** Start building:
</Callout>

1. **[Architecture Overview](/docs/developer/architecture)** - Understand the system
2. **[Backend Development](/docs/developer/backend)** - Build APIs
3. **[Frontend Development](/docs/developer/frontend)** - Build UI
4. **[Testing Guide](/docs/developer/testing)** - Write tests
5. **[Contributing](/docs/developer/contributing)** - Submit PRs

## Getting Help

- 💬 [Discord #development](https://discord.gg/tracertm) - Ask questions
- 📚 [Developer Docs](/docs/developer) - Comprehensive guides
- 🐛 [GitHub Issues](https://github.com/tracertm/tracertm/issues) - Report bugs
- 📧 [dev@tracertm.io](mailto:dev@tracertm.io) - Direct support
