---
title: "Docker Setup"
description: "Set up TraceRTM using Docker and Docker Compose"
keywords: [docker, docker-compose, containers, setup]
---

# Docker Setup

Set up TraceRTM using Docker for isolated, reproducible development environments.

## Prerequisites

- Docker 20.10+
- Docker Compose 2.0+

## Quick Start

### 1. Clone Repository

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

### 2. Configure Environment

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

# Edit .env
nano .env
```

### 3. Start Services

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

# View logs
docker-compose logs -f

# Check status
docker-compose ps
```

## Docker Compose Services

### API Service

```yaml
api:
  build: .
  ports:
    - "8000:8000"
  environment:
    - DATABASE_URL=postgresql://postgres:password@db:5432/tracertm
  depends_on:
    - db
    - redis
```

### Database Service

```yaml
db:
  image: postgres:14
  environment:
    - POSTGRES_DB=tracertm
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=password
  volumes:
    - postgres_data:/var/lib/postgresql/data
```

### Redis Service

```yaml
redis:
  image: redis:7-alpine
  ports:
    - "6379:6379"
```

## Common Commands

### Start Services

```bash
# Start in background
docker-compose up -d

# Start with logs
docker-compose up
```

### Stop Services

```bash
# Stop services
docker-compose stop

# Stop and remove containers
docker-compose down

# Remove volumes too
docker-compose down -v
```

### View Logs

```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api

# Last 100 lines
docker-compose logs --tail=100 api
```

### Execute Commands

```bash
# Run command in container
docker-compose exec api python -m tracertm.cli migrate

# Open shell
docker-compose exec api bash

# Run tests
docker-compose exec api pytest
```

## Database Operations

### Run Migrations

```bash
docker-compose exec api alembic upgrade head
```

### Access Database

```bash
# Connect to PostgreSQL
docker-compose exec db psql -U postgres -d tracertm

# Or from host
psql -h localhost -U postgres -d tracertm
```

### Backup Database

```bash
# Create backup
docker-compose exec db pg_dump -U postgres tracertm > backup.sql

# Restore backup
docker-compose exec -T db psql -U postgres tracertm < backup.sql
```

## Development Workflow

### Rebuild Containers

```bash
# Rebuild after code changes
docker-compose build

# Rebuild and restart
docker-compose up -d --build
```

### Hot Reload

The API service uses volume mounts for hot reload:

```yaml
volumes:
  - ./src:/app/src
```

Code changes are automatically reflected.

### Run Tests

```bash
# Run all tests
docker-compose exec api pytest

# Run specific test
docker-compose exec api pytest tests/test_items.py

# With coverage
docker-compose exec api pytest --cov=tracertm
```

## Environment Variables

### Using .env File

```bash
# .env file
DATABASE_URL=postgresql://postgres:password@db:5432/tracertm
REDIS_URL=redis://redis:6379/0
SECRET_KEY=dev-secret-key
```

### Override in docker-compose.yml

```yaml
services:
  api:
    environment:
      - DEBUG=true
      - LOG_LEVEL=DEBUG
```

## Volumes

### Named Volumes

```yaml
volumes:
  postgres_data:
  redis_data:
```

### Bind Mounts

```yaml
volumes:
  - ./src:/app/src
  - ./data:/app/data
```

## Troubleshooting

### Container Won't Start

```bash
# Check logs
docker-compose logs api

# Check status
docker-compose ps

# Restart service
docker-compose restart api
```

### Database Connection Issues

```bash
# Check database is ready
docker-compose exec db pg_isready

# Test connection
docker-compose exec api python -c "from tracertm.database import get_db; print('Connected')"
```

### Port Conflicts

```bash
# Change ports in docker-compose.yml
ports:
  - "8001:8000"  # Use different host port
```

### Clean Up

```bash
# Remove containers and volumes
docker-compose down -v

# Remove images
docker-compose down --rmi all

# Full cleanup
docker system prune -a
```

## Production Considerations

For production, use:
- Separate docker-compose.prod.yml
- Environment-specific configurations
- Resource limits
- Health checks
- Restart policies

## Next Steps

- [Local Development](./02-local-development) - Non-Docker setup
- [First Run](./06-first-run) - Verify installation
- [Environment Variables](./05-environment-variables) - Configuration
