From a97955f604ff5b022931f3bdffe93f7220ac7cd4 Mon Sep 17 00:00:00 2001 From: Patryk Ciechanski Date: Thu, 12 Jun 2025 14:20:19 +0200 Subject: [PATCH 1/3] fix: Add multi-platform Docker build support for ARM64 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🔧 Added platforms: linux/amd64,linux/arm64 to Docker build to support: - Intel/AMD x86_64 systems - Apple Silicon M1/M2/M3 Macs (ARM64) - ARM64 Linux servers This fixes the 'no matching manifest for linux/arm64/v8' error when pulling images on Apple Silicon Macs. Also fixed missing space in IMAGE_NAME variable in attestation step. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .github/workflows/build_and_publish_docker.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build_and_publish_docker.yml b/.github/workflows/build_and_publish_docker.yml index 779c25b..d1683b6 100644 --- a/.github/workflows/build_and_publish_docker.yml +++ b/.github/workflows/build_and_publish_docker.yml @@ -51,6 +51,7 @@ jobs: uses: docker/build-push-action@v5 with: context: . + platforms: linux/amd64,linux/arm64 push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} @@ -60,7 +61,7 @@ jobs: - name: Generate artifact attestation uses: actions/attest-build-provenance@v1 with: - subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} + subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} subject-digest: ${{ steps.build.outputs.digest }} push-to-registry: true From 4272cf2ae70e89b0d4640baa09eaf4a9117def42 Mon Sep 17 00:00:00 2001 From: Patryk Ciechanski Date: Thu, 12 Jun 2025 14:21:08 +0200 Subject: [PATCH 2/3] fix: Generate latest tag for all version releases Changed latest tag condition from is_default_branch to github.ref_type == tag so that latest tag is created whenever any version tag (v*) is pushed, regardless of branch. This ensures that: - docker pull ghcr.io/patrykiti/zen-mcp-server:latest works - docker pull ghcr.io/patrykiti/zen-mcp-server:v4.0.8 works - No more SHA-only tags as primary tags --- .github/workflows/build_and_publish_docker.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build_and_publish_docker.yml b/.github/workflows/build_and_publish_docker.yml index d1683b6..ddfc2f1 100644 --- a/.github/workflows/build_and_publish_docker.yml +++ b/.github/workflows/build_and_publish_docker.yml @@ -42,7 +42,7 @@ jobs: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | type=ref,event=tag - type=raw,value=latest,enable={{is_default_branch}} + type=raw,value=latest,enable=${{ github.ref_type == 'tag' }} type=sha,prefix=main-,enable=${{ github.event_name == 'repository_dispatch' }} type=raw,value=pr-${{ github.event.client_payload.pr_number }},enable=${{ github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' }} From f47d16b3167dbf2eb1f431c9dd0d4ef930597ac8 Mon Sep 17 00:00:00 2001 From: Patryk Ciechanski Date: Thu, 12 Jun 2025 14:24:17 +0200 Subject: [PATCH 3/3] docs: Add comprehensive Windows setup guide for Docker support Added detailed Windows setup documentation covering: - Why WSL2 + Docker Desktop is required for Linux containers - Complete step-by-step Windows setup instructions - WSL2 installation and Docker Desktop configuration - Alternative Python installation method for Windows users - Windows-specific troubleshooting section - Claude Desktop config file location for Windows Updated both README.md and docs/user-guides/installation.md to provide clear guidance for Windows users who need to use WSL2 + Docker Desktop to run Linux-based Docker images. --- README.md | 91 +++++++++++++++++++++++++++++++- docs/user-guides/installation.md | 20 +++++-- 2 files changed, 107 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 61dee52..ffd0f63 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ The final implementation resulted in a 26% improvement in JSON parsing performan - Docker Desktop installed ([Download here](https://www.docker.com/products/docker-desktop/)) - Git -- **Windows users**: WSL2 is required for Claude Code CLI +- **Windows users**: WSL2 + Docker Desktop required for Docker images ### 1. Get API Keys (at least one required) - **Gemini**: Visit [Google AI Studio](https://makersuite.google.com/app/apikey) and generate an API key. For best results with Gemini 2.5 Pro, use a paid API key as the free tier has limited access to the latest models. @@ -1046,6 +1046,95 @@ The project includes GitHub Actions workflows that: The CI pipeline works without any secrets and will pass all tests using mocked responses. Simulation tests require API key secrets (`GEMINI_API_KEY` and/or `OPENAI_API_KEY`) to run the communication simulator. +## Windows Setup Guide + +**Windows users need WSL2 + Docker Desktop to run Linux-based Docker containers.** + +### Why WSL2 is Required + +Our Docker images use `python:3.11-slim` (Linux-based), which cannot run natively on Windows. Docker Desktop solves this by running containers in WSL2's Linux environment. + +### Complete Windows Setup + +1. **Install WSL2** + ```powershell + # Run in PowerShell as Administrator + wsl --install + # Restart computer when prompted + ``` + +2. **Install Docker Desktop for Windows** + - Download: [Docker Desktop for Windows](https://docs.docker.com/desktop/windows/install/) + - During installation, ensure "Use WSL 2 instead of Hyper-V" is selected + +3. **Configure Docker Desktop** + - Open Docker Desktop settings + - Go to "Resources" → "WSL Integration" + - Enable integration with your default WSL distro (usually Ubuntu) + +4. **Verify Setup** + ```bash + # In WSL2 terminal (Ubuntu) + docker --version + docker pull hello-world + docker run hello-world + ``` + +5. **Install Claude Desktop in Windows** + - Download and install Claude Desktop for Windows normally + - Docker commands will automatically route to WSL2 + +### Usage on Windows + +Once set up, everything works normally: + +```bash +# Pull the image (runs in WSL2 automatically) +docker pull ghcr.io/patrykiti/zen-mcp-server:latest + +# Configure Claude Desktop normally in Windows +# Docker Desktop handles WSL2 routing automatically +``` + +**Claude Desktop Config Location (Windows):** +``` +C:\Users\[USERNAME]\AppData\Roaming\Claude\claude_desktop_config.json +``` + +### Alternative: Direct Python Installation + +If you prefer not to use Docker: + +```powershell +# In PowerShell or Command Prompt +git clone https://github.com/PatrykIti/zen-mcp-server.git +cd zen-mcp-server +pip install -r requirements.txt + +# Set your API key +set GEMINI_API_KEY=your-api-key-here +# or create .env file + +# Run server directly +python server.py +``` + +Then configure Claude Desktop to use Python directly instead of Docker. + +### Windows Troubleshooting + +**"Docker command not found"** +- Ensure Docker Desktop is running +- Restart WSL2: `wsl --shutdown` then reopen terminal + +**"No matching manifest for linux/arm64"** +- Our images support both AMD64 and ARM64 +- If you see this error, your Docker setup may need reconfiguring + +**WSL2 not working** +- Enable virtualization in BIOS +- Run `wsl --update` in PowerShell as Administrator + ## Troubleshooting ### Common Issues diff --git a/docs/user-guides/installation.md b/docs/user-guides/installation.md index cd35fd8..00649d8 100644 --- a/docs/user-guides/installation.md +++ b/docs/user-guides/installation.md @@ -19,9 +19,23 @@ After following this guide, you'll have: 4. **Git** - For cloning the repository ### Platform Support -- ✅ **macOS** (Intel and Apple Silicon) -- ✅ **Linux** -- ✅ **Windows** (requires WSL2 for Claude Desktop) +- ✅ **macOS** (Intel and Apple Silicon M1/M2/M3) +- ✅ **Linux** (AMD64 and ARM64) +- ✅ **Windows** (requires WSL2 + Docker Desktop for Claude Desktop) + +### Windows Setup Requirements +**Windows users must use WSL2 + Docker Desktop:** +1. **Install WSL2** - [Microsoft WSL Guide](https://docs.microsoft.com/en-us/windows/wsl/install) +2. **Install Docker Desktop** - [Docker for Windows](https://docs.docker.com/desktop/windows/install/) +3. **Enable WSL2 integration** in Docker Desktop settings +4. **Run Claude Desktop** in Windows (Docker containers run in WSL2) + +**Why WSL2 is required:** +- Docker images are Linux-based (python:3.11-slim) +- Docker Desktop automatically runs containers in WSL2 Linux environment +- Provides full compatibility with Linux containers on Windows + +**Alternative for Windows:** Install Python directly and run server with `pip install -r requirements.txt && python server.py` ## 🚀 Setup Option 1: Published Docker Image (Fastest)