---
title: "Linux Development Setup"
description: "Complete guide for setting up TraceRTM development environment on Linux"
---

# Linux Development Setup

This guide provides comprehensive instructions for setting up TraceRTM development environment on Linux distributions including Ubuntu/Debian, Fedora/RHEL, and Arch Linux.

## Overview

TraceRTM is a Python-based requirements traceability system with a React frontend. This guide will help you set up:

- Python 3.12+ runtime environment
- Node.js 20+ for frontend development
- PostgreSQL database
- Redis for caching (optional)
- Development tools and IDE configuration

**Estimated Setup Time**: 30-45 minutes

## Prerequisites by Distribution

### System Requirements

- 4GB RAM minimum (8GB recommended)
- 2GB free disk space
- Internet connection
- Terminal access with sudo privileges

### Ubuntu/Debian (20.04+, Debian 11+)

```bash
# Update package list
sudo apt update

# Install essential build tools
sudo apt install -y build-essential curl wget git vim
```

### Fedora/RHEL (Fedora 38+, RHEL 9+)

```bash
# Update system packages
sudo dnf update -y

# Install development tools
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y curl wget git vim
```

### Arch Linux

```bash
# Update system
sudo pacman -Syu

# Install base development tools
sudo pacman -S --needed base-devel curl wget git vim
```

## Python 3.12+ Installation

TraceRTM requires Python 3.12 or higher for modern async features and type system improvements.

### Ubuntu/Debian

Ubuntu 24.04+ includes Python 3.12 by default. For older versions, use the deadsnakes PPA:

```bash
# Add deadsnakes PPA (Ubuntu < 24.04)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# Install Python 3.12
sudo apt install -y python3.12 python3.12-venv python3.12-dev python3-pip

# Verify installation
python3.12 --version  # Should show Python 3.12.x
```

### Fedora/RHEL

```bash
# Install Python 3.12
sudo dnf install -y python3.12 python3.12-devel

# Verify installation
python3.12 --version
```

### Arch Linux

```bash
# Install Python (Arch typically has latest version)
sudo pacman -S python python-pip

# Verify installation
python --version  # Should show Python 3.12.x or higher
```

### Installing UV Package Manager (Recommended)

TraceRTM uses UV for faster dependency management:

```bash
# Install UV (all distributions)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Verify installation
uv --version
```

## Node.js Installation

The frontend requires Node.js 20+.

### Ubuntu/Debian

```bash
# Install Node.js 20 using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version  # Should show v20.x.x
npm --version
```

### Fedora/RHEL

```bash
# Install Node.js 20 using NodeSource
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# Verify installation
node --version
npm --version
```

### Arch Linux

```bash
# Install Node.js
sudo pacman -S nodejs npm

# Verify installation
node --version
npm --version
```

### Enable Corepack for pnpm

TraceRTM uses pnpm for frontend package management:

```bash
# Enable corepack (all distributions)
sudo corepack enable

# Install pnpm
corepack prepare pnpm@latest --activate

# Verify installation
pnpm --version
```

## PostgreSQL Setup

PostgreSQL is the recommended database for development and production.

### Ubuntu/Debian

```bash
# Install PostgreSQL 15+
sudo apt install -y postgresql postgresql-contrib libpq-dev

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verify installation
sudo -u postgres psql --version
```

### Fedora/RHEL

```bash
# Install PostgreSQL
sudo dnf install -y postgresql-server postgresql-contrib postgresql-devel

# Initialize database cluster
sudo postgresql-setup --initdb

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

### Arch Linux

```bash
# Install PostgreSQL
sudo pacman -S postgresql

# Initialize database cluster
sudo -u postgres initdb -D /var/lib/postgres/data

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

### Database Configuration

Create a database and user for TraceRTM:

```bash
# Switch to postgres user
sudo -u postgres psql

# In PostgreSQL prompt, run:
CREATE DATABASE tracertm;
CREATE USER tracertm_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE tracertm TO tracertm_user;

# PostgreSQL 15+ requires additional grant
\c tracertm
GRANT ALL ON SCHEMA public TO tracertm_user;

# Exit PostgreSQL
\q
```

### Connection String

Add to your `.env` file:

```bash
TRACERTM_DATABASE__URL=postgresql://tracertm_user:your_secure_password@localhost:5432/tracertm
```

## Redis Setup (Optional)

Redis is used for caching and can improve performance.

### Ubuntu/Debian

```bash
# Install Redis
sudo apt install -y redis-server

# Start Redis service
sudo systemctl start redis-server
sudo systemctl enable redis-server

# Test connection
redis-cli ping  # Should return PONG
```

### Fedora/RHEL

```bash
# Install Redis
sudo dnf install -y redis

# Start Redis service
sudo systemctl start redis
sudo systemctl enable redis

# Test connection
redis-cli ping
```

### Arch Linux

```bash
# Install Redis
sudo pacman -S redis

# Start Redis service
sudo systemctl start redis
sudo systemctl enable redis

# Test connection
redis-cli ping
```

## Git Configuration

Configure Git for development:

```bash
# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Enable helpful colorization
git config --global color.ui auto

# Set default editor (optional)
git config --global core.editor vim
```

## Project Setup

### Clone Repository

```bash
# Clone the repository
git clone https://github.com/yourusername/tracertm.git
cd tracertm
```

### Python Virtual Environment Setup

Using UV (recommended):

```bash
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate

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

Using standard Python:

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

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

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

### Environment Configuration

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

# Edit .env with your settings
vim .env
```

Minimum required configuration:

```bash
# Database (PostgreSQL)
TRACERTM_DATABASE__URL=postgresql://tracertm_user:your_secure_password@localhost:5432/tracertm

# Development settings
TRACERTM_LOG_LEVEL=DEBUG
TRACERTM_DATABASE__ECHO=false
```

### Database Initialization

```bash
# Run database migrations (when implemented)
# alembic upgrade head

# For now, the application creates tables automatically on first run
tracertm init
```

### Frontend Setup

```bash
# Navigate to frontend directory
cd frontend

# Install dependencies
pnpm install

# Return to root
cd ..
```

## Running the Development Environment

### Backend API Server

```bash
# Ensure virtual environment is activated
source .venv/bin/activate

# Run the API server (default port: 8000)
uvicorn src.tracertm.api.main:app --reload --host 0.0.0.0 --port 8000
```

Access the API at: http://localhost:8000

API Documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### Frontend Development Server

In a new terminal:

```bash
# Navigate to frontend
cd frontend/apps/web

# Start development server (default port: 3000)
pnpm dev
```

Access the frontend at: http://localhost:3000

### CLI Tool

```bash
# Activate virtual environment
source .venv/bin/activate

# Run CLI commands
tracertm --help
rtm --help  # Shorter alias

# Example commands
tracertm init                    # Initialize configuration
tracertm project create "MyProject"
tracertm item create --type requirement --title "User Authentication"
```

### TUI (Terminal User Interface)

```bash
# Launch the TUI
tracertm tui
```

## IDE Setup

### Visual Studio Code

#### Installation

**Ubuntu/Debian:**
```bash
# Install via snap
sudo snap install code --classic

# Or download .deb from code.visualstudio.com
wget -O code.deb https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64
sudo apt install ./code.deb
```

**Fedora/RHEL:**
```bash
# Import Microsoft GPG key
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

# Add repository
sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/vscode.repo'

# Install
sudo dnf install code
```

**Arch Linux:**
```bash
# Install from AUR
yay -S visual-studio-code-bin
# Or
paru -S visual-studio-code-bin
```

#### Recommended Extensions

```bash
# Python development
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension charliermarsh.ruff

# Frontend development
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss

# Database
code --install-extension ms-ossdata.vscode-postgresql

# Git
code --install-extension eamodio.gitlens
```

#### VS Code Settings

Create `.vscode/settings.json`:

```json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "python.linting.enabled": true,
  "python.formatting.provider": "none",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    ".venv": true
  }
}
```

### PyCharm

#### Installation

**Ubuntu/Debian:**
```bash
# Install via snap
sudo snap install pycharm-community --classic

# Or use JetBrains Toolbox
```

**Fedora/RHEL:**
```bash
# Install via snap
sudo snap install pycharm-community --classic
```

**Arch Linux:**
```bash
# Install from official repositories
sudo pacman -S pycharm-community-edition

# Or from AUR for Professional
yay -S pycharm-professional
```

#### PyCharm Configuration

1. Open the project directory
2. Configure Python interpreter:
   - File → Settings → Project → Python Interpreter
   - Add interpreter → Existing environment
   - Select `.venv/bin/python`
3. Enable pytest:
   - File → Settings → Tools → Python Integrated Tools
   - Default test runner: pytest
4. Configure code style:
   - File → Settings → Editor → Code Style → Python
   - Import from pyproject.toml

## Verification

### Backend Tests

```bash
# Activate virtual environment
source .venv/bin/activate

# Run all tests
pytest

# Run with coverage
pytest --cov=src/tracertm --cov-report=html

# Run specific test types
pytest -m unit           # Unit tests only
pytest -m integration    # Integration tests only
```

### Frontend Tests

```bash
cd frontend/apps/web

# Run unit tests
pnpm test

# Run E2E tests
pnpm test:e2e
```

### Code Quality

```bash
# Activate virtual environment
source .venv/bin/activate

# Format code
ruff format .

# Lint code
ruff check --fix .

# Type checking
mypy src/

# Run all quality checks (if using poethepoet)
poe quality
```

## Common Linux Development Issues

### Permission Denied for PostgreSQL

**Problem**: Cannot connect to PostgreSQL database.

**Solution**:
```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Verify authentication in pg_hba.conf
sudo vim /etc/postgresql/*/main/pg_hba.conf
# Or for Fedora/RHEL:
sudo vim /var/lib/pgsql/data/pg_hba.conf

# Add or modify line for local connections:
# local   all             all                                     md5
# host    all             all             127.0.0.1/32            md5

# Restart PostgreSQL
sudo systemctl restart postgresql
```

### Python Module Not Found

**Problem**: ImportError or ModuleNotFoundError despite installation.

**Solution**:
```bash
# Ensure virtual environment is activated
source .venv/bin/activate

# Verify Python path
which python  # Should point to .venv/bin/python

# Reinstall dependencies
pip install -e ".[dev]"

# Or with UV
uv pip install -e ".[dev]"
```

### Port Already in Use

**Problem**: Address already in use when starting servers.

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

# Kill the process
kill -9 <PID>

# Or use a different port
uvicorn src.tracertm.api.main:app --reload --port 8001
```

### Node.js/pnpm Issues

**Problem**: pnpm command not found or module errors.

**Solution**:
```bash
# Ensure corepack is enabled
sudo corepack enable

# Clear pnpm cache
pnpm store prune

# Reinstall dependencies
cd frontend
rm -rf node_modules
pnpm install
```

### Database Connection Timeout

**Problem**: Database operations timing out.

**Solution**:
```bash
# Check PostgreSQL max_connections
sudo -u postgres psql -c "SHOW max_connections;"

# Increase if needed (edit postgresql.conf)
sudo vim /etc/postgresql/*/main/postgresql.conf
# Set: max_connections = 100

# Restart PostgreSQL
sudo systemctl restart postgresql
```

### File Watcher Limits (for Hot Reload)

**Problem**: "ENOSPC: System limit for number of file watchers reached"

**Solution**:
```bash
# Increase inotify watches limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Verify
cat /proc/sys/fs/inotify/max_user_watches
```

### SSL Certificate Issues

**Problem**: SSL certificate verification errors during package installation.

**Solution**:
```bash
# Update CA certificates
# Ubuntu/Debian:
sudo apt install --reinstall ca-certificates

# Fedora/RHEL:
sudo dnf reinstall ca-certificates

# Arch:
sudo pacman -S ca-certificates
```

### Disk Space Issues

**Problem**: No space left on device.

**Solution**:
```bash
# Check disk usage
df -h

# Clean package manager cache
# Ubuntu/Debian:
sudo apt clean
sudo apt autoremove

# Fedora/RHEL:
sudo dnf clean all

# Arch:
sudo pacman -Sc

# Clean Python cache
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

# Clean pnpm cache
pnpm store prune
```

## Performance Optimization

### Faster Package Installation

```bash
# Use UV instead of pip (10-100x faster)
uv pip install -e ".[dev]"

# Use pnpm instead of npm (2-3x faster)
pnpm install

# Enable parallel builds
export MAKEFLAGS="-j$(nproc)"
```

### Database Performance

```bash
# Add to postgresql.conf for development
shared_buffers = 256MB
effective_cache_size = 1GB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
```

### Virtual Environment Location

```bash
# Keep .venv on fast SSD, not network drive
python3.12 -m venv .venv

# Or use system-wide cache directory
python3.12 -m venv ~/.virtualenvs/tracertm
```

## Next Steps

Once your development environment is set up:

1. Review the [Architecture](/docs/development/architecture) documentation
2. Explore the [API Reference](/api) for backend development
3. Check the [Frontend Guide](/docs/development/frontend) for UI development
4. Read the [Testing Guide](/docs/development/testing) for writing tests
5. Set up [Pre-commit Hooks](/docs/development/git-workflow) for code quality

## Additional Resources

- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Python Virtual Environments](https://docs.python.org/3/library/venv.html)
- [UV Package Manager](https://github.com/astral-sh/uv)
- [pnpm Documentation](https://pnpm.io/)
- [VS Code Python Guide](https://code.visualstudio.com/docs/python/python-tutorial)

## Getting Help

If you encounter issues not covered in this guide:

1. Check the [Troubleshooting](/docs/troubleshooting) section
2. Search existing [GitHub Issues](https://github.com/yourusername/tracertm/issues)
3. Ask on the [Discord Community](https://discord.gg/tracertm)
4. Open a new issue with your system details and error logs
