tikker/DEPLOYMENT.md at main

 # 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
 . Check logs: `docker-compose logs`
 . Verify ports are available: `netstat -tulpn | grep 800`
 . Check disk space: `df -h`
 . 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
 . Check slow queries: Enable logging in C tools
 . Optimize database: `sqlite3 tikker.db "VACUUM;"`
 . 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:
 . Check logs: `docker-compose logs`
 . Review API documentation: `docs/API.md`
 . Check CLI usage guide: `docs/examples/CLI_USAGE.md`
 . Test with curl or Postman