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"