---
title: "Local Development"
description: "Set up TraceRTM for local development"
keywords: [development, local, setup, environment]
---

# Local Development

Set up TraceRTM for local development on your machine.

## Quick Start

### 1. Clone Repository

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

### 2. Set Up Python Environment

```bash
# Create virtual environment
python3 -m venv venv

# Activate (macOS/Linux)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"
```

### 3. Set Up Database

```bash
# Create database
createdb tracertm_dev

# Run migrations
python -m tracertm.cli migrate
```

### 4. Configure Environment

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

# Edit .env
nano .env
```

Set required variables:
```bash
DATABASE_URL=postgresql://localhost:5432/tracertm_dev
SECRET_KEY=dev-secret-key
JWT_SECRET=dev-jwt-secret
```

### 5. Start Development Server

```bash
# Start API server
uvicorn tracertm.api.main:app --reload --port 8000

# In another terminal, start frontend
cd docs-site
npm install
npm run dev
```

## Development Workflow

### Running Tests

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_items.py

# Run with coverage
pytest --cov=tracertm --cov-report=html
```

### Code Formatting

```bash
# Format code
black .

# Check formatting
black --check .

# Sort imports
isort .
```

### Linting

```bash
# Run linters
flake8 .
mypy .

# Auto-fix issues
autopep8 --in-place --aggressive --aggressive .
```

### Database Migrations

```bash
# Create migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1
```

## Development Tools

### Pre-commit Hooks

```bash
# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

### Debugging

```bash
# Run with debugger
python -m debugpy --listen 5678 -m uvicorn tracertm.api.main:app --reload
```

### Hot Reload

The development server automatically reloads on code changes when using `--reload` flag.

## Project Structure

```
tracertm/
├── src/
│   └── tracertm/
│       ├── api/          # API endpoints
│       ├── database/     # Database models
│       ├── services/     # Business logic
│       └── utils/        # Utilities
├── tests/                # Test files
├── docs-site/            # Documentation site
├── alembic/              # Database migrations
└── requirements.txt      # Dependencies
```

## Common Tasks

### Create New API Endpoint

1. Add route in `src/tracertm/api/main.py`
2. Create service method if needed
3. Add tests
4. Update documentation

### Add Database Model

1. Create model in `src/tracertm/database/models/`
2. Create migration: `alembic revision --autogenerate`
3. Apply migration: `alembic upgrade head`

### Run Database Seeding

```bash
# Seed development data
python scripts/seed_dev_data.py
```

## Troubleshooting

### Database Connection Issues

```bash
# Check PostgreSQL is running
pg_isready

# Test connection
psql -U postgres -d tracertm_dev
```

### Port Already in Use

```bash
# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>
```

### Import Errors

```bash
# Reinstall in editable mode
pip install -e ".[dev]"

# Check Python path
python -c "import sys; print(sys.path)"
```

## Next Steps

- [Docker Setup](./03-docker-setup) - Use Docker for development
- [First Run](./06-first-run) - Verify installation
- [Code Style](../03-contributing/01-code-style) - Coding standards
