Quick Start

This guide walks you through creating your first Forge application from scratch. By the end, you will have a running HTTP server with automatic health checks, metrics, and structured logging.

Prerequisites

Forge requires Go 1.21 or later. Check your version with go version. Make sure you have the Forge CLI installed. See the Installation guide.

Build Your First Server

Create a new Go project

mkdir my-forge-app && cd my-forge-app
go mod init my-forge-app

Install Forge

go get github.com/xraph/forge@latest

Write your application

Create main.go:

package main

import "github.com/xraph/forge"

func main() {
    // Create a new Forge application with functional options
    app := forge.New(
        forge.WithAppName("my-forge-app"),
        forge.WithAppVersion("0.1.0"),
        forge.WithHTTPAddress(":8080"),
    )

    // Register routes
    app.Router().GET("/", func(ctx forge.Context) error {
        return ctx.JSON(200, map[string]string{
            "message": "Welcome to Forge!",
        })
    })

    app.Router().GET("/users", func(ctx forge.Context) error {
        users := []map[string]string{
            {"id": "1", "name": "Alice"},
            {"id": "2", "name": "Bob"},
        }
        return ctx.JSON(200, users)
    })

    // Run blocks until shutdown signal (SIGINT/SIGTERM)
    if err := app.Run(); err != nil {
        panic(err)
    }
}

Run your application

forge dev

The Forge CLI starts a development server with hot reload enabled by default. You should see a startup banner with your application name, version, and the address it is listening on.

Verify it works

Open a new terminal and test the endpoints:

# Your custom route
curl http://localhost:8080/
# {"message":"Welcome to Forge!"}

# Users endpoint
curl http://localhost:8080/users
# [{"id":"1","name":"Alice"},{"id":"2","name":"Bob"}]

# Application info (always available)
curl http://localhost:8080/_/info

# Health check
curl http://localhost:8080/_/health

# Liveness probe (for Kubernetes)
curl http://localhost:8080/_/health/live

# Readiness probe
curl http://localhost:8080/_/health/ready

# Metrics (Prometheus format)
curl http://localhost:8080/_/metrics

What You Get Out of the Box

Without any additional configuration, your Forge application includes:

Feature	Endpoint	Description
App Info	`/_/info`	Application name, version, uptime, Go version, registered services and routes
Health Check	`/_/health`	Aggregated health status of all registered checks
Liveness Probe	`/_/health/live`	Always returns 200 if the server is running
Readiness Probe	`/_/health/ready`	Returns 200 only when all health checks pass
Metrics	`/_/metrics`	Prometheus-compatible metrics export
Structured Logging	Console	Development-friendly colored output in dev mode
Graceful Shutdown	Built-in	Handles SIGINT/SIGTERM with configurable timeout
Config Auto-Discovery	Automatic	Loads `config.yaml` and `config.local.yaml` if present

Adding Middleware

Forge supports global and route-level middleware:

// Global middleware - applies to all routes
app.Router().Use(func(next forge.Handler) forge.Handler {
    return func(ctx forge.Context) error {
        ctx.Response().Header().Set("X-Request-ID", "some-id")
        return next(ctx)
    }
})

// Route-level middleware
app.Router().GET("/admin", adminHandler,
    forge.WithMiddleware(authMiddleware),
)

Using Route Groups

Organize related routes under a shared prefix:

api := app.Router().Group("/api/v1")

api.GET("/users", listUsers)
api.POST("/users", createUser)
api.GET("/users/:id", getUser)
api.PUT("/users/:id", updateUser)
api.DELETE("/users/:id", deleteUser)

Stopping the Server

Press Ctrl+C in the terminal. Forge will:

Stop accepting new connections
Wait for in-flight requests to complete (up to 30 seconds by default)
Execute shutdown hooks in the proper order
Stop all extensions and services
Exit cleanly

Prerequisites

Build Your First Server

Create a new Go project

Install Forge

Write your application

Run your application

Verify it works

What You Get Out of the Box

Adding Middleware

Using Route Groups

Stopping the Server

Next Steps

Installation

Your First App

Architecture

Configuration

On this page