510 lines
8.2 KiB
Markdown
Raw Normal View History

Update.
2025-11-29 00:50:53 +01:00
# 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
Reference in New Issue Copy Permalink