# Developer Workstation

This guide helps you to set up your local environment for contributing to the Model Context Protocol (MCP) Gateway. It provides detailed instructions for tooling requirements, OS-specific notes, common pitfalls, and commit signing practices.

## Tooling Requirements

-   **Python** (>= 3.10)
    -   Download from [python.org](https://www.python.org/downloads/) or use your package manager (e.g., `brew install python` on macOS, `sudo apt-get install python3` on Ubuntu).
    -   Verify: `python --version`.
-   **Docker or Podman**
    -   **Docker**: Install `docker.io`, `buildx`, and `docker-compose v2`.
        -   [Docker Desktop](https://www.docker.com/products/docker-desktop/) for macOS/Windows.
        -   Linux: `sudo apt-get install docker.io docker-buildx-plugin docker-compose-plugin` (Debian/Ubuntu) or `sudo dnf install docker docker-buildx docker-compose` (Fedora).
    -   **Podman**: Install [Podman Desktop](https://podman-desktop.io/downloads) for a rootless alternative.
    -   Verify: `docker --version` or `podman --version`.
-   **Permissions Setup**
    -   **Docker**: Add your user to the `docker` group: `sudo usermod -aG docker $USER`, then log out and back in (Linux). Restart Docker Desktop (Windows/macOS).
    -   **Podman**: Configure rootless mode with `podman system service`.
-   **Docker Compose or Compatible Wrapper**
    -   Included with Docker Desktop or as `docker-compose-plugin`.
    -   For Podman: `pip install podman-compose`.
    -   Verify: `docker compose version` or `podman-compose --version`.
-   **GNU Make**
    -   macOS: `brew install make`.
    -   Linux: `sudo apt-get install make` or `sudo dnf install make`.
    -   Windows: Install via [Chocolatey](https://chocolatey.org/) (`choco install make`) or use WSL2.
    -   Verify: `make --version`.
-   **(Optional) uv, ruff, mypy, isort**
    -   Install: `pip install uv ruff mypy isort`.
    -   Usage: Run `ruff check .` or `mypy .` for linting/type checking.
-   **Node.js and npm** (for UI linters)
    -   Install from [nodejs.org](https://nodejs.org/).
    -   Verify: `node --version` and `npm --version`.
    -   Install linters: `npm install -g eslint stylelint`.
-   **(Optional)Visual Studio Code and useful plugins**
    -   Download from [code.visualstudio.com](https://code.visualstudio.com/).

## OS-Specific Setup

### macOS

-   **Installation**:
    -   Install [Homebrew](https://brew.sh/): `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`.
    -   Run: `brew install python docker make node`.
-   **Apple Silicon**: Use Docker Desktop with ARM64 support. Homebrew handles architecture natively.
-   **Troubleshooting**: Ensure Rosetta 2 is installed for Intel-based tools if needed (`softwareupdate --install-rosetta`).

### Linux

-   **Installation**:
    -   Debian/Ubuntu: `sudo apt-get update && sudo apt-get install python3 docker.io docker-buildx-plugin docker-compose-plugin make nodejs npm`.
    -   Fedora: `sudo dnf install python3 docker docker-buildx docker-compose make nodejs npm`.
-   **Permissions**: Add user to `docker` group: `sudo usermod -aG docker $USER`, then reboot.
-   **Troubleshooting**: Use `systemctl start docker` if the service isn't running.

### Windows

-   **Recommended: WSL2**
    -   Install [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) and Ubuntu: `wsl --install`.
    -   Install Docker Desktop with WSL2 integration.
-   **File Paths and Volume Mounting**
    -   Use forward slashes (e.g., `/f/All/ibm/mcp-forge/mcp-context-forge`).
    -   Avoid spaces/special characters; use absolute paths in `docker run -v`.
-   **Podman in WSL2**
    -   Install: `sudo apt-get install podman` in WSL2.
    -   Port exposure: Use `podman system service` and configure firewall (`sudo ufw allow 4444`).
-   **Windows Terminal**
    -   Install from Microsoft Store. set WSL2 as default profile.
-   **Make Alternatives**
    -   Use WSL2's `make` or install via Chocolatey (`choco install make`).

## Common Gotchas

### Docker Socket Permissions

-   **Problem**: You may encounter "permission denied while connecting to the Docker daemon" if your user lacks access to the Docker socket.
-   **Fix**:
    -   **Linux**: Add your user to the `docker` group with `sudo usermod -aG docker $USER`, then log out and log back in. Verify with `docker ps`.
    -   **Windows/macOS**: Restart Docker Desktop from the system tray or settings menu.
-   **Troubleshooting**: If the issue persists, ensure the Docker service is running (`systemctl status docker` on Linux) or reinstall Docker Desktop.

### .venv Activation Across Shells

-   **Problem**: The virtual environment (`.venv`) may not activate automatically when opening new terminal sessions.
-   **Fix**:
    -   **Activate**: Use `source .venv/bin/activate` (Linux/macOS) or `.venv\Scripts\activate` (Windows) for each session.
    -   **Persist**: Add to your shell profile (e.g., `echo "source ./.venv/bin/activate" >> ~/.bashrc` for Bash on Linux). Replace `.` with the relative path to your `.venv` if different.
-   **Troubleshooting**: Verify activation with `which python` (should point to `.venv/bin/python`); deactivate with `deactivate` if needed.

### Port 4444 Already in Use

-   **Problem**: Port 4444, used by the MCP Gateway and MkDocs, may be occupied by another process, causing conflicts.
-   **Fix**:
    -   **Check**: Run `netstat -aon | findstr :4444` (Windows) or `ss -tuln | grep 4444` (Linux) to identify the process ID (PID).
    -   **Resolve**: Use a different port for MkDocs with `mkdocs serve --dev-addr=127.0.0.1:8001`, or stop the conflicting process (e.g., `taskkill /PID <PID>` on Windows or `kill <PID>` on Linux).
-   **Troubleshooting**: If unsure which process to stop, check with `docker ps` (if a container) or review running services.

## Snippet Examples

### Set Up and Serve Documentation

```bash
# Create and activate virtual environment
make venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install dependencies
make install

# Serve documentation locally
make serve
```

## Signing commits

To ensure commit integrity and comply with the DCO, sign your commits with a `Signed-off-by` trailer. Configure your Git settings:

```
# ~/.gitconfig
[user]
    name = Your Name
    email = your-exail@example.com

[init]
    defaultBranch = main  # Use 'main' instead of 'master' when creating new repos

[core]
    autocrlf = input       # On commit: convert CRLF to LF (Windows → Linux)
                           # On checkout: leave LF alone (no conversion)
    eol = lf               # Ensure all files in the repo use LF internally

[alias]
    cm = commit -s -m      # Short alias: 'git cm "message"' creates signed-off commit
    ca = commit --amend -s # Amend last commit and ensure it has a Signed-off-by trailer

[commit]
    template = ~/.git-commit-template
```

-   **Setup**: Replace Your Name and your-exail@example.com with your details.
-   **Signing**: Use git cm "Your message" to create signed commits automatically with the configured alias.
-   **Sign-off**: Use git commit -s -m "Your message" for manual signed commits without the alias.
