Skip to content

quickstart.md

Latest commit

 

History

History
94 lines (69 loc) · 2.93 KB

quickstart.md

File metadata and controls

94 lines (69 loc) · 2.93 KB
Raw

Forge self-hosting quickstart

Stand up a complete Forge instance on a single machine with Docker Compose. This is the fastest path from a clone to a running board, knowledge pipeline, and API. For the production hardening details see docker-compose.md; for day-2 operations see backup.md, restore.md, upgrade.md, security.md, and troubleshooting.md.

Prerequisites

  • Docker Engine 24+ and the Docker Compose v2 plugin (docker compose version).
  • 4 CPU cores and 8 GB RAM available to Docker (the default resource limits in the production compose file assume roughly this).
  • For local development from source instead of images: Python 3.14 with uv, Node 22 with pnpm, and make.

1. Clone and configure

git clone https://github.com/QuintinBotes/forge.git
cd forge
cp .env.example .env

Edit .env and set, at minimum:

  • SECRET_KEY and AUTH_SECRET — long random strings (e.g. openssl rand -hex 32).
  • POSTGRES_PASSWORD and MINIO_ROOT_PASSWORD — strong unique secrets.
  • DOMAIN — the hostname Caddy will serve (use localhost for a local trial).
  • MODEL_PROVIDER_KEY — your BYOK model provider key (Forge is provider agnostic; leave blank to run the platform without live model calls).

The full set of variables is documented inline in ../../.env.example.

2. Bring the stack up

docker compose -f deploy/docker-compose.yml up -d --remove-orphans

This starts Postgres (pgvector), Redis, MinIO, the API, the worker, the MCP gateway, the web UI, the Caddy edge proxy, and the autoheal sidecar. Watch services become healthy:

docker compose -f deploy/docker-compose.yml ps

3. Run database migrations

Apply the schema once the database is healthy:

docker compose -f deploy/docker-compose.yml exec api \
  alembic -c packages/db/alembic.ini upgrade head

4. Verify

curl -fsS http://localhost:8000/health

A 200 response means the API is up. Open the web UI at http://localhost:3000 (or https://$DOMAIN once Caddy has issued a certificate).

Local development (from source)

To iterate on the code instead of running published images, use the dev stack and the Makefile targets defined in ../../Makefile:

make setup    # uv sync + pnpm install
make migrate  # alembic upgrade head
make dev      # docker compose -f deploy/docker-compose.dev.yml up

Then run the test suite and linters:

make test     # uv run pytest
make lint     # ruff check + format --check

Next steps