# Docker Setup for Oclawma

This directory contains Docker configuration for running Oclawma in containers.

## Files

- `Dockerfile` - Multi-stage build definition
- `docker-compose.yml` - Complete service orchestration
- `.dockerignore` - Files to exclude from Docker context
- `docker/entrypoint.sh` - Container initialization script
- `docker/healthcheck.sh` - Health check script

## Quick Start

### Build the image

```bash
docker build -t oclawma:latest .
```

### Run with Docker Compose

```bash
# Create a .env file with your API keys
cat > .env << EOF
KIMI_API_KEY=your_kimi_api_key
OPENAI_API_KEY=your_openai_api_key  # optional
OCLAWMA_LOG_LEVEL=INFO
EOF

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Run oclawma commands
docker-compose exec oclawma oclawma --help
docker-compose exec oclawma oclawma config show
```

### Interactive Mode

```bash
# Run with TTY for interactive sessions
docker-compose run --rm oclawma

# Or directly with docker
docker run -it --rm \
  -v oclawma_data:/app/data \
  -e KIMI_API_KEY=your_key \
  oclawma:latest
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OCLAWMA_DATA_DIR` | /app/data | Data persistence directory |
| `OCLAWMA_CONFIG_DIR` | /app/data/config | Configuration directory |
| `OCLAWMA_LOG_LEVEL` | INFO | Logging level |
| `OCLAWMA_PROVIDER` | kimi | Default LLM provider |
| `KIMI_API_KEY` | - | Kimi API key |
| `OPENAI_API_KEY` | - | OpenAI API key |

### Volumes

| Volume | Purpose |
|--------|---------|
| `oclawma_data` | Persistent data storage |
| `./config` | Optional: Custom configuration files |

### Resource Limits

The default configuration sets:
- **CPU Limit:** 2.0 cores
- **Memory Limit:** 1GB
- **CPU Reservation:** 0.5 cores  
- **Memory Reservation:** 256MB

## Health Checks

The container includes a health check that verifies:
- Oclawma CLI is available
- Version command works
- Data directory is writable

Health status can be checked with:
```bash
docker inspect --format='{{.State.Health.Status}}' oclawma
```

## Graceful Shutdown

The container handles SIGTERM for graceful shutdown:
- 30-second grace period
- Proper cleanup of running operations
- Exit code 0 on successful shutdown

## Production Deployment

For production use, consider:

1. **Use specific image tags** instead of `latest`
2. **Set resource limits** appropriate to your workload
3. **Configure log rotation** (already set in compose)
4. **Use secrets management** for API keys
5. **Enable monitoring** via health checks

Example production override:

```yaml
# docker-compose.prod.yml
version: "3.8"
services:
  oclawma:
    image: oclawma:0.2.0  # specific version
    deploy:
      resources:
        limits:
          cpus: '4.0'
          memory: 2G
    logging:
      driver: syslog
      options:
        syslog-address: tcp://logs.example.com:514
```

## Troubleshooting

### Container won't start

Check logs:
```bash
docker-compose logs oclawma
```

### Permission issues

Ensure the data volume has correct permissions:
```bash
docker-compose exec oclawma ls -la /app/data
```

### API key issues

Verify environment variables are set:
```bash
docker-compose exec oclawma env | grep -i api
```
