# Docker Guide for Ducku

This guide explains how to build, run, and distribute ducku as a Docker container.

## 🐳 Docker Image Features

- **Multi-stage build**: Optimized for small image size
- **Non-root user**: Runs as `ducku` user for security
- **Git support**: Includes git for repository analysis
- **Health checks**: Built-in container health monitoring
- **Volume mounting**: Easy project analysis via volume mounts

## 🏗️ Building the Docker Image

### Quick Build

```bash
# Build using the provided script
./scripts/docker-build.sh

# Or build manually
docker build -t ducku:latest .
```

### Manual Build with Custom Tags

```bash
# Build with specific tag
docker build -t ducku:0.1.0 .

# Build and tag for registry
docker build -t your-registry.com/ducku:latest .
```

## 🚀 Running Ducku in Docker

### Basic Usage

```bash
# Analyze current directory
docker run --rm -v $(pwd):/workspace ducku:latest

# Analyze specific project
docker run --rm -v /path/to/project:/workspace ducku:latest

# Using the convenience script
./scripts/docker-run.sh
```

### Advanced Usage

```bash
# Interactive shell for debugging
docker run --rm -it -v $(pwd):/workspace --entrypoint bash ducku:latest

# Run with custom environment variables
docker run --rm \
  -v $(pwd):/workspace \
  -e PROJECT_PATH=/workspace \
  ducku:latest

# Mount configuration file
docker run --rm \
  -v $(pwd):/workspace \
  -v $(pwd)/.ducku.yaml:/workspace/.ducku.yaml:ro \
  ducku:latest
```

## 🐙 Docker Compose

### Simple Analysis

```bash
# Analyze current directory
docker-compose run analyze

# Analyze specific project
PROJECT_PATH=/path/to/project docker-compose run analyze
```

### Interactive Mode

```bash
# Start interactive session
docker-compose run --rm ducku bash
```

### Custom Compose Commands

```yaml
# Add to docker-compose.override.yml
services:
  my-project:
    extends: analyze
    volumes:
      - ./my-specific-project:/workspace:ro
```

## 📦 Distribution

### Docker Hub

```bash
# Tag for Docker Hub
docker tag ducku:latest your-username/ducku:latest

# Push to Docker Hub
docker push your-username/ducku:latest

# Users can then pull and run
docker run --rm -v $(pwd):/workspace your-username/ducku:latest
```

### GitHub Container Registry

```bash
# Tag for GitHub Container Registry
docker tag ducku:latest ghcr.io/duckuio/ducku:latest

# Push to GHCR
docker push ghcr.io/duckuio/ducku:latest
```

### Private Registry

```bash
# Tag for private registry
docker tag ducku:latest your-registry.com/ducku:latest

# Push to private registry
docker push your-registry.com/ducku:latest
```

## 🔧 CI/CD Integration

### GitHub Actions

```yaml
name: Build and Push Docker Image

on:
  push:
    tags: ['v*']
  
jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build -t ducku:${{ github.ref_name }} .
      
      - name: Push to registry
        run: |
          echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
          docker push ducku:${{ github.ref_name }}
```

### GitLab CI

```yaml
# .gitlab-ci.yml
build-docker:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
  only:
    - tags
```

## 🎯 Use Cases

### 1. Local Development

```bash
# Quick analysis of current project
./scripts/docker-run.sh

# Debug with shell access
docker run --rm -it -v $(pwd):/workspace --entrypoint bash ducku:latest
```

### 2. CI/CD Pipelines

```bash
# In your CI script
docker run --rm -v $PWD:/workspace ducku:latest > analysis-report.txt
```

### 3. Team Consistency

```bash
# Ensure everyone uses the same version
docker run --rm -v $(pwd):/workspace ducku:0.1.0
```

### 4. Multi-Project Analysis

```bash
# Analyze multiple projects
for project in /path/to/projects/*; do
  echo "Analyzing $project"
  docker run --rm -v "$project:/workspace" ducku:latest
done
```

## 🛠️ Troubleshooting

### Common Issues

1. **Permission denied**
   ```bash
   # Fix file permissions
   sudo chown -R $(id -u):$(id -g) /path/to/project
   ```

2. **Volume mount issues**
   ```bash
   # Use absolute paths
   docker run --rm -v "$(pwd):/workspace" ducku:latest
   ```

3. **Configuration not found**
   ```bash
   # Mount config explicitly
   docker run --rm \
     -v $(pwd):/workspace \
     -v $(pwd)/.ducku.yaml:/workspace/.ducku.yaml:ro \
     ducku:latest
   ```

### Debug Commands

```bash
# Check if image exists
docker images | grep ducku

# Inspect image
docker inspect ducku:latest

# Check container logs
docker run --rm -v $(pwd):/workspace ducku:latest 2>&1 | tee ducku.log

# Run with debug shell
docker run --rm -it -v $(pwd):/workspace --entrypoint bash ducku:latest
```

## 📊 Image Information

- **Base Image**: `python:3.13-slim-bookworm`
- **Size**: ~150MB (compressed)
- **Architecture**: Multi-platform (amd64, arm64)
- **Security**: Non-root user, minimal attack surface
- **Dependencies**: Only runtime dependencies included

## 🚀 Quick Start

1. **Build the image:**
   ```bash
   ./scripts/docker-build.sh
   ```

2. **Run on your project:**
   ```bash
   ./scripts/docker-run.sh
   ```

3. **Or use Docker directly:**
   ```bash
   docker run --rm -v $(pwd):/workspace ducku:latest
   ```

That's it! Ducku will analyze your project and provide insights about documentation quality and unused modules.
