Installation

This guide will help you install Forge and set up your development environment.

Prerequisites

Before installing Forge, ensure you have the following:

Go 1.21+: Forge requires Go 1.21 or later
Git: For cloning repositories and version control
Make: For running build commands (optional but recommended)

You can check your Go version with go version. If you need to install or update Go, visit golang.org.

Installation Methods

Using Go Modules

The recommended way to use Forge is through Go modules:

# Create a new project
mkdir my-forge-app
cd my-forge-app
go mod init my-forge-app

# Add Forge dependency
go get github.com/xraph/forge

This will add Forge to your go.mod file and download the package.

Forge follows semantic versioning. Use go get github.com/xraph/forge@latest to get the latest stable version.

Using the CLI Tool

Forge provides a powerful CLI tool for project management:

# Install the CLI tool
go install github.com/xraph/forge/cmd/forge@latest

# Verify installation
forge version

# Create a new project
forge init my-project
cd my-project

# Start development server
forge dev

The CLI tool provides commands for:

Project initialization
Code generation
Development server
Database management
Extension management
Deployment

See the CLI documentation for a complete list of commands.

Building from Source

To build Forge from source:

# Clone the repository
git clone https://github.com/xraph/forge.git
cd forge

# Build the CLI tool
make build

# Install CLI tool
make install

# Run tests
make test

Building from source is only recommended for contributors or when you need the latest unreleased features.

Verify Installation

After installation, verify everything is working:

# Check Go version
go version

# Check Forge CLI (if installed)
forge version

# Create a test project
mkdir test-forge-app
cd test-forge-app
go mod init test-forge-app
go get github.com/xraph/forge

# Create a simple main.go
cat > main.go << 'EOF'
package main

import "github.com/xraph/forge"

func main() {
    app := forge.NewApp(forge.AppConfig{
        Name: "test-app",
    })
    
    app.Router().GET("/", func(ctx forge.Context) error {
        return ctx.JSON(200, map[string]string{"message": "Hello, Forge!"})
    })
    
    app.Run()
}
EOF

# Run the application
go run main.go

If everything is working correctly, you should see output indicating the server is running on http://localhost:8080.

Development Environment

Recommended IDE Setup

VS Code:

Install the Go extension
Install the Forge extension (if available)
Configure Go settings for optimal development

GoLand/IntelliJ:

Built-in Go support
Excellent debugging capabilities
Integrated terminal and version control

Environment Variables

Forge respects standard Go environment variables:

# Go workspace
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

# Go proxy (optional, for faster downloads)
export GOPROXY=https://proxy.golang.org,direct

# Go private modules (if using private repositories)
export GOPRIVATE=github.com/your-org/*

Project Structure

A typical Forge project structure:

my-forge-app/
├── main.go              # Application entry point
├── go.mod               # Go module file
├── go.sum               # Go module checksums
├── .forge.yaml          # Forge configuration (optional)
├── config/              # Configuration files
│   ├── development.yaml
│   ├── production.yaml
│   └── testing.yaml
├── internal/             # Private application code
│   ├── handlers/         # HTTP handlers
│   ├── services/         # Business logic
│   ├── models/           # Data models
│   └── middleware/       # Custom middleware
├── pkg/                  # Public packages
├── extensions/           # Custom extensions
├── migrations/           # Database migrations
└── tests/               # Test files

Next Steps

Now that you have Forge installed:

Quick Start Guide - Build your first application
Configuration - Learn about configuration management
CLI Reference - Explore the command-line tools
Architecture - Understand Forge's design principles

Troubleshooting

Common Issues

Go version too old:

# Update Go to 1.21+
# Visit https://golang.org/dl/ for downloads

Module proxy issues:

# Use direct mode
export GOPROXY=direct
go get github.com/xraph/forge

Permission errors:

# Fix Go module permissions
sudo chown -R $(whoami) $GOPATH

Build failures:

# Clean module cache
go clean -modcache
go mod download

Getting Help

If you encounter issues:

Check the GitHub Issues
Review the documentation
Join our community discussions
Create a new issue with detailed information

When reporting issues, please include your Go version, operating system, and a minimal reproduction case.

Installation

On this page