> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Guide

> Run mySpellChecker in Docker with multi-stage builds, docker-compose profiles, GPU support, and production deployment.

Docker lets you run mySpellChecker without installing Python dependencies locally. The multi-stage Dockerfile provides optimized images for production API, development, and CLI-only use cases.

## Quick Start

### Using Docker Compose (Recommended)

```bash theme={null}
# Start the API server (production)
docker compose up api

# Start development server with hot reload
docker compose --profile dev up dev

# Run CLI commands
docker compose --profile cli run --rm cli check "မြန်မာစာ"

# Run tests
docker compose --profile test run --rm test
```

### Using Docker Directly

```bash theme={null}
# Build the image
docker build -t myspellchecker:latest .

# Run API server
docker run -p 8000:8000 -v ./data:/app/data:ro myspellchecker:latest

# Run CLI
docker run --rm -v ./data:/app/data:ro myspellchecker:cli --help
```

## Available Docker Images

The Dockerfile uses multi-stage builds to create optimized images for different use cases:

| Target        | Image Tag               | Purpose                             | Size    |
| ------------- | ----------------------- | ----------------------------------- | ------- |
| `runtime`     | `myspellchecker:latest` | Production API server               | \~200MB |
| `development` | `myspellchecker:dev`    | Development with hot reload + tests | \~350MB |
| `cli`         | `myspellchecker:cli`    | CLI-only (no web server)            | \~150MB |

### Building Specific Targets

```bash theme={null}
# Build production image
docker build --target runtime -t myspellchecker:latest .

# Build development image
docker build --target development -t myspellchecker:dev .

# Build CLI-only image
docker build --target cli -t myspellchecker:cli .
```

## Docker Compose Services

### Production API (`api`)

```bash theme={null}
docker compose up api
```

* **Port**: 8000
* **Health check**: `http://localhost:8000/health`
* **Resource limits**: 2 CPUs, 1GB memory
* **Restart policy**: `unless-stopped`

### Development Server (`dev`)

```bash theme={null}
docker compose --profile dev up dev
```

* **Port**: 8000
* **Hot reload**: Enabled (watches `/app/src`)
* **Log level**: DEBUG
* **Profile**: `dev` (requires `--profile dev`)

### GPU-Enabled API (`api-gpu`)

For transformer-based POS tagging and AI features:

```bash theme={null}
docker compose --profile gpu up api-gpu
```

* **Requires**: NVIDIA GPU with Docker GPU support
* **Resource limits**: 4 CPUs, 4GB memory, 1 GPU
* **Environment**: `CUDA_VISIBLE_DEVICES=0`

### CLI Tool (`cli`)

```bash theme={null}
# Check text
docker compose --profile cli run --rm cli check "သွားပါမယ်"

# Build dictionary
docker compose --profile cli run --rm cli build --input /app/input/corpus.txt --output /app/output/dictionary.db

# Get help
docker compose --profile cli run --rm cli --help
```

### Test Runner (`test`)

```bash theme={null}
docker compose --profile test run --rm test
```

Runs pytest with coverage reporting.

## Volume Mounts

| Host Path  | Container Path | Purpose                   |
| ---------- | -------------- | ------------------------- |
| `./data`   | `/app/data`    | Dictionary database files |
| `./config` | `/app/config`  | Custom configuration      |
| `./input`  | `/app/input`   | Input files for CLI       |
| `./output` | `/app/output`  | Output files from CLI     |
| `./src`    | `/app/src`     | Source code (dev only)    |

### Example: Using Custom Dictionary

```bash theme={null}
# Place your dictionary in ./data/
cp my_dictionary.db ./data/dictionary.db

# Start API with custom dictionary
docker compose up api
```

## Environment Variables

| Variable               | Default    | Description                                 |
| ---------------------- | ---------- | ------------------------------------------- |
| `PYTHONPATH`           | `/app/src` | Python module path                          |
| `LOG_LEVEL`            | `INFO`     | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `CUDA_VISIBLE_DEVICES` | `0`        | GPU device ID (gpu service only)            |

### Custom Environment

```bash theme={null}
# Override environment variables
LOG_LEVEL=DEBUG docker compose up api

# Or use .env file
echo "LOG_LEVEL=DEBUG" > .env
docker compose up api
```

## Production Deployment

### Basic Deployment

```bash theme={null}
# Build production image
docker compose build api

# Run in detached mode
docker compose up -d api

# Check status
docker compose ps
docker compose logs api
```

### With Reverse Proxy (nginx)

```yaml theme={null}
# docker-compose.override.yml
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - api
```

### Health Monitoring

The docker-compose configuration includes a health check that calls your API's health endpoint. You must implement this endpoint in your API wrapper (e.g., FastAPI):

```python theme={null}
# Example health endpoint in your FastAPI app
@app.get("/health")
def health():
    return {"status": "ok"}
```

```bash theme={null}
# Docker health check runs automatically every 30s
docker inspect --format='{{.State.Health.Status}}' myspellchecker-api
```

## Building Dictionary in Docker

### From Corpus File

```bash theme={null}
# Place corpus in input directory
cp my_corpus.txt ./input/

# Build dictionary
docker compose --profile cli run --rm cli build \
  --input /app/input/my_corpus.txt \
  --output /app/output/dictionary.db

# Copy output to data directory
cp ./output/dictionary.db ./data/
```

### Sample Dictionary

```bash theme={null}
# Build sample dictionary for testing
docker compose --profile cli run --rm cli build --sample

# Output is saved to /app/data/dictionary.db
```

## GPU Support

### Prerequisites

1. NVIDIA GPU with CUDA support
2. [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)

### Installation (Ubuntu)

```bash theme={null}
# Add NVIDIA Container Toolkit repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Restart Docker
sudo systemctl restart docker
```

### Running with GPU

```bash theme={null}
# Start GPU-enabled service
docker compose --profile gpu up api-gpu

# Verify GPU access
docker compose run --rm api-gpu python -c "import torch; print(torch.cuda.is_available())"
```

## Troubleshooting

### Container Won't Start

```bash theme={null}
# Check logs
docker compose logs api

# Check if port is in use
lsof -i :8000

# Rebuild image
docker compose build --no-cache api
```

### Database Not Found

```bash theme={null}
# Ensure data directory exists and contains dictionary
ls -la ./data/

# Build sample dictionary if needed
docker compose --profile cli run --rm cli build --sample
```

### Permission Denied

```bash theme={null}
# Fix volume permissions (Linux)
sudo chown -R 1000:1000 ./data ./output

# Or run as root (not recommended for production)
docker compose --profile cli run --rm --user root cli build --sample
```

### GPU Not Detected

```bash theme={null}
# Verify NVIDIA runtime
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

# Check Docker GPU configuration
docker info | grep -i gpu
```

### Memory Issues

```bash theme={null}
# Increase memory limit in docker-compose.yml
services:
  api:
    deploy:
      resources:
        limits:
          memory: 2G  # Increase from 1G
```

## Security Considerations

The Docker images follow security best practices:

1. **Non-root user**: Containers run as `appuser` (UID 1000)
2. **Read-only mounts**: Data volumes mounted as read-only where possible
3. **Minimal base image**: Uses `python:slim` for smaller attack surface
4. **No secrets in image**: Configuration via environment variables or mounted volumes
5. **Health checks**: Automatic container health monitoring

### Running with Read-Only Filesystem

```bash theme={null}
docker run --read-only \
  --tmpfs /tmp \
  -v ./data:/app/data:ro \
  myspellchecker:latest
```

## See Also

* [Installation Guide](/guides/installation) - pip installation
* [Configuration](/guides/configuration) - Configuration options
* [Performance Tuning](/guides/performance-tuning) - Optimization strategies
* [Integration Guide](/guides/integration) - Web framework integration