Installation & Setup

Forge Core is two apps in one repo: forge-core (the Fastify API server) and forge-ui (the Next.js admin dashboard). Both run locally for development; a third app, sister-app-demo, exists purely to exercise "Sign in with Forge" end-to-end as an example integrator.

Prerequisites

Node.js 18 or later
A MongoDB instance — local or remote
Yarn (this repo uses Yarn classic v1 workspaces)

Clone and install

git clone <this-repo>
cd casteluke-forge-core
yarn install

A single yarn install at the repo root installs dependencies for every workspace (apps/* and packages/*).

Configure forge-core

Copy apps/forge-core/.env.example to apps/forge-core/.env and fill in the values:

apps/forge-core/.env

FORGE_BASE_URL=http://localhost:3030
FORGE_PORT=3030
FORGE_CORE_SECRET=your_core_secret_here
FORGE_PROJECT_ID="casteluke-forge-core"
FORGE_PROJECT_NAME="Casteluke Forge Core"
FORGE_PROJECT_SLUG="casteluke-forge-core"
FORGE_PROJECT_DESCRIPTION="The core of Casteluke Forge, a platform to maintain project authentication and authorization."
FORGE_BETTER_AUTH_SECRET=your_better_auth_secret_here
FORGE_MONGODB_URI=mongodb://localhost:27017/forge-core
NODE_ENV=development

What each secret is for

FORGE_CORE_SECRET is the internal secret used by Forge Core's own middleware. FORGE_BETTER_AUTH_SECRET is Better Auth's signing/encryption secret — it also encrypts the private half of each JWKS signing key at rest, so treat it as highly sensitive and never rotate it without a plan (see documentation/SECURITY.md for the incident-response runbook).

Don't trust apps/forge-core/README.md for env var names

That README predates the FORGE_* naming convention and documents a different port (3001) and unprefixed variable names (BETTER_AUTH_SECRET, MONGODB_URI). The .env.example shown above reflects what the app actually reads today — use it, not the README.

Configure forge-ui

Copy apps/forge-ui/.env.example to apps/forge-ui/.env.local:

apps/forge-ui/.env.local

NEXT_PUBLIC_API_URL=http://localhost:3030

This points the dashboard at the Forge Core API origin. Next.js also proxies /api/* requests from the dashboard straight through to that origin (see apps/forge-ui/next.config.ts), so the browser never needs to know the API's real host directly.

Run both apps

# from the repo root — runs every app's dev script via Turborepo
yarn dev

# or run just one app
yarn workspace forge-core dev   # http://localhost:3030
yarn workspace forge-ui dev     # http://localhost:3000

On first boot, forge-core connects to MongoDB, initializes Better Auth, seeds the built-in roles, and bootstraps an owner account from the first verified sign-up. Once both apps are running, open http://localhost:3000 and sign up — the first verified account is automatically promoted to owner.

Live API reference

Forge Core serves interactive Swagger/OpenAPI docs at {FORGE_BASE_URL}/api/docs — e.g. http://localhost:3030/api/docs in local dev. That's the authoritative, always-current source for exact request/response shapes; this section covers concepts and workflows, and cross-links to it from the /docs/api-reference page.