Prerequisites

Before setting up Forja, make sure the following tools are installed on your development machine.

Required

Rust 1.97

The backend is written in Rust (2024 edition) and requires Rust 1.97. The repository pins the toolchain in rust-toolchain.toml, so rustup installs the correct version automatically on first build. Install rustup via:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify your installation:

rustc --version   # inside the repo, should print 1.97.0 (pinned by rust-toolchain.toml)
cargo --version

Node.js 24+

The admin dashboard and frontend templates require Node.js 24 or later. We recommend using nvm to manage versions:

# Install nvm (if you don't have it)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Install and use Node 24
nvm install 24
nvm use 24

Verify:

node --version   # should print v24.x.x or higher
npm --version

Docker & Docker Compose

Forja uses Docker to run PostgreSQL, Redis, and pgAdmin during development. Install Docker Desktop (which includes Docker Compose).

Verify:

docker --version
docker compose version

SQLx CLI

The backend uses SQLx for database migrations. Install the CLI tool:

cargo install sqlx-cli --no-default-features --features rustls,postgres

Verify:

sqlx --version

psql (PostgreSQL Client)

The seed script uses psql to load development data. It ships with any PostgreSQL installation:

• macOS (Homebrew): brew install libpq && brew link --force libpq
• Ubuntu/Debian: sudo apt install postgresql-client
• Arch: sudo pacman -S postgresql-libs

Verify:

psql --version

Optional

Clerk Account

The admin dashboard uses Clerk for user authentication. You will need a free Clerk account to enable login in the admin UI.

1. Sign up at clerk.com.
2. Create an application.
3. Copy your Publishable Key (pk_test_...) and Secret Key (sk_test_...).
4. You will add these to your .env during the Configuration step.

tip

Clerk is optional for API-only usage. You can interact with the backend using API keys (X-API-Key header) without any Clerk setup.

pgAdmin (built-in)

A pgAdmin instance is included in the Docker Compose stack and available at localhost:5050 after starting Docker. Default credentials:

Field	Value
Email	admin@forja.dev
Password	admin

Summary

Tool	Version	Install
Rust	1.97 (pinned via rust-toolchain.toml)	rustup
Node.js	24+	nvm or nodejs.org
Docker	Latest	docker.com
SQLx CLI	Latest	cargo install sqlx-cli
psql	Any	System package manager
Clerk	--	clerk.com (optional)

Once everything is installed, proceed to Installation.