Profile Compatibility & Deployment Matrix¶

This document provides a comprehensive compatibility matrix and reproducible setup instructions for running PatchDIFF profiles across operating systems and Docker environments.

1. Compatibility Overview¶

PatchDIFF profiles fall into two operational classes:

1. Workspace Synchronizer Profiles (observed_workspace, workspace):
2. Manage real filesystem directories (PATCHDIFF_WORKSPACE_ROOT).
3. POSIX Requirement: Directory writebacks use descriptor-relative operations (openat, O_NOFOLLOW, O_DIRECTORY, and fcntl.flock) to guard against symlinks, path traversal, and race conditions.
4. Requires a POSIX environment: Linux, WSL2, macOS, or Docker. Bare Windows cmd/PowerShell lacks fcntl.flock.
5. Inline Ledger Profiles (observed_v2, editor, unobserved_editor, hybrid_editor, full, etc.):
6. Targets are initialized directly in memory and managed exclusively inside the PostgreSQL ledger.
7. Universal Support: Runs natively across all operating systems (Bare Windows, WSL2, Linux, macOS) without filesystem lock requirements.

2. OS & Docker Configuration Compatibility Matrix¶

¹ Note for Bare Windows: Although inline-content patchdiff_initialize_target has no POSIX filesystem dependency, the workspace startup preflight check (_check_workspace_startup) executes before the MCP handshake and requires POSIX descriptor-relative operations and directory locks (fcntl.flock). Because bare Windows cmd/PowerShell lacks these primitives, the server refuses to start in workspace or observed_workspace profiles even for inline-only use. On Windows, run PatchDIFF inside WSL2 or Docker to use workspace profiles, or specify --profile observed_v2 or --profile editor for native bare Windows inline editing.

3. Dependency Requirements per Profile¶

4. Reproducible Setup Instructions by Environment¶

Configuration A: Windows with Docker Desktop (WSL2 Backend) (Recommended for Windows)¶

This configuration runs the PatchDIFF server inside WSL2 while PostgreSQL runs in Docker Desktop, with full support for the default observed_workspace profile.

Step 1: Enable Docker Desktop WSL Integration¶

1. Open Docker Desktop on Windows.
2. Go to Settings > Resources > WSL Integration.
3. Enable Turn on integration with additional distros and check your distribution (e.g. Ubuntu).
4. Click Apply & Restart.

Step 2: Start PostgreSQL Container¶

From PowerShell or inside your WSL terminal in the repository root:

docker compose up -d

docker ps --filter "name=patchdiff-postgres"

Step 3: Configure Environment in WSL2¶

Inside your WSL distribution, export the required environment variables:

# Point to Docker PostgreSQL (accessible via localhost in WSL2)
export PATCHDIFF_DATABASE_URL="postgresql+psycopg://patchdiff:patchdiff@127.0.0.1:5432/patchdiff"

# Point to your repository or working directory
export PATCHDIFF_WORKSPACE_ROOT="$(pwd)"

# Profile defaults to observed_workspace automatically
export PATCHDIFF_MCP_PROFILE="observed_workspace"

Step 4: Run Database Migrations¶

patchdiff-mcp --migrate

Step 5: Start the MCP Server¶

patchdiff-mcp

Configuration B: Bare Windows (No WSL2, Docker Desktop Host)¶

When running directly on Windows without WSL2, workspace filesystem sync is disabled due to missing POSIX descriptor locks. Use inline ledger profiles such as observed_v2, editor, or full.

Step 1: Start PostgreSQL via Docker Desktop¶

In PowerShell from the repository root:

docker compose up -d

Step 2: Set Environment Variables in PowerShell¶

$env:PATCHDIFF_DATABASE_URL = "postgresql+psycopg://patchdiff:patchdiff@127.0.0.1:5432/patchdiff"
# Select an inline profile (e.g. observed_v2 or editor)
$env:PATCHDIFF_MCP_PROFILE = "observed_v2"

Step 3: Run Migrations and Start Server¶

patchdiff-mcp --migrate
patchdiff-mcp

Configuration C: Native Linux with System Docker Engine¶

Full native Linux deployment with zero translation overhead.

Step 1: Start PostgreSQL¶

docker compose up -d

Step 2: Set Environment Variables¶

export PATCHDIFF_DATABASE_URL="postgresql+psycopg://patchdiff:patchdiff@127.0.0.1:5432/patchdiff"
export PATCHDIFF_WORKSPACE_ROOT="/path/to/your/project"
export PATCHDIFF_MCP_PROFILE="observed_workspace"

Step 3: Apply Migrations and Launch¶

patchdiff-mcp --migrate
patchdiff-mcp

Configuration D: macOS with Docker Desktop for Mac¶

macOS supports POSIX file locking natively, allowing observed_workspace to run directly on the host with Dockerized PostgreSQL.

Step 1: Start PostgreSQL¶

docker compose up -d

Step 2: Configure Environment¶

export PATCHDIFF_DATABASE_URL="postgresql+psycopg://patchdiff:patchdiff@127.0.0.1:5432/patchdiff"
export PATCHDIFF_WORKSPACE_ROOT="$(pwd)"
export PATCHDIFF_MCP_PROFILE="observed_workspace"

Step 3: Apply Migrations and Launch¶

patchdiff-mcp --migrate
patchdiff-mcp

Configuration E: Fully Containerized Deployment (Server + Database)¶

To run both PatchDIFF MCP server and PostgreSQL inside containers (e.g. on Kubernetes, remote runners, or isolated CI):

Dockerfile for PatchDIFF MCP Server¶

FROM python:3.11-slim

# Install Node.js 22 for Waymark AST discovery
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    git \
    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY pyproject.toml README.md LICENSE ./
COPY backend/ ./backend/
COPY integrations/ ./integrations/

# Install Python dependencies and package
RUN pip install --no-cache-dir -e .

# Install pinned Waymark engine
RUN npm --prefix integrations/waymark ci --omit=dev

ENV PATCHDIFF_WAYMARK_MODE=resident
ENV PATCHDIFF_MCP_PROFILE=observed_workspace

ENTRYPOINT ["patchdiff-mcp"]

docker-compose.server.yml¶

services:
  postgres:
    image: postgres:16.3-alpine
    container_name: patchdiff-postgres
    environment:
      POSTGRES_DB: patchdiff
      POSTGRES_USER: patchdiff
      POSTGRES_PASSWORD: patchdiff
    ports:
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U patchdiff -d patchdiff"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - patchdiff_postgres_data:/var/lib/postgresql/data

  patchdiff:
    build: .
    container_name: patchdiff-mcp
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      PATCHDIFF_DATABASE_URL: "postgresql+psycopg://patchdiff:patchdiff@postgres:5432/patchdiff"
      PATCHDIFF_WORKSPACE_ROOT: "/workspace"
      PATCHDIFF_MCP_PROFILE: "observed_workspace"
    volumes:
      - ./target_project:/workspace:rw
    stdin_open: true
    tty: false

volumes:
  patchdiff_postgres_data:

5. Port Conflicts & Troubleshooting¶

For host configuration, WSL2 resource compaction, and background process management, see the Troubleshooting & Operations Guide.