From 02fd70726bdc0a758c12a7e905a00e94bb6c5eb5 Mon Sep 17 00:00:00 2001 From: jango-blockchained Date: Thu, 6 Feb 2025 12:55:31 +0100 Subject: [PATCH] docs: Enhance Docker deployment documentation with comprehensive setup guide - Expand Docker documentation with detailed build and launch instructions - Add support for standard, speech-enabled, and GPU-accelerated configurations - Include Docker Compose file explanations and resource management details - Provide troubleshooting tips and best practices for Docker deployment - Update README with improved Docker build and launch instructions --- README.md | 55 +++++++- docs/getting-started/docker.md | 249 ++++++++++++++++++++++++++++++++- 2 files changed, 301 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 49cb794..879f2f4 100644 --- a/README.md +++ b/README.md @@ -133,11 +133,64 @@ NODE_ENV=production ./scripts/setup-env.sh - Edit `.env` file with your Home Assistant details - Required: Add your `HASS_TOKEN` (long-lived access token) -4. Launch with Docker: +4. Build and launch with Docker: ```bash +# Build options: +# Standard build +./docker-build.sh + +# Build with speech support +./docker-build.sh --speech + +# Build with speech and GPU support +./docker-build.sh --speech --gpu + +# Launch: docker compose up -d + +# With speech features: +docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d ``` +## Docker Build Options ๐Ÿณ + +My Docker build script (`docker-build.sh`) supports different configurations: + +### 1. Standard Build +```bash +./docker-build.sh +``` +- Basic MCP server functionality +- REST API and WebSocket support +- No speech features + +### 2. Speech-Enabled Build +```bash +./docker-build.sh --speech +``` +- Includes wake word detection +- Speech-to-text capabilities +- Pulls required images: + - `onerahmet/openai-whisper-asr-webservice` + - `rhasspy/wyoming-openwakeword` + +### 3. GPU-Accelerated Build +```bash +./docker-build.sh --speech --gpu +``` +- All speech features +- CUDA GPU acceleration +- Optimized for faster processing +- Float16 compute type for better performance + +### Build Features +- ๐Ÿ”„ Automatic resource allocation +- ๐Ÿ’พ Memory-aware building +- ๐Ÿ“Š CPU quota management +- ๐Ÿงน Automatic cleanup +- ๐Ÿ“ Detailed build logs +- ๐Ÿ“Š Build summary and status + ## Environment Configuration ๐Ÿ”ง I've implemented a hierarchical configuration system: diff --git a/docs/getting-started/docker.md b/docs/getting-started/docker.md index 7a83eac..6b30f8e 100644 --- a/docs/getting-started/docker.md +++ b/docs/getting-started/docker.md @@ -5,6 +5,251 @@ parent: Getting Started nav_order: 3 --- -# Docker Deployment Guide ๐Ÿณ +# Docker Setup Guide ๐Ÿณ -Detailed guide for deploying MCP Server with Docker... \ No newline at end of file +## Overview + +I've designed the MCP server to run efficiently in Docker containers, with support for different configurations including speech processing and GPU acceleration. + +## Build Options ๐Ÿ› ๏ธ + +### 1. Standard Build +```bash +./docker-build.sh +``` + +This build includes: +- Core MCP server functionality +- REST API endpoints +- WebSocket/SSE support +- Basic automation features + +Resource usage: +- Memory: 50% of available RAM +- CPU: 50% per core +- Disk: ~200MB + +### 2. Speech-Enabled Build +```bash +./docker-build.sh --speech +``` + +Additional features: +- Wake word detection +- Speech-to-text processing +- Multiple language support + +Required images: +```bash +onerahmet/openai-whisper-asr-webservice:latest # Speech-to-text +rhasspy/wyoming-openwakeword:latest # Wake word detection +``` + +Resource requirements: +- Memory: 2GB minimum +- CPU: 2 cores minimum +- Disk: ~2GB + +### 3. GPU-Accelerated Build +```bash +./docker-build.sh --speech --gpu +``` + +Enhanced features: +- CUDA GPU acceleration +- Float16 compute type +- Optimized performance +- Faster speech processing + +Requirements: +- NVIDIA GPU +- CUDA drivers +- nvidia-docker runtime + +## Docker Compose Files ๐Ÿ“„ + +### 1. Base Configuration (`docker-compose.yml`) +```yaml +version: '3.8' +services: + homeassistant-mcp: + build: . + ports: + - "${HOST_PORT:-4000}:4000" + env_file: + - .env + - .env.${NODE_ENV:-development} + environment: + - NODE_ENV=${NODE_ENV:-development} + - PORT=4000 + - HASS_HOST + - HASS_TOKEN + - LOG_LEVEL=${LOG_LEVEL:-info} + volumes: + - .:/app + - /app/node_modules + - logs:/app/logs +``` + +### 2. Speech Support (`docker-compose.speech.yml`) +```yaml +services: + homeassistant-mcp: + environment: + - ENABLE_SPEECH_FEATURES=true + - ENABLE_WAKE_WORD=true + - ENABLE_SPEECH_TO_TEXT=true + + fast-whisper: + image: onerahmet/openai-whisper-asr-webservice:latest + volumes: + - whisper-models:/models + - audio-data:/audio + + wake-word: + image: rhasspy/wyoming-openwakeword:latest + devices: + - /dev/snd:/dev/snd +``` + +## Launch Commands ๐Ÿš€ + +### Standard Launch +```bash +# Build and start +./docker-build.sh +docker compose up -d + +# View logs +docker compose logs -f + +# Stop services +docker compose down +``` + +### With Speech Features +```bash +# Build with speech support +./docker-build.sh --speech + +# Start all services +docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d + +# View specific service logs +docker compose logs -f fast-whisper +docker compose logs -f wake-word +``` + +### With GPU Support +```bash +# Build with GPU acceleration +./docker-build.sh --speech --gpu + +# Start with GPU support +docker compose -f docker-compose.yml -f docker-compose.speech.yml \ + --env-file .env.gpu up -d +``` + +## Resource Management ๐Ÿ“Š + +The build script automatically manages resources: + +1. **Memory Allocation** + ```bash + TOTAL_MEM=$(free -m | awk '/^Mem:/{print $2}') + BUILD_MEM=$(( TOTAL_MEM / 2 )) + ``` + +2. **CPU Management** + ```bash + CPU_COUNT=$(nproc) + CPU_QUOTA=$(( CPU_COUNT * 50000 )) + ``` + +3. **Build Arguments** + ```bash + BUILD_ARGS=( + --memory="${BUILD_MEM}m" + --memory-swap="${BUILD_MEM}m" + --cpu-quota="${CPU_QUOTA}" + ) + ``` + +## Troubleshooting ๐Ÿ”ง + +### Common Issues + +1. **Build Failures** + - Check system resources + - Verify Docker daemon is running + - Ensure network connectivity + - Review build logs + +2. **Speech Processing Issues** + - Verify audio device permissions + - Check CUDA installation (for GPU) + - Monitor resource usage + - Review service logs + +3. **Performance Problems** + - Adjust resource limits + - Consider GPU acceleration + - Monitor container stats + - Check for resource conflicts + +### Debug Commands +```bash +# Check container status +docker compose ps + +# View resource usage +docker stats + +# Check logs +docker compose logs --tail=100 + +# Inspect configuration +docker compose config +``` + +## Best Practices ๐ŸŽฏ + +1. **Resource Management** + - Monitor container resources + - Set appropriate limits + - Use GPU when available + - Regular cleanup + +2. **Security** + - Use non-root users + - Limit container capabilities + - Regular security updates + - Proper secret management + +3. **Maintenance** + - Regular image updates + - Log rotation + - Resource cleanup + - Performance monitoring + +## Advanced Configuration โš™๏ธ + +### Custom Build Arguments +```bash +# Example: Custom memory limits +BUILD_MEM=4096 ./docker-build.sh --speech + +# Example: Specific CUDA device +CUDA_VISIBLE_DEVICES=1 ./docker-build.sh --speech --gpu +``` + +### Environment Overrides +```bash +# Production settings +NODE_ENV=production ./docker-build.sh + +# Custom port +HOST_PORT=5000 docker compose up -d +``` + +See [Configuration Guide](../configuration.md) for more environment options. \ No newline at end of file