Shopify Liquid MCP Server

# Docker Usage Guide Complete guide for running the Shopify Liquid MCP Server with Docker. ## Quick Start ```bash # Pull the image docker pull florinel-chis/shopify-liquid-mcp:latest # Run the server docker run -it --rm florinel-chis/shopify-liquid-mcp:latest # Or build locally docker build -t shopify-liquid-mcp . docker run -it --rm shopify-liquid-mcp ``` ## Why Docker? ✅ **Consistent Environment** - Same setup everywhere ✅ **No Python Setup** - No need to manage Python versions ✅ **Isolated** - Doesn't interfere with system Python ✅ **Portable** - Easy to share with team ✅ **Production Ready** - Deploy anywhere Docker runs ## Building the Image ### From Source ```bash # Clone repository git clone https://github.com/florinel-chis/shopify-liquid-mcp.git cd shopify-liquid-mcp # Build image docker build -t shopify-liquid-mcp:latest . # Build with custom tag docker build -t shopify-liquid-mcp:v0.1.0 . # Build with build args docker build \ --build-arg PYTHON_VERSION=3.11 \ -t shopify-liquid-mcp:python311 \ . ``` ### Multi-Platform Build ```bash # For ARM64 and AMD64 docker buildx build \ --platform linux/amd64,linux/arm64 \ -t shopify-liquid-mcp:latest \ --push \ . ``` ## Running the Container ### Basic Usage ```bash # Interactive mode docker run -it shopify-liquid-mcp # Detached mode docker run -d --name shopify-liquid-mcp shopify-liquid-mcp # View logs docker logs -f shopify-liquid-mcp # Stop container docker stop shopify-liquid-mcp ``` ### With Persistent Data ```bash # Create named volume docker volume create mcp-data # Run with volume docker run -it --rm \ -v mcp-data:/data \ shopify-liquid-mcp # Run with bind mount docker run -it --rm \ -v $(pwd)/data:/data \ shopify-liquid-mcp ``` ### Custom Configuration ```bash # Custom database path docker run -it --rm \ -e SHOPIFY_LIQUID_DB_PATH=/data/custom.db \ -v mcp-data:/data \ shopify-liquid-mcp # Multiple environment variables docker run -it --rm \ -e SHOPIFY_LIQUID_DB_PATH=/data/mcp.db \ -e LOG_LEVEL=DEBUG \ -v mcp-data:/data \ shopify-liquid-mcp ``` ### Adding Custom Documentation ```bash # Create custom docs directory mkdir custom-docs echo "# My Custom Snippet" > custom-docs/my-snippet.md # Run with custom docs docker run -it --rm \ -v $(pwd)/custom-docs:/docs/custom:ro \ -v mcp-data:/data \ shopify-liquid-mcp ``` ## Docker Compose ### Basic Setup `docker-compose.yml`: ```yaml version: '3.8' services: shopify-liquid-mcp: image: shopify-liquid-mcp:latest container_name: shopify-liquid-mcp volumes: - mcp-data:/data environment: - SHOPIFY_LIQUID_DB_PATH=/data/shopify-liquid.db stdin_open: true tty: true restart: unless-stopped volumes: mcp-data: ``` ### With Custom Docs ```yaml version: '3.8' services: shopify-liquid-mcp: image: shopify-liquid-mcp:latest volumes: - mcp-data:/data - ./custom-docs:/docs/custom:ro environment: - SHOPIFY_LIQUID_DB_PATH=/data/shopify-liquid.db volumes: mcp-data: ``` ### Development Setup ```yaml version: '3.8' services: shopify-liquid-mcp: build: context: . dockerfile: Dockerfile volumes: - ./shopify_liquid_mcp:/app/shopify_liquid_mcp - mcp-data:/data environment: - SHOPIFY_LIQUID_DB_PATH=/data/dev.db - LOG_LEVEL=DEBUG command: python -m shopify_liquid_mcp.server volumes: mcp-data: ``` ### Commands ```bash # Start services docker-compose up -d # View logs docker-compose logs -f # Stop services docker-compose down # Rebuild docker-compose build # Exec into container docker-compose exec shopify-liquid-mcp bash # Restart docker-compose restart ``` ## Integration with Editors ### VS Code `.vscode/settings.json`: ```json { "mcp.servers": { "shopify-liquid": { "type": "docker", "image": "shopify-liquid-mcp:latest", "volumes": { "mcp-data": "/data" } } } } ``` ### Claude Desktop `claude_desktop_config.json`: ```json { "mcpServers": { "shopify-liquid": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "mcp-data:/data", "shopify-liquid-mcp:latest" ] } } } ``` ### Cursor Cursor MCP settings: ```json { "mcpServers": { "shopify-liquid": { "command": "docker", "args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"] } } } ``` ## Management ### Inspect Container ```bash # Container details docker inspect shopify-liquid-mcp # Container stats docker stats shopify-liquid-mcp # Container processes docker top shopify-liquid-mcp ``` ### Health Checks ```bash # Check health docker inspect --format='{{.State.Health.Status}}' shopify-liquid-mcp # View health logs docker inspect --format='{{json .State.Health}}' shopify-liquid-mcp | jq ``` ### Database Management ```bash # Backup database docker run --rm \ -v mcp-data:/data \ -v $(pwd):/backup \ alpine \ cp /data/shopify-liquid.db /backup/backup.db # Restore database docker run --rm \ -v mcp-data:/data \ -v $(pwd):/backup \ alpine \ cp /backup/backup.db /data/shopify-liquid.db # Access database docker run -it --rm \ -v mcp-data:/data \ alpine \ sqlite3 /data/shopify-liquid.db ``` ## Optimization ### Image Size ```bash # Check image size docker images shopify-liquid-mcp # Use slim base FROM python:3.10-slim # Multi-stage build FROM python:3.10 as builder # ... build steps FROM python:3.10-slim COPY --from=builder /app /app ``` ### Performance ```bash # Allocate more resources docker run -it --rm \ --memory="512m" \ --cpus="1.0" \ shopify-liquid-mcp # Use tmpfs for database (faster, not persistent) docker run -it --rm \ --tmpfs /data:rw,size=100m \ shopify-liquid-mcp ``` ## Troubleshooting ### Container Won't Start ```bash # Check logs docker logs shopify-liquid-mcp # Run with debug docker run -it --rm \ -e LOG_LEVEL=DEBUG \ shopify-liquid-mcp # Interactive shell docker run -it --rm \ --entrypoint /bin/bash \ shopify-liquid-mcp ``` ### Database Issues ```bash # Reindex documentation docker run -it --rm \ -v mcp-data:/data \ shopify-liquid-mcp \ python -m shopify_liquid_mcp.ingest --force # Check database docker run -it --rm \ -v mcp-data:/data \ shopify-liquid-mcp \ sqlite3 /data/shopify-liquid.db "SELECT COUNT(*) FROM liquid_docs;" ``` ### Permission Issues ```bash # Run as specific user docker run -it --rm \ --user $(id -u):$(id -g) \ -v mcp-data:/data \ shopify-liquid-mcp # Fix permissions docker run -it --rm \ -v mcp-data:/data \ alpine \ chown -R 1000:1000 /data ``` ## Production Deployment ### Docker Swarm ```yaml version: '3.8' services: shopify-liquid-mcp: image: shopify-liquid-mcp:latest deploy: replicas: 3 restart_policy: condition: on-failure resources: limits: cpus: '0.5' memory: 256M volumes: - mcp-data:/data volumes: mcp-data: driver: local ``` ### Kubernetes ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: shopify-liquid-mcp spec: replicas: 2 selector: matchLabels: app: shopify-liquid-mcp template: metadata: labels: app: shopify-liquid-mcp spec: containers: - name: mcp-server image: shopify-liquid-mcp:latest resources: limits: memory: "256Mi" cpu: "500m" volumeMounts: - name: data mountPath: /data volumes: - name: data persistentVolumeClaim: claimName: mcp-data ``` ## Security ### Non-Root User ```dockerfile # Add in Dockerfile RUN useradd -m -u 1000 mcp USER mcp ``` ### Read-Only Filesystem ```bash docker run -it --rm \ --read-only \ --tmpfs /tmp \ -v mcp-data:/data \ shopify-liquid-mcp ``` ### Security Scanning ```bash # Scan image docker scan shopify-liquid-mcp:latest # Use Trivy trivy image shopify-liquid-mcp:latest ``` ## Resources - [Docker Documentation](https://docs.docker.com/) - [Best Practices](https://docs.docker.com/develop/dev-best-practices/) - [Docker Compose](https://docs.docker.com/compose/) --- **Need help?** Open an issue on [GitHub](https://github.com/florinel-chis/shopify-liquid-mcp/issues)