Add Docker setup, Aussie config, docs; remove redundant run guides

shubham5080 · shubham5080 · commit 0ab21da91661 · 2026-03-02T10:55:27.000+05:30
Made-with: Cursor
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,34 @@
+# Dependencies and local state (never copy into image)
+.venv
+venv
+env
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+
+# Git and IDE
+.git
+.gitignore
+.cursor
+*.swp
+*.swo
+
+# Local data and secrets (mount at runtime instead)
+data/
+*.db
+.env
+.env.*
+!.env.example
+
+# Docs and dev artifacts (optional: keep repo small)
+*.log
+bot.log
+bot_output.log
+
+# Test and CI (not needed in production image)
+tests/
+.pre-commit-config.yaml
+htmlcov
+.coverage
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,34 @@
+# Gitcord - Offline-first Discord–GitHub automation engine
+# Production Dockerfile: minimal layers, non-root user, reproducible build.
+# Python 3.11 slim for smaller image and security updates.
+
+FROM python:3.11-slim
+
+# Prevent Python from writing bytecode and buffering stdout (cleaner logs in containers).
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install dependencies first (better layer caching: only re-run when deps change).
+# We copy only dependency manifests and source package, then install.
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends gosu \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip install --no-cache-dir -e . \
+    && useradd --create-home --shell /bin/bash appuser \
+    && chown -R appuser:appuser /app \
+    && mkdir -p /data && chown appuser:appuser /data
+
+# Config and entrypoint (entrypoint runs as root to chown /data, then gosu to appuser).
+COPY config/ ./config/
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+# Default: run Discord bot. Override with run-once or other commands.
+# Example: docker compose run --rm bot --config /app/config/config.yaml run-once
+ENTRYPOINT ["/docker-entrypoint.sh"]
+CMD ["--config", "/app/config/config.yaml", "bot"]
diff --git a/README.md b/README.md
@@ -78,6 +78,7 @@ Gitcord is a local, offline‑first automation engine that reads GitHub activity
 1. [Main Repository](https://github.com/AOSSIE-Org/Gitcord-GithubDiscordBot)
 2. [Installation Guide](INSTALLATION.md) - Complete setup instructions
 3. [Technical Documentation](TECHNICAL_DOCUMENTATION.md) - Architecture and design
+4. [Docker Guide](docs/DOCKER.md) - Docker setup and mentor-friendly deployment
 
 ---
 
@@ -122,13 +123,29 @@ Load config -> Ingest -> Score -> Plan -> Audit -> (Optional) Apply
 
 Before installing Gitcord, you need:
 
-- ✅ **Python 3.11+** installed
 - ✅ **GitHub Organization** access
 - ✅ **Discord Server** with admin permissions
 - ✅ **GitHub Personal Access Token** (fine-grained PAT) - [How to create](INSTALLATION.md#step-1-create-github-token-pat)
 - ✅ **Discord Bot Token** - [How to create](INSTALLATION.md#step-2-create-discord-bot)
 
-### Quick Setup Overview
+### Quick Start with Docker (recommended for mentors)
+
+If you have Docker installed, you can skip Python setup and run Gitcord in one go:
+
+```bash
+git clone https://github.com/AOSSIE-Org/Gitcord-GithubDiscordBot.git
+cd Gitcord-GithubDiscordBot
+cp .env.example .env          # Add your GITHUB_TOKEN and DISCORD_TOKEN
+cp config/docker-example.yaml config/config.yaml   # Set github.org and discord.guild_id
+docker compose up -d
+```
+
+The Discord bot stays running; SQLite data and reports persist in a Docker volume. To run a one-off sync (e.g. dry-run):  
+`docker compose run --rm bot --config /app/config/config.yaml run-once`
+
+See **[docs/DOCKER.md](docs/DOCKER.md)** for details, pitfalls, and audit-first workflow.
+
+### Quick Setup Overview (local Python install)
 
 **1. Create GitHub Token** ([Detailed Guide](INSTALLATION.md#step-1-create-github-token-pat))
 
diff --git a/config/aussie.yaml b/config/aussie.yaml
@@ -0,0 +1,54 @@
+# Gitcord config for Aussie organization (AOSSIE-Org).
+# Set GITHUB_TOKEN and DISCORD_TOKEN in .env, or replace the token values below.
+# For Docker: set data_dir to "/data" and use: docker compose run --rm bot --config /app/config/aussie.yaml bot
+
+runtime:
+  mode: "dry-run"
+  log_level: "INFO"
+  data_dir: "./data/aussie"
+  github_adapter: "ghdcbot.adapters.github.rest:GitHubRestAdapter"
+  discord_adapter: "ghdcbot.adapters.discord.api:DiscordApiAdapter"
+  storage_adapter: "ghdcbot.adapters.storage.sqlite:SqliteStorage"
+
+github:
+  org: "AOSSIE-Org"
+  token: "${GITHUB_TOKEN}"
+  api_base: "https://api.github.com"
+  permissions:
+    read: true
+    write: false
+  user_fallback: false
+
+discord:
+  guild_id: "1022871757289422898"
+  token: "${DISCORD_TOKEN}"
+  permissions:
+    read: true
+    write: false
+  activity_channel_id: null
+  pr_preview_channels: []
+
+scoring:
+  period_days: 30
+  weights:
+    issue_opened: 3
+    pr_opened: 5
+    pr_reviewed: 2
+    comment: 1
+
+role_mappings:
+  - discord_role: "Contributor"
+    min_score: 10
+  - discord_role: "Maintainer"
+    min_score: 40
+
+assignments:
+  review_roles:
+    - "Maintainer"
+  issue_assignees:
+    - "Mentor"
+  issue_request_eligible_roles: []
+
+repo_contributor_roles: {}
+
+identity_mappings: []
diff --git a/config/docker-example.yaml b/config/docker-example.yaml
@@ -0,0 +1,53 @@
+# Gitcord config for Docker: data_dir must be /data (mounted volume).
+# Copy to config/config.yaml and set github.org, discord.guild_id, and tokens in .env.
+
+runtime:
+  mode: "dry-run"
+  log_level: "INFO"
+  data_dir: "/data"
+  github_adapter: "ghdcbot.adapters.github.rest:GitHubRestAdapter"
+  discord_adapter: "ghdcbot.adapters.discord.api:DiscordApiAdapter"
+  storage_adapter: "ghdcbot.adapters.storage.sqlite:SqliteStorage"
+
+github:
+  org: "example-org"
+  token: "${GITHUB_TOKEN}"
+  api_base: "https://api.github.com"
+  permissions:
+    read: true
+    write: false
+  user_fallback: false
+
+discord:
+  guild_id: "000000000000000000"
+  token: "${DISCORD_TOKEN}"
+  permissions:
+    read: true
+    write: false
+  activity_channel_id: null
+  pr_preview_channels: []
+
+scoring:
+  period_days: 30
+  weights:
+    issue_opened: 3
+    pr_opened: 5
+    pr_reviewed: 2
+    comment: 1
+
+role_mappings:
+  - discord_role: "Contributor"
+    min_score: 10
+  - discord_role: "Maintainer"
+    min_score: 40
+
+assignments:
+  review_roles:
+    - "Maintainer"
+  issue_assignees:
+    - "Mentor"
+  issue_request_eligible_roles: []
+
+repo_contributor_roles: {}
+
+identity_mappings: []
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,19 @@
+# Gitcord - Docker Compose for mentor-friendly deployment.
+# Usage: copy .env and config, then run: docker compose up -d
+# Data (SQLite, reports, identity links) persists in named volume gitcord_data.
+
+services:
+  bot:
+    build: .
+    image: gitcord:latest
+    env_file: .env
+    volumes:
+      # Mount config so you can edit YAML without rebuilding (use data_dir: /data in config).
+      - ./config:/app/config:ro
+      # Persist SQLite state, reports, and audit logs between restarts.
+      - gitcord_data:/data
+    command: ["--config", "/app/config/config.yaml", "bot"]
+    restart: unless-stopped
+
+volumes:
+  gitcord_data:
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+# Ensure /data is writable by appuser (named volume may be root-owned on first run).
+chown -R appuser:appuser /data 2>/dev/null || true
+exec gosu appuser ghdcbot "$@"
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
@@ -0,0 +1,129 @@
+# Gitcord Docker Guide
+
+Docker support is designed for **mentor-friendly deployment** and **reproducible runs** without changing Gitcord’s offline-first architecture. The bot and `run-once` both work; SQLite and reports persist across restarts.
+
+---
+
+## Why Docker?
+
+- **No local Python/setup**: Mentors run `docker compose up` after adding `.env` and config.
+- **Same behavior as CLI**: Same code paths; only the runtime is containerized.
+- **Persistent state**: Named volume keeps SQLite, reports, and identity links across restarts.
+- **Audit-first unchanged**: Dry-run and reports work the same; config and mutation policy are unchanged.
+
+---
+
+## Quick Start (3 steps)
+
+1. **Create `.env`** in the project root (copy from `.env.example`):
+
+   ```env
+   GITHUB_TOKEN=your_fine_grained_pat
+   DISCORD_TOKEN=your_discord_bot_token
+   ```
+
+2. **Create config** (use Docker-specific data dir):
+
+   ```bash
+   cp config/docker-example.yaml config/config.yaml
+   ```
+
+   Edit `config/config.yaml`: set `github.org`, `discord.guild_id`, and any other options. **Do not change `data_dir`**; it must stay `/data` so the mounted volume is used.
+
+3. **Start the bot**:
+
+   ```bash
+   docker compose up -d
+   ```
+
+   The Discord bot runs in the background. Slash commands sync within ~30 seconds.
+
+**Run a one-off sync (dry-run or active):**
+
+```bash
+docker compose run --rm bot --config /app/config/config.yaml run-once
+```
+(Do not pass `ghdcbot` — the image entrypoint is already `ghdcbot`.)
+
+---
+
+## Recommended Folder Structure
+
+```
+Gitcord-GithubDiscordBot/
+├── .env                    # Tokens (never commit; not in image)
+├── .env.example
+├── config/
+│   ├── config.yaml         # Your active config (data_dir: /data for Docker)
+│   ├── docker-example.yaml # Template for Docker
+│   └── example.yaml        # Template for local install
+├── docker-compose.yml
+├── Dockerfile
+├── pyproject.toml
+├── src/
+└── ...
+```
+
+**Inside the container:**
+
+- `/app` = app root (code, config mount at `/app/config`).
+- `/data` = persistent volume (SQLite `state.db`, `reports/`, `audit_events.jsonl`). Set `data_dir: "/data"` in config.
+
+---
+
+## Dockerfile Design (Why Each Part)
+
+| Section | Purpose |
+|--------|--------|
+| `FROM python:3.11-slim` | Matches `requires-python = ">=3.11"`; slim reduces image size and attack surface. |
+| `PYTHONDONTWRITEBYTECODE=1` | Avoids writing `.pyc` in the image; cleaner and slightly faster. |
+| `PYTHONUNBUFFERED=1` | Logs show up immediately in `docker compose logs`. |
+| Copy `pyproject.toml` + `src/` then `pip install -e .` | Dependency layer is cached; only code/setup changes trigger reinstall. |
+| `useradd appuser` / `USER appuser` | Process does not run as root. |
+| `ENTRYPOINT ["ghdcbot"]` | All invocations use the same binary; override with `run-once`, `bot`, etc. |
+| `CMD ["--config", "/app/config/config.yaml", "bot"]` | Default is Discord bot; overridden by `docker-compose` `command` or `docker run ... run-once`. |
+
+---
+
+## docker-compose.yml Design
+
+| Section | Purpose |
+|--------|--------|
+| `env_file: .env` | Loads `GITHUB_TOKEN` and `DISCORD_TOKEN`; config YAML uses `${GITHUB_TOKEN}` etc. |
+| `./config:/app/config:ro` | Host config dir mounted read-only; edit YAML on host without rebuilding. |
+| `gitcord_data:/data` | Named volume for SQLite and reports; survives `docker compose down`. |
+| `command: ["--config", "/app/config/config.yaml", "bot"]` | Ensures config path is correct and default is bot. |
+| `restart: unless-stopped` | Bot comes back after reboot or Docker restart. |
+
+---
+
+## Common Pitfalls and How to Avoid Them
+
+| Pitfall | Cause | Fix |
+|--------|--------|-----|
+| **"Config file does not exist"** | No `config/config.yaml` or wrong path. | Copy `config/docker-example.yaml` to `config/config.yaml` and keep `data_dir: "/data"`. |
+| **"Missing required environment variable: GITHUB_TOKEN"** | `.env` missing or not loaded. | Create `.env` in project root (same dir as `docker-compose.yml`) with `GITHUB_TOKEN` and `DISCORD_TOKEN`. |
+| **State lost after restart** | `data_dir` pointed at a non-persistent path. | Use `data_dir: "/data"` and the provided `docker-compose` volume; do not override `/data` with a host path unless you intend to. |
+| **Bot doesn’t respond / "application did not respond"** | Same as non-Docker: slow storage or missing intents. | Ensure Server Members Intent is enabled; check logs with `docker compose logs -f`. |
+| **Permission errors on `/data`** | Container user cannot write. | Dockerfile already runs as `appuser`; the volume is writable by the container. If you use a host bind mount for `data`, ensure the host dir is writable (e.g. `chown` to the same UID as `appuser`). |
+| **Running both bot and run-once** | Need two invocations. | Bot: `docker compose up -d`. Run-once: `docker compose run --rm bot ghdcbot --config /app/config/config.yaml run-once`. |
+
+---
+
+## Audit-First Workflow in Docker
+
+1. Keep `runtime.mode: "dry-run"` in config.
+2. Run once:  
+   `docker compose run --rm bot --config /app/config/config.yaml run-once`
+3. Inspect reports in the volume (e.g. copy out or run a temporary container that mounts the same volume and cats the file):  
+   Reports are under `/data/reports/` (e.g. `audit.md`, `audit.json`).
+4. When satisfied, set `runtime.mode: "active"` and `discord.permissions.write: true` in config, then run `run-once` again or let the bot apply changes on the next sync.
+
+---
+
+## Production and Maintainability Notes
+
+- **Reproducibility**: Same image and config produce the same behavior; use tagged images if you need to pin versions.
+- **Secrets**: Never bake tokens into the image; use `.env` or a secrets manager and `env_file` / env.
+- **Updates**: Rebuild with `docker compose build --no-cache` after dependency or code changes; config and data are unchanged.
+- **Logs**: Use `docker compose logs -f bot` for live logs; log level is controlled by config `runtime.log_level`.
diff --git a/src/ghdcbot/engine/pr_context.py b/src/ghdcbot/engine/pr_context.py
@@ -127,7 +127,7 @@ def determine_mentor_signal(
     merged = pr.get("merged", False)
     
     if state != "open" or draft or merged:
-        if merged:
+        if merged or state == "merged":
             return "Merged"
         elif state == "closed":
             return "Closed"
diff --git a/tests/test_notifications.py b/tests/test_notifications.py
