# Tikker Deployment Guide

## Prerequisites

- Docker 20.10+
- Docker Compose 2.0+
- 2GB RAM minimum
- 500MB disk space minimum

## Quick Start

### 1. Build and Start Services

```bash
docker-compose up --build
```

This will:
- Build the C tools from source in the builder stage
- Build the Python services
- Start all 4 services with health checks
- Create default network bridge

### 2. Verify Services

```bash
# Check all services are running
docker-compose ps

# Check specific service logs
docker-compose logs api
docker-compose logs ai_service
docker-compose logs viz_service
```

### 3. Test API

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

# Get daily stats
curl http://localhost:8000/api/stats/daily

# Get top words
curl http://localhost:8000/api/words/top

# Test AI service
curl -X POST http://localhost:8001/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "test", "analysis_type": "general"}'

# Test visualization
curl -X POST http://localhost:8002/chart \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "data": {"A": 10}, "chart_type": "bar"}'
```

## Detailed Setup

### 1. Clone Repository

```bash
git clone <repository-url>
cd tikker
```

### 2. Build C Tools

```bash
cd src/libtikker
make clean && make
cd ../tools
make clean && make
cd ../..
```

Verify build output:
```bash
ls -la build/lib/libtikker.a
ls -la build/bin/tikker-*
```

### 3. Configure Environment

Create `.env` file in project root:

```bash
# API Configuration
TOOLS_DIR=/app/build/bin
DB_PATH=/app/tikker.db
LOG_LEVEL=INFO

# AI Service Configuration
OPENAI_API_KEY=sk-xxxxxxxxxxxx

# Service URLs (for service-to-service communication)
AI_SERVICE_URL=http://ai_service:8001
VIZ_SERVICE_URL=http://viz_service:8002
```

### 4. Build Docker Images

```bash
docker-compose build
```

### 5. Start Services

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

# Or run in foreground (for debugging)
docker-compose up
```

### 6. Initialize Database (if needed)

```bash
docker-compose exec api python -c "
from src.api.c_tools_wrapper import CToolsWrapper
tools = CToolsWrapper()
print('C tools initialized successfully')
"
```

## Production Deployment

### 1. Resource Limits

Update `docker-compose.yml`:

```yaml
services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G
  
  ai_service:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
  
  viz_service:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
```

### 2. Logging Configuration

```yaml
services:
  api:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
        labels: "service=tikker-api"
```

### 3. Restart Policy

```yaml
services:
  api:
    restart: on-failure
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

## Scaling

### Scale AI Service

```bash
docker-compose up -d --scale ai_service=3
```

### Scale Visualization Service

```bash
docker-compose up -d --scale viz_service=2
```

Note: Main API service should remain as single instance due to database locking.

## Monitoring

### View Real-time Logs

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

# Specific service
docker-compose logs -f api

# Follow and grep
docker-compose logs -f api | grep ERROR
```

### Health Checks

```bash
# Check all health endpoints
for port in 8000 8001 8002; do
  echo "Port $port:"
  curl -s http://localhost:$port/health | jq .
done
```

### Database Status

```bash
# Access database viewer (if running dev profile)
# Open http://localhost:8080 in browser

# Or query directly
docker-compose exec api sqlite3 tikker.db ".tables"
```

## Backup and Recovery

### Backup Database

```bash
# Container
docker-compose exec api cp tikker.db tikker.db.backup

# Or from host
cp tikker.db tikker.db.backup
```

### Backup Logs

```bash
# Container
docker-compose exec api tar -czf logs.tar.gz logs_plain/

# Or from host
tar -czf logs.tar.gz logs_plain/
```

### Restore from Backup

```bash
# Copy backup to container
docker cp tikker.db.backup <container-id>:/app/tikker.db

# Restart API service
docker-compose restart api
```

## Troubleshooting

### Services Won't Start

1. Check logs: `docker-compose logs`
2. Verify ports are available: `netstat -tulpn | grep 800`
3. Check disk space: `df -h`
4. Rebuild images: `docker-compose build --no-cache`

### Database Connection Error

```bash
# Check database exists
docker-compose exec api ls -la tikker.db

# Check permissions
docker-compose exec api chmod 666 tikker.db

# Reset database
docker-compose exec api rm tikker.db
docker-compose restart api
```

### Memory Issues

```bash
# Check memory usage
docker stats

# Reduce container limits
# Edit docker-compose.yml resource limits

# Clear unused images/containers
docker system prune -a
```

### High CPU Usage

1. Check slow queries: Enable logging in C tools
2. Optimize database: `sqlite3 tikker.db "VACUUM;"`
3. Reduce polling frequency if applicable

### Network Connectivity

```bash
# Test inter-service communication
docker-compose exec api curl http://ai_service:8001/health
docker-compose exec api curl http://viz_service:8002/health

# Inspect network
docker network inspect tikker-network
```

## Updating Services

### Update Single Service

```bash
# Rebuild and restart specific service
docker-compose up -d --build api

# Or just restart without rebuild
docker-compose restart api
```

### Update All Services

```bash
# Pull latest code
git pull

# Rebuild all
docker-compose build --no-cache

# Restart all
docker-compose restart
```

### Rolling Updates (Zero Downtime)

```bash
# Update and restart one at a time
docker-compose up -d --no-deps --build api
docker-compose up -d --no-deps --build ai_service
docker-compose up -d --no-deps --build viz_service
```

## Development Setup

### Run with Development Profile

```bash
docker-compose --profile dev up -d
```

This includes Adminer database viewer on port 8080.

### Hot Reload Python Code

```bash
# Mount source code as volume
docker-compose exec api python -m uvicorn \
  src.api.api_c_integration:app \
  --host 0.0.0.0 --port 8000 --reload
```

### Debug Services

```bash
# Run in foreground to see output
docker-compose up api

# Press Ctrl+C to stop

# Or run single container in interactive mode
docker run -it --rm -p 8000:8000 \
  -e TOOLS_DIR=/app/build/bin \
  -v $(pwd):/app \
  tikker-api /bin/bash
```

## Security Hardening

### 1. Run as Non-Root

```dockerfile
RUN useradd -m tikker
USER tikker
```

### 2. Read-Only Filesystem

```yaml
services:
  api:
    read_only: true
    tmpfs:
      - /tmp
      - /var/tmp
```

### 3. Limit Capabilities

```yaml
services:
  api:
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
```

### 4. Network Isolation

```yaml
networks:
  tikker-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.25.0.0/16
```

## Performance Tuning

### Database Optimization

```bash
# Vacuum database
docker-compose exec api sqlite3 tikker.db "VACUUM;"

# Analyze query plans
docker-compose exec api sqlite3 tikker.db ".mode line" "EXPLAIN QUERY PLAN SELECT * FROM words;"
```

### Python Optimization

Update docker run with environment variables:
```bash
-e PYTHONOPTIMIZE=2
-e PYTHONDONTWRITEBYTECODE=1
```

### Resource Allocation

Monitor and adjust in docker-compose.yml:
```yaml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '1.0'
      memory: 1G
```

## Maintenance

### Regular Tasks

Daily:
- Monitor logs for errors
- Check disk usage
- Verify all services healthy

Weekly:
- Backup database
- Review performance metrics
- Check for updates

Monthly:
- Full system backup
- Test disaster recovery
- Update dependencies

### Cleanup

```bash
# Remove unused images
docker image prune

# Remove unused volumes
docker volume prune

# Remove unused networks
docker network prune

# Full cleanup
docker system prune -a --volumes
```

## Support

For issues or questions:
1. Check logs: `docker-compose logs`
2. Review API documentation: `docs/API.md`
3. Check CLI usage guide: `docs/examples/CLI_USAGE.md`
4. Test with curl or Postman