Local Setup¶

This page is a condensed reference. For the full walkthrough including payload-based testing, Prometheus metrics, Langfuse tracing, and debugging tools, see the Developer Guide.

Prerequisites¶

Tool	Install
Python 3.11+	python.org
uv	`curl -LsSf https://astral.sh/uv/install.sh \\| sh`
Podman	`brew install podman` / `dnf install podman`
Docker Compose	Included with Docker Desktop or `brew install docker-compose`

External accounts needed: Jira Cloud, GitHub, and LLM backend access through a direct model provider API or Vertex AI.

Installation¶

git clone https://github.com/forge-sdlc/forge.git
cd forge
uv sync
cp .env.example .env

Environment Variables¶

Edit .env — minimum required:

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_USER_EMAIL=you@example.com
JIRA_API_TOKEN=your-jira-api-token

GITHUB_TOKEN=github_pat_your_token

LLM_BACKEND=vertex-ai
GOOGLE_CLOUD_PROJECT=your-gcp-project
GOOGLE_CLOUD_LOCATION=global
LLM_MODEL=gemini-3.5-flash
REDIS_URL=redis://localhost:6380/0

For local development, also set:

FORGE_REQUIRE_PROJECT_CONFIG=false
GITHUB_DEFAULT_REPO=your-org/your-repo
GITHUB_KNOWN_REPOS=your-org/your-repo

See Reference: Configuration for all variables.

Build the Container Image¶

podman build -t forge-dev:latest -f containers/Containerfile containers/

Start Services¶

# Redis (the only service using Docker)
docker compose up redis -d

# API server
uv run uvicorn forge.main:app --reload --port 8000 --host 0.0.0.0

# Worker (must run on the host — spawns Podman containers)
uv run forge worker

Service Ports¶

Service	Port
API server	8000
Worker metrics	8001
Redis	6380

Webhook Setup¶

For local development, expose your server with ngrok:

ngrok http 8000

Then configure Jira and GitHub webhooks to point at the ngrok URL.

See the Developer Guide for payload-based testing without live webhooks.