Installation

This page shows how to install Behemoth, its adapters, and its configuration in a Go project.

Prerequisites #

Before you install Behemoth, make sure that you have:

  • Go 1.26 or higher (see go.mod for the exact version)
  • A supported database: PostgreSQL, MySQL, SQLite, SQL Server, or MongoDB (Bun and GORM adapters are also available)
  • A router: net/http, Gin, Echo, chi, or Fiber (optional, since the flows can also be called from code)
Info

Behemoth is under active development, and the API may still change.

Install the package #

Add Behemoth to your module:

bash
go get github.com/go-behemoth/behemoth

Database and router adapters #

Database and framework adapters are separate modules, so you only download what you use. The net/http adapter is part of Behemoth's own module and needs no separate install:

go get github.com/go-behemoth/behemoth/storage/adapters/postgres

Configuration #

You set up Behemoth in two steps. Prepare collects the declarations of your plugins and schema. Boot connects them to a database and a router.

main.go
plugin := emailpassword.New(emailpassword.Options{})

// 1. Declarations: plugins, hooks, schema.
app, err := engine.Prepare(
    []core.Plugin{plugin},
    engine.PrepareConfig{
        Migration: migration.MigrationConfig{
            FolderPath: "migrations",
        },
    },
)
if err != nil {
    log.Fatal(err)
}

// 2. Runtime: storage, routes, sessions.
db := postgres.NewPostgresAdapter(sqlDB, app.Resolver)

ac, err := engine.Boot(
    ctx,
    app,
    db,
    engine.BootConfig{
        Crypto: cryptoCfg,
        HTTP:   ginadapter.New(router),
        Session: core.SessionConfig{
            ExpiresIn: 24 * time.Hour,
        },
        // The session token travels in a header.
        Router: httpapi.RouterConfig{
            Carrier: httpapi.TokenCarrierConfig{
                Delivery: httpapi.DeliveryHeader,
            },
        },
    },
)

Set up the database #

Behemoth builds a migration from the tables your plugins and your own schema declare, and writes it to a folder for you to review. The generate command never changes your database. Install the behemoth command:

bash
go install github.com/go-behemoth/behemoth/cmd/behemoth@latest

Then run it where your application runs:

bash
# preview the next migration
behemoth generate

# write it to your migrations folder
behemoth generate -confirm

The command reads your plugins and schema from your own code, so it needs a small setup file in your application. See Migration CLI for the setup, the files it writes, and its limits.

Behemoth generates migrations for PostgreSQL, MySQL, SQLite, and SQL Server. The command has ready-made setups for PostgreSQL and MySQL, and the other two need a small backend of your own. MongoDB has no migrations: the adapter creates the declared indexes, and Boot checks them. See Data and migrations.

Behemoth uses the following core tables:

TablePurpose
usersUser accounts and profiles
accountsCredentials and linked provider accounts
sessionsActive user sessions (token hashes only)
tokensSingle-use tokens
verification_codesOne-time codes, stored as keyed hashes
rate_limitsRate limiter counters (empty when Redis holds them)
audit_logAudit events

Environment variables #

Behemoth derives every key from a master secret that you supply. The example application reads the secret from the environment:

.env
# Database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/behemoth?sslmode=disable

# Behemoth master secret (hex, at least 32 bytes)
BEHEMOTH_SECRET=your-hex-encoded-secret
Keep your secret safe

The master secret signs and hashes session tokens, so keep it private. Generate one with openssl rand -hex 32. If the secret changes, existing sessions stop working.

Verify the installation #

To check that the installation works without a router, call the flows from code:

verify.go
user, err := plugin.SignUp(ctx, behemoth.M{
    "email":    "test@example.com",
    "password": "my-primus-stove",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("user created:", user.ID)

result, err := plugin.SignIn(
    ctx,
    emailpassword.EmailAndPasswordCredentials{
        Email:    "test@example.com",
        Password: "my-primus-stove",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Println("session created:", result.Session.ID)

Installation is complete. To build your first authentication flow, continue to the Quick Start guide.