From 507c36c1de7ee08e5c60aaa4fa3a90ec205e2d8c Mon Sep 17 00:00:00 2001 From: Forge Date: Mon, 6 Jul 2026 13:06:00 +0000 Subject: [PATCH] [AISOS-2125] Add concrete local setup instructions to Forge README Detailed description: - Updated the 'Quick Start' section in README.md to list Prerequisites, Core Services (Redis Stack, API gateway, worker, and container build instructions), and Optional Observability Services (Prometheus, Grafana, and Langfuse tracing configuration). - Injected a new test file 'tests/unit/test_readme_integrity.py' to programmatically verify that all required commands, paths, and configurations are correctly documented. Closes: AISOS-2125 --- README.md | 57 ++++++++++++++++++++++++----- tests/unit/test_readme_integrity.py | 31 ++++++++++++++++ 2 files changed, 79 insertions(+), 9 deletions(-) create mode 100644 tests/unit/test_readme_integrity.py diff --git a/README.md b/README.md index 29f310c1..3ddf7be6 100644 --- a/README.md +++ b/README.md @@ -168,28 +168,67 @@ Jira and GitHub send webhooks to Forge. Forge queues events, resumes the right w ## Quick Start -To run Forge locally you need: +### 1. Prerequisites -- 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 +Before running Forge locally, ensure you have the following installed and configured: -Then: +- **Python 3.11+** +- **Podman** (or Docker) +- **API Access Tokens**: + - Jira Cloud API credentials (base URL, API token, user email) + - GitHub personal access token (with repository scope) + - LLM Backend Access (Anthropic Claude API credentials or Google Vertex AI authentication) + +### 2. Core Services + +To start the local development environment, clone the repository, synchronize the environment, and spin up the required core services: ```bash git clone https://github.com/Forge-sdlc/forge.git cd forge uv sync cp .env.example .env +# Edit .env with your Jira, GitHub, and LLM credentials + +# 1. Start Redis Stack (using developer compose configuration) +docker compose -f devtools/docker-compose.dev.yml up -d redis + +# 2. Build the container image for isolated code execution podman build -t forge-dev:latest -f containers/Containerfile containers/ -docker compose up redis -d + +# 3. Start the FastAPI Gateway uv run uvicorn forge.main:app --reload --port 8000 --host 0.0.0.0 + +# 4. Start the background worker process uv run forge worker ``` +### 3. Optional Observability Services + +Forge supports extensive real-time telemetry, including Prometheus metrics, Langfuse traces, and local Grafana dashboards. + +#### Monitoring (Prometheus & Grafana) + +Run Prometheus and Grafana for metrics and dashboard visualization: + +```bash +docker compose -f devtools/docker-compose.dev.yml up -d prometheus grafana +``` + +Access the service consoles via these local endpoints: +- **Prometheus Dashboard:** [http://localhost:9092](http://localhost:9092) +- **Grafana Dashboards:** [http://localhost:3010](http://localhost:3010) (default credentials: `admin` / `grafana`) + +#### Tracing (Langfuse) + +To capture workflow execution steps, inputs, and outputs with Langfuse, configure your `.env` file with your credentials: + +```env +LANGFUSE_PUBLIC_KEY="pk-lf-..." +LANGFUSE_SECRET_KEY="sk-lf-..." +LANGFUSE_HOST="https://cloud.langfuse.com" # Or your custom/local endpoint +``` + 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/test_readme_integrity.py b/tests/unit/test_readme_integrity.py new file mode 100644 index 00000000..5ef5d19b --- /dev/null +++ b/tests/unit/test_readme_integrity.py @@ -0,0 +1,31 @@ +"""Test suite verifying README.md structure and content integrity.""" + +import os +from pathlib import Path + + +def test_readme_exists_and_contains_quickstart(): + # Find the repository root README.md + readme_path = Path("/workspace/README.md") + assert readme_path.exists(), "README.md does not exist at root" + + content = readme_path.read_text() + + # Assert presence of key quick start headings and instructions + assert "## Quick Start" in content, "README is missing '## Quick Start' section" + assert "### 1. Prerequisites" in content, "README is missing Prerequisites subsection" + assert "### 2. Core Services" in content, "README is missing Core Services subsection" + assert "### 3. Optional Observability Services" in content, "README is missing Optional Observability Services subsection" + +def test_readme_contains_commands_and_paths(): + readme_path = Path("/workspace/README.md") + content = readme_path.read_text() + + # Verify the specific files/paths mentioned in the implementation plan + assert "devtools/docker-compose.dev.yml" in content, "README should mention the developer docker-compose file path" + assert "redis" in content, "README should contain redis instructions" + assert "prometheus" in content, "README should mention prometheus" + assert "grafana" in content, "README should mention grafana" + assert "LANGFUSE_PUBLIC_KEY" in content, "README should mention Langfuse configuration keys" + assert "uv run uvicorn forge.main:app" in content, "README should specify the FastAPI startup command" + assert "uv run forge worker" in content, "README should specify the worker startup command"