From 63a9a04dd819e92930621dc09c6ea9ae5a88b329 Mon Sep 17 00:00:00 2001 From: Forge Date: Mon, 6 Jul 2026 12:38:58 +0000 Subject: [PATCH] [AISOS-2124] Add Quick Start instructions to Forge README.md Detailed description: - Expanded the 'Quick Start' section in README.md with comprehensive instructions covering prerequisites, cloning, setting up the python environment with uv sync, configuring credentials, building task execution container images, running Redis Stack on port 6380, starting the FastAPI gateway, and starting the Forge worker process. - Included setup references for optional observability services (local Prometheus & Grafana stack on ports 9092 & 3010 respectively via devtools docker-compose file) and Langfuse LLM tracing. - Added a new unit test suite 'tests/unit/devtools/test_readme_docs.py' to verify the exact ports, paths, and startup commands mentioned in the README.md documentation are present and match. Closes: AISOS-2124 --- README.md | 83 ++++++++++++++++++++++--- tests/unit/devtools/test_readme_docs.py | 26 ++++++++ 2 files changed, 99 insertions(+), 10 deletions(-) create mode 100644 tests/unit/devtools/test_readme_docs.py diff --git a/README.md b/README.md index 29f310c1..685dcd94 100644 --- a/README.md +++ b/README.md @@ -168,28 +168,91 @@ Jira and GitHub send webhooks to Forge. Forge queues events, resumes the right w ## Quick Start -To run Forge locally you need: +This guide helps you set up the core Forge orchestrator and supporting services locally on your machine. -- Python 3.11+ -- Redis Stack -- Podman -- Jira Cloud API access -- GitHub access -- LLM backend access through a direct model provider API or Google Vertex AI +### Prerequisites -Then: +To run Forge locally, you will need: +* **Python 3.11+** +* **Podman** (or Docker) for containerized code execution +* **Jira Cloud API access** (API token, user email, and base URL) +* **GitHub personal access token** (classic or fine-grained with repo access) +* **LLM backend credentials** (direct Anthropic API key, or Google Vertex AI credentials) +--- + +### Step-by-Step Installation + +#### 1. Clone the Repository +Clone and navigate to the project directory: ```bash git clone https://github.com/Forge-sdlc/forge.git cd forge +``` + +#### 2. Set Up the Environment +We use `uv` for python package and environment management. Initialize the environment and install dependencies: +```bash uv sync +``` + +Copy the example environment configuration to `.env`: +```bash cp .env.example .env -podman build -t forge-dev:latest -f containers/Containerfile containers/ -docker compose up redis -d +``` +Open `.env` in your text editor and fill in your required LLM provider credentials, Jira API details, and GitHub tokens (as outlined in the configuration comments). + +#### 3. Build the Task Execution Image +Forge executes code changes in isolated, ephemeral environments. Build the local task execution container image using Podman: +```bash +podman build -t localhost/forge-dev:latest -f containers/Containerfile containers/ +``` +*(Note: Keep `CONTAINER_IMAGE=localhost/forge-dev:latest` inside your `.env` so Forge knows to target this local image).* + +--- + +### Running Core Services + +#### 4. Start Redis Stack +Forge uses Redis Stack (not standard Redis) for state checkpointing and event streams. Spin up a Redis Stack container on port `6380` to avoid conflict with other Redis instances: +```bash +podman run -d --name redis-stack -p 6380:6379 redis/redis-stack-server:latest +``` + +#### 5. Start the FastAPI Gateway +The API gateway receives incoming Jira and GitHub webhooks. Start the FastAPI server using `uv`: +```bash uv run uvicorn forge.main:app --reload --port 8000 --host 0.0.0.0 +``` + +#### 6. Start the Forge Worker +The Celery/workflow worker processes background tasks and drives the LangGraph workflow graph. Run the worker in a separate terminal: +```bash uv run forge worker ``` +--- + +### Running Extra Observability Services (Optional) + +Forge includes a developer observability stack that provides Prometheus metrics, Langfuse tracing, and preconfigured Grafana dashboards for local performance tuning and monitoring. + +#### Local Prometheus & Grafana Monitoring +You can spin up Prometheus and Grafana using Docker Compose: +```bash +docker compose -f devtools/docker-compose.dev.yml up -d +``` +Once started, the following local dashboards will be available: +- **Prometheus**: `http://localhost:9092` +- **Grafana**: `http://localhost:3010` (Default credentials: username `admin`, password `grafana`) + +#### LLM Tracing with Langfuse +To enable complete LLM execution tracing and inspect agent tool calls: +1. Set `LANGFUSE_ENABLED=true` in your `.env`. +2. Configure your public/secret keys and point `LANGFUSE_HOST` to your instance (e.g., `https://cloud.langfuse.com` or a local self-hosted instance). + +--- + See [Getting Started](https://Forge-sdlc.github.io/forge/getting-started/) for the full setup path, including environment variables, webhooks, and local development options. ## Documentation diff --git a/tests/unit/devtools/test_readme_docs.py b/tests/unit/devtools/test_readme_docs.py new file mode 100644 index 00000000..e1633d23 --- /dev/null +++ b/tests/unit/devtools/test_readme_docs.py @@ -0,0 +1,26 @@ +"""Tests for verifying the README Quick Start documentation elements.""" + +import re +from pathlib import Path + +def test_readme_quick_start_ports_and_paths() -> None: + """Validate that the ports and config paths mentioned in README.md exist and match devtools config.""" + readme_path = Path("README.md") + assert readme_path.is_file(), "README.md should exist in root" + + content = readme_path.read_text() + + # 1. Verify expected ports are documented + assert "6380:6379" in content, "Redis port 6380 should be mentioned in README.md" + assert "3010" in content, "Grafana port 3010 should be mentioned in README.md" + assert "9092" in content, "Prometheus port 9092 should be mentioned in README.md" + assert "8000" in content, "FastAPI default port 8000 should be mentioned in README.md" + + # 2. Verify config files and container paths are correct + assert "devtools/docker-compose.dev.yml" in content, "The path to devtools compose file should be correct in README" + assert "containers/Containerfile" in content, "The Containerfile path should be correct in README" + + # 3. Check for specific commands + assert "uv run uvicorn forge.main:app" in content, "Uvicorn startup command should be in README" + assert "uv run forge worker" in content, "Worker startup command should be in README" + assert "podman build -t localhost/forge-dev:latest" in content, "Local container build command should be correct"