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

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

# 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

# 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

git clone <repository-url>
cd tikker

2. Build C Tools

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

Verify build output:

ls -la build/lib/libtikker.a
ls -la build/bin/tikker-*

3. Configure Environment

Create .env file in project root:

# 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

docker-compose build

5. Start Services

# Run in background
docker-compose up -d

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

6. Initialize Database (if needed)

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:

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

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

3. Restart Policy

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

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

Scale Visualization Service

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

# 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

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

Database Status

# 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

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

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

Backup Logs

# 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

# 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

# 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

# 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

# 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

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

# Or just restart without rebuild
docker-compose restart api

Update All Services

# Pull latest code
git pull

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

# Restart all
docker-compose restart

Rolling Updates (Zero Downtime)

# 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

docker-compose --profile dev up -d

This includes Adminer database viewer on port 8080.

Hot Reload Python Code

# 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

# 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

RUN useradd -m tikker
USER tikker

2. Read-Only Filesystem

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

3. Limit Capabilities

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

4. Network Isolation

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

Performance Tuning

Database Optimization

# 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:

-e PYTHONOPTIMIZE=2
-e PYTHONDONTWRITEBYTECODE=1

Resource Allocation

Monitor and adjust in docker-compose.yml:

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

# 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