Installation

This guide walks you through installing all prerequisites and the FORGE CLI itself. FORGE generates projects that rely on Rust, Node.js, Docker, and PostgreSQL, so each of these must be available on your system before you begin.

Prerequisites

Requirement	Minimum Version	Purpose
Rust	1.75+	Backend compilation and FORGE CLI
Node.js	18+	Frontend development (Next.js)
Docker	24+	Containers for PostgreSQL, Redis, Caddy
Docker Compose	2.20+	Multi-container orchestration
PostgreSQL	15+	Primary database (runs in Docker)
Redis	7+	Caching and session store (runs in Docker)

You do not need to install PostgreSQL or Redis directly

Both services run inside Docker containers managed by FORGE. You only need Docker installed and running.

Step 1: Install Rust

FORGE is written in Rust and distributed as a Cargo package. Install Rust using rustup:

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

After installation, ensure the Rust toolchain is on your PATH:

source $HOME/.cargo/env
rustc --version   # Should show 1.75.0 or higher

Already have Rust installed?

Make sure you are on version 1.75 or later. Run rustup update to upgrade to the latest stable release.

Step 2: Install Node.js

The generated frontend applications use Next.js, which requires Node.js 18 or later. We recommend using nvm to manage Node versions:

nvm (recommended)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install and use Node.js 20 LTS
nvm install 20
nvm use 20
node --version   # Should show v20.x.x

Homebrew (macOS)

brew install node@20
node --version

Official installer

# Download from https://nodejs.org/
# Choose the LTS version (20.x)
node --version

Step 3: Install Docker

Docker runs your database, cache, and reverse proxy in isolated containers. Install Docker Desktop for your platform:

macOS

# Download Docker Desktop from https://docker.com/products/docker-desktop
# Or install via Homebrew:
brew install --cask docker

Linux (Ubuntu/Debian)

# Install using the official convenience script
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker compose version

Windows

# Download Docker Desktop from https://docker.com/products/docker-desktop
# Requires WSL 2 backend
# After installation, verify in PowerShell:
docker --version
docker compose version

Verify Docker is running:

docker --version          # Docker 24.0+ required
docker compose version    # Docker Compose 2.20+ required

Step 4: Install FORGE CLI

With Rust installed, install the FORGE CLI via Cargo:

cargo install forge-cli

Verify the installation:

forge --version

You should see output similar to:

FORGE v1.0.0
The Application Factory

Updating FORGE

To update to the latest version, run the same install command. Cargo will replace the existing binary:

cargo install forge-cli --force

Step 5: Install mkcert (Local SSL)

FORGE uses mkcert to generate locally-trusted SSL certificates so your development environment runs over HTTPS — matching production behavior exactly.

macOS

brew install mkcert
brew install nss    # Required for Firefox support

Linux (Ubuntu/Debian)

sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

Windows

choco install mkcert
# Or download from https://github.com/FiloSottile/mkcert/releases

After installing mkcert, install the local Certificate Authority:

mkcert -install

This creates a local CA that your system and browsers will trust. FORGE uses this CA when generating SSL certificates for your project domains.

Do not skip mkcert installation

Without mkcert, FORGE cannot generate trusted SSL certificates. Your development environment will either run without HTTPS or show browser security warnings. Use the --no-ssl flag with forge new only if you have a specific reason to skip SSL.

Verifying Your Environment

Run this checklist to confirm everything is ready:

# Rust toolchain
rustc --version        # 1.75+
cargo --version        # 1.75+

# Node.js runtime
node --version         # 18+
npm --version          # 9+

# Docker engine
docker --version       # 24+
docker compose version # 2.20+

# FORGE CLI
forge --version          # Should display version

# mkcert (optional but recommended)
mkcert --version       # Any recent version

All checks passing?

You are ready to create your first FORGE application. Head to the Quick Start guide.

Troubleshooting

cargo install fails with compilation errors

Ensure you have the required system libraries. On Ubuntu/Debian:

sudo apt install build-essential pkg-config libssl-dev

On macOS, install Xcode Command Line Tools:

xcode-select --install

Docker permission denied on Linux

If you see permission denied while trying to connect to the Docker daemon, add your user to the docker group and re-login:

sudo usermod -aG docker $USER
# Log out and log back in

mkcert -install requires sudo on Linux

This is expected. mkcert needs to install the root CA into the system trust store:

sudo mkcert -install

Next Steps

• Quick Start — Create and launch your first FORGE application
• Configuration — Learn about forge.yaml and environment variables