Docker support

DOCKER.md

@@ -0,0 +1,87 @@
+# Docker Setup for AsyncReview
+
+This guide explains how to run AsyncReview using Docker, both for production (immutable usage) and local development.
+
+## Prerequisites
+
+- **Docker** and **Docker Compose** installed on your machine.
+- A `.env` file with your API keys (see [README.md](README.md) or copy `.env.example`).
+
+**Note:** You *must* create a `.env` file before running any Docker commands.
+```bash
+cp .env.example .env
+# Edit .env and add your GEMINI_API_KEY
+```
+
+## Quick Start (Production/User Mode)
+
+To run the application in a stable, immutable container environment using the convenience Makefile command:
+
+```bash
+make docker-up
+```
+
+Alternatively, using Docker Compose directly:
+```bash
+docker compose up --build
+```
+
+- **Web UI:** http://localhost:3000
+- **API:** Proxied via the Web UI at http://localhost:3000/api
+  - Note: The backend service is not directly exposed to the host in production mode.
+
+To stop the application:
+```bash
+docker compose down
+```
+
+## Local Development
+
+To run the application in development mode with hot-reloading (changes to your code are immediately reflected):
+
+```bash
+make docker-dev
+```
+
+Alternatively, using Docker Compose directly (requires both files):
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+```
+
+- **Web UI:** http://localhost:5173 (Vite dev server)
+- **API:** http://localhost:8000 (Direct access for debugging)
+
+*Note: In development mode, the `web/` directory and the root directory are mounted into the containers. Changes you make locally will trigger reloads.*
+
+## Running CLI Commands
+
+You can run the `cr` CLI tool inside the backend container.
+
+**In Production Mode:**
+```bash
+docker compose run --rm backend cr --help
+docker compose run --rm backend cr review --url https://github.com/org/repo/pull/123
+```
+
+**In Development Mode:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm backend cr --help
+```
+
+## Troubleshooting
+
+### Port Conflicts
+If port 3000, 8000, or 5173 are in use, you can modify the ports in `docker-compose.yml` or `docker-compose.dev.yml`.
+
+### Deno/Pyodide Issues
+The backend container installs Deno and caches the Pyodide environment during the build. If you encounter issues, try rebuilding:
+```bash
+docker compose build --no-cache backend
+```
+
+### Dependencies
+If you add new Python dependencies to `pyproject.toml`, you must rebuild the backend container:
+```bash
+docker compose build backend
+```
+In development mode, since the source is mounted but dependencies are installed in the system python path, a rebuild is usually required to install new dependencies.

Dockerfile.backend

@@ -0,0 +1,38 @@
+# Base image
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+# explicit path to ensure it's available
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# Install Deno
+ENV DENO_INSTALL="/root/.deno"
+RUN curl -fsSL https://deno.land/install.sh | sh
+ENV PATH="$DENO_INSTALL/bin:$PATH"
+
+# Set working directory
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml README.md ./
+COPY cr/ ./cr/
+COPY cli/ ./cli/
+
+# Install python dependencies
+# We use --system to install into the container's system python environment
+RUN uv pip install --system .
+
+# Cache Deno dependencies
+RUN deno cache npm:pyodide/pyodide.js
+
+# Expose port
+EXPOSE 8000
+
+# Default command
+CMD ["uvicorn", "cr.server:app", "--host", "0.0.0.0", "--port", "8000"]

Makefile

@@ -8,12 +8,16 @@
 #   make all            - Build, install, and test
 #   make clean          - Clean build artifacts
 #
+# Docker Usage:
+#   make docker-up      - Run production environment (User mode)
+#   make docker-dev     - Run development environment (Hot-reload)
+#
 # Version Management:
 #   make bump-patch     - Bump patch version (0.5.0 -> 0.5.1)
 #   make bump-minor     - Bump minor version (0.5.0 -> 0.6.0)
 #   make bump-major     - Bump major version (0.5.0 -> 1.0.0)
 
-.PHONY: all build install test publish clean bump-patch bump-minor bump-major version
+.PHONY: all build install test publish clean bump-patch bump-minor bump-major version docker-up docker-dev
 
 # Version file - single source of truth
 VERSION_FILE := VERSION
@@ -75,6 +79,20 @@ clean:
 	@rm -rf .runtime_stage
 	@echo "Done."
 
+# ============================================================
+# Docker Helpers
+# ============================================================
+
+docker-up:
+	@if [ ! -f .env ]; then echo "Error: .env file not found. Copy .env.example to .env and fill in API keys."; exit 1; fi
+	@echo "==> Starting AsyncReview in Production Mode (Immutable)..."
+	@docker compose up --build
+
+docker-dev:
+	@if [ ! -f .env ]; then echo "Error: .env file not found. Copy .env.example to .env and fill in API keys."; exit 1; fi
+	@echo "==> Starting AsyncReview in Development Mode (Hot-Reload)..."
+	@docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+
 # ============================================================
 # Version Management
 # ============================================================
@@ -171,6 +189,10 @@ publish-npm: $(VERSION_FILE)
 help:
 	@echo "AsyncReview Runtime Build System"
 	@echo ""
+	@echo "Docker Commands (Preferred):"
+	@echo "  make docker-up    - Run production environment (User mode)"
+	@echo "  make docker-dev   - Run development environment (Hot-reload)"
+	@echo ""
 	@echo "Build Commands:"
 	@echo "  make build        - Build runtime v$(VERSION) for $(PLATFORM)"
 	@echo "  make install      - Install built runtime locally"
@@ -197,4 +219,3 @@ help:
 	@echo "Dev Commands:"
 	@echo "  make build-npx    - Build TypeScript only"
 	@echo "  make dev URL=... Q=... - Run dev mode"
-

README.md

@@ -120,6 +120,8 @@ If you prefer manual configuration, point your agent to the skill definition fil
 
 To run the full backend server or web interface locally, please see the [Installation Guide](INSTALLATION.md).
 
+To run using **Docker**, see the [Docker Guide](DOCKER.md).
+
 ## License
 
 MIT

docker-compose.dev.yml

@@ -0,0 +1,24 @@
+services:
+  backend:
+    volumes:
+      - ./:/app
+      # Use anonymous volumes to prevent host directories from overwriting container directories
+      - /app/.venv
+      - /app/.deno
+    command: uvicorn cr.server:app --reload --host 0.0.0.0 --port 8000
+    ports:
+      - "8000:8000"
+    environment:
+      - WATCHFILES_FORCE_POLLING=true
+
+  frontend:
+    build:
+      target: dev
+    volumes:
+      - ./web:/app
+      - /app/node_modules
+    ports:
+      - "5173:5173"
+    environment:
+      - API_URL=http://backend:8000
+    command: npm run dev -- --host

docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend
+    env_file:
+      - .env
+    environment:
+      - PYTHONUNBUFFERED=1
+    restart: unless-stopped
+
+  frontend:
+    build:
+      context: ./web
+      dockerfile: Dockerfile
+      target: prod
+    ports:
+      - "3000:80"
+    depends_on:
+      - backend
+    restart: unless-stopped

web/Dockerfile

@@ -0,0 +1,25 @@
+# Base stage
+FROM node:20-alpine AS base
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+# Development stage
+FROM base AS dev
+# Expose default Vite port
+EXPOSE 5173
+# Command to run dev server, binding to all interfaces
+CMD ["npm", "run", "dev", "--", "--host"]
+
+# Build stage
+FROM base AS build
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine AS prod
+COPY --from=build /app/dist /usr/share/nginx/html
+# We will copy a custom nginx config to handle SPA routing and API proxying
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

web/nginx.conf

@@ -0,0 +1,40 @@
+server {
+    listen 80;
+    server_name localhost;
+
+    location / {
+        root /usr/share/nginx/html;
+        index index.html index.htm;
+        # Support SPA routing (redirect to index.html for non-existent files)
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Proxy API requests to the backend service
+    location /api/ {
+        proxy_pass http://backend:8000/api/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Support SSE (Server Sent Events)
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_set_header Connection '';
+        proxy_http_version 1.1;
+        chunked_transfer_encoding off;
+    }
+
+    # Health check
+    location /health {
+        proxy_pass http://backend:8000/health;
+    }
+
+    # Docs
+    location /docs {
+        proxy_pass http://backend:8000/docs;
+    }
+    location /openapi.json {
+        proxy_pass http://backend:8000/openapi.json;
+    }
+}