Installation

Requirements

Install the Forge CLI

The Forge CLI (forge) is the primary tool for developing, building, and managing Forge applications. It provides hot-reload development servers, code generation, database migrations, and more.

brew install xraph/tap/forge

brew upgrade xraph/tap/forge

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

scoop bucket add xraph https://github.com/xraph/scoop-bucket
scoop install forge

scoop update forge

tar -xzf forge-*.tar.gz

sudo mv forge /usr/local/bin/

forge version

# Debian / Ubuntu
sudo dpkg -i forge_*.deb

# Fedora / RHEL
sudo rpm -i forge_*.rpm

# Alpine
sudo apk add --allow-untrusted forge_*.apk

docker pull ghcr.io/xraph/forge:latest

docker run --rm ghcr.io/xraph/forge:latest version

Verify the CLI

After installation, confirm the CLI is available:

forge version

You should see version, commit, and build information printed to the terminal.

Add Forge to Your Project

Once the CLI is installed, set up Forge as a Go dependency in your project.

mkdir my-project && cd my-project
go mod init github.com/yourorg/my-project

go get github.com/xraph/forge@latest

# Examples of optional extensions
go get github.com/xraph/forge/extensions/database@latest
go get github.com/xraph/forge/extensions/kafka@latest
go get github.com/xraph/forge/extensions/grpc@latest

package main

import (
    "fmt"
    "github.com/xraph/forge"
)

func main() {
    app := forge.New(
        forge.WithAppName("install-check"),
    )
    fmt.Printf("Forge app created: %s\n", app.Name())
}

forge dev

Version Compatibility

Forge follows semantic versioning. The module path is github.com/xraph/forge.

When upgrading, always run:

go get github.com/xraph/forge@latest
go mod tidy

IDE Setup

VS Code

Install the official Go extension for full IntelliSense, debugging, and test support. Add these settings for the best experience:

{
  "go.useLanguageServer": true,
  "gopls": {
    "ui.semanticTokens": true,
    "ui.completion.usePlaceholders": true
  }
}

GoLand / IntelliJ

GoLand provides full support out of the box. Ensure the Go plugin is up to date and that the project SDK points to Go 1.21+.

Neovim

Use gopls as the language server with your preferred LSP client (nvim-lspconfig, coc.nvim, or similar).

Recommended Project Structure

Forge does not enforce a specific project layout, but the following structure works well for most applications:

my-project/
├── main.go                 # Application entry point
├── config.yaml             # Base configuration
├── config.local.yaml       # Local overrides (git-ignored)
├── .forge.yaml             # Forge CLI configuration (optional)
├── go.mod
├── go.sum
├── internal/
│   ├── handlers/           # HTTP handler functions
│   │   └── users.go
│   ├── services/           # Business logic
│   │   └── user_service.go
│   ├── models/             # Data models
│   │   └── user.go
│   └── middleware/          # Custom middleware
│       └── auth.go
└── extensions/             # Custom extensions (if any)
    └── notifications/
        └── extension.go

Key conventions:

• main.go creates the app, registers services and routes, and calls app.Run().
• config.yaml is auto-discovered by Forge and loaded into the configuration manager.
• config.local.yaml provides developer-specific overrides and should be added to .gitignore.
• internal/ keeps packages private to your module, following standard Go conventions.

Configuration Files

Forge auto-discovers configuration files on startup. Place a config.yaml in your project root:

# config.yaml
server:
  port: 8080
  timeout: 30s

database:
  host: localhost
  port: 5432
  name: myapp

logging:
  level: info

Create config.local.yaml for personal overrides (add this to .gitignore):

# config.local.yaml - developer-specific overrides
database:
  host: 127.0.0.1
  password: localdev

logging:
  level: debug

See the Configuration guide for full details on auto-discovery, environment variables, and config binding.

Next Steps