Skip to main content

Installation

This guide covers everything you need to install and set up Forge for development.

System Requirements​

Go Version​

Forge requires Go 1.26 or higher. Check your version:

go version

If you need to install or upgrade Go, download it from go.dev/dl.

Database​

Forge is tested with PostgreSQL 15; other versions are untested and SQLite is experimental. The support contract has the details. Install PostgreSQL:

Verify PostgreSQL is running:

psql --version

Operating System​

Forge works on:

  • Linux (any distribution)
  • macOS (10.15+)
  • Windows (with WSL recommended)

Install Forge CLI​

The Forge CLI provides commands for project creation, code generation, migrations, and more.

Global Installation​

Install the forge command globally:

go install github.com/forgego/forge/cmd/forge@latest

This installs the binary to $GOPATH/bin or $GOBIN.

Verify Installation​

Check that forge is available:

forge version

It prints the module version the binary was installed from, for example:

Forge v0.2.0

Binaries built from v0.1.1 or earlier print v0.1.0 whatever their real version; upgrade to get the correct output and the correct version pinned in new projects.

Add to PATH​

If the forge command isn't found, add Go's bin directory to your PATH.

Bash/Zsh (add to ~/.bashrc or ~/.zshrc):

export PATH="$PATH:$(go env GOPATH)/bin"

Fish (add to ~/.config/fish/config.fish):

set -gx PATH $PATH (go env GOPATH)/bin

Reload your shell:

source ~/.bashrc  # or ~/.zshrc

Install as a Library​

If you want to use Forge in an existing Go project without the CLI:

go get github.com/forgego/forge@latest

Then import packages as needed:

import (
    "github.com/forgego/forge/schema"
    "github.com/forgego/forge/orm"
    "github.com/forgego/forge/server"
)

Database Setup​

Create Database​

Create a PostgreSQL database for your project:

createdb myproject_db

Or using SQL:

CREATE DATABASE myproject_db;

Database User​

It's recommended to create a dedicated user for your application:

psql -c "CREATE USER myapp WITH PASSWORD 'secure_password';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE myproject_db TO myapp;"

Connection String​

Your connection details will go in config/config.yaml:

database:
  host: localhost
  port: 5432
  name: myproject_db
  user: myapp
  password: secure_password
  sslmode: disable

Development Tools (Optional)​

PostgreSQL GUI Tools​

Code Editor Extensions​

VS Code​

Install these extensions for the best experience:

  • Go by Go Team at Google
  • Go Test Explorer for test discovery
  • PostgreSQL for database management
  • YAML for config file syntax

GoLand​

GoLand has built-in Go support. Enable these:

  • Go modules integration
  • Database tools and SQL
  • Code completion and refactoring

Git​

Forge projects use Git for version control:

git --version

Install Git if needed: git-scm.com/downloads

Create Your First Project​

Once everything is installed, create a project:

forge new myproject
cd myproject

Configure your database in config/config.yaml, then:

forge generate
forge makemigrations init --auto
forge migrate up
forge runserver

Visit http://localhost:8000/admin/ to see the admin interface.

Upgrading Forge​

Upgrade CLI​

To upgrade to the latest version:

go install github.com/forgego/forge/cmd/forge@latest

Upgrade Library​

In your project:

go get -u github.com/forgego/forge@latest
go mod tidy

Check Version​

forge version

Troubleshooting​

Command not found: forge​

Problem: Shell can't find the forge command.

Solution: Make sure $GOPATH/bin is in your PATH:

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc
source ~/.bashrc

Cannot connect to database​

Problem: Database connection errors.

Solutions:

  1. Check PostgreSQL is running:

    pg_isready

  2. Verify connection details in config/config.yaml

  3. Test connection manually:

    psql -h localhost -U myapp -d myproject_db

  4. Check PostgreSQL logs:

    tail -f /usr/local/var/log/postgresql.log  # macOS
    sudo tail -f /var/log/postgresql/postgresql-*.log  # Linux

go.mod not found​

Problem: Go module errors.

Solution: Make sure you're in the project directory and go.mod exists:

go mod init myproject  # if starting from scratch
go mod tidy

Permission denied​

Problem: Can't create database or access files.

Solutions:

  1. For database: Grant permissions to your user
  2. For files: Check file ownership and permissions

Port 8000 already in use​

Problem: Development server can't start.

Solution: Change port in config/config.yaml or kill the process:

# Find process
lsof -ti:8000

# Kill process (macOS/Linux)
kill $(lsof -ti:8000)

Module download issues​

Problem: Can't download Forge or dependencies.

Solutions:

  1. Enable Go modules:

    export GO111MODULE=on

  2. Clear module cache:

    go clean -modcache

  3. Set Go proxy:

    export GOPROXY=https://proxy.golang.org,direct

Environment Setup​

Every configuration key can be set from the environment as FORGE_ plus the key in upper case with dots replaced by underscores. forge new writes development secrets to a local .env file, which Forge loads without overriding variables that are already set.

Development Environment​

export FORGE_APP_ENV=development
export FORGE_DATABASE_HOST=localhost
export FORGE_DATABASE_NAME=myproject_db
export FORGE_DATABASE_USER=myapp
export FORGE_DATABASE_PASSWORD=secure_password

Production Environment​

export FORGE_APP_ENV=production
export FORGE_APP_DEBUG=false
export FORGE_DATABASE_HOST=prod-host
export FORGE_DATABASE_PASSWORD=...          # from your secrets manager
export FORGE_DATABASE_SSLMODE=require
export FORGE_SECURITY_SECRET_KEY=...        # from your secrets manager
export FORGE_SECURITY_SESSION_SECRET=...
export FORGE_SECURITY_CSRF_SECRET_KEY=...

There is no DATABASE_URL setting; set the individual FORGE_DATABASE_* variables. With FORGE_APP_ENV=production the server refuses to start unless all three security secrets are set explicitly. The deployment guide covers the rest.

Docker Setup (Optional)​

You can run PostgreSQL in Docker:

docker run --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=myproject_db \
  -p 5432:5432 \
  -d postgres:15

Then use these connection details:

database:
  host: localhost
  port: 5432
  name: myproject_db
  user: postgres
  password: postgres

Next Steps​

Now that Forge is installed:

  1. Quick Start - Build your first app
  2. Models Guide - Define your data
  3. Configuration - Learn about configuration options

Getting Help​