---
title: "First Run"
description: "Verify TraceRTM installation and run for the first time"
keywords: [first run, verification, installation, setup]
---

# First Run

Verify your TraceRTM installation and run it for the first time.

## Verification Checklist

### 1. Check Prerequisites

```bash
# Python version
python3 --version
# Should be 3.12+

# Node.js version
node --version
# Should be 18+

# PostgreSQL version
psql --version
# Should be 14+

# Docker (if using)
docker --version
docker-compose --version
```

### 2. Verify Database

```bash
# Check PostgreSQL is running
pg_isready

# Test connection
psql -U postgres -d tracertm_dev -c "SELECT version();"
```

### 3. Check Environment

```bash
# Verify .env file exists
ls -la .env

# Check required variables
grep -E "DATABASE_URL|SECRET_KEY|JWT_SECRET" .env
```

## First Run Steps

### 1. Start Services

#### Using Docker

```bash
# Start all services
docker-compose up -d

# Check status
docker-compose ps
```

#### Local Development

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

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

### 2. Run Migrations

```bash
# Using Docker
docker-compose exec api alembic upgrade head

# Local
alembic upgrade head
```

### 3. Verify API

```bash
# Health check
curl http://localhost:8000/health

# Expected response
{"status": "healthy"}
```

### 4. Access Web Interface

Open browser:
```
http://localhost:3000
```

### 5. Create First Project

```bash
# Using CLI
trace project create "My First Project"

# Or via API
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Project"}'
```

## Verification Script

Run the verification script:

```bash
# Run verification
python scripts/verify_installation.py
```

Expected output:
```
✓ Python version: 3.12.0
✓ PostgreSQL connection: OK
✓ Database migrations: Applied
✓ API server: Running
✓ Frontend: Running
✓ All checks passed!
```

## Common Issues

### Database Connection Failed

```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Check connection string
echo $DATABASE_URL

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

### Migration Errors

```bash
# Check migration status
alembic current

# View migration history
alembic history

# Reset database (development only)
alembic downgrade base
alembic upgrade head
```

### Port Already in Use

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

# Kill process
kill -9 <PID>

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

### Import Errors

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

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

## Next Steps

After successful first run:

1. **Create a project** - Set up your first project
2. **Add items** - Create requirements or test cases
3. **Create links** - Establish traceability
4. **Explore features** - Try different views and features

## Related Documentation

- [Local Development](./02-local-development) - Development setup
- [Docker Setup](./03-docker-setup) - Docker setup
- [Prerequisites](./01-prerequisites) - Required software
