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.modfor 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)
Behemoth is under active development, and the API may still change.
Install the package #
Add Behemoth to your module:
go get github.com/go-behemoth/behemothDatabase 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/postgresConfiguration #
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.
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:
go install github.com/go-behemoth/behemoth/cmd/behemoth@latestThen run it where your application runs:
# preview the next migration
behemoth generate
# write it to your migrations folder
behemoth generate -confirmThe 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:
| Table | Purpose |
|---|---|
users | User accounts and profiles |
accounts | Credentials and linked provider accounts |
sessions | Active user sessions (token hashes only) |
tokens | Single-use tokens |
verification_codes | One-time codes, stored as keyed hashes |
rate_limits | Rate limiter counters (empty when Redis holds them) |
audit_log | Audit events |
Environment variables #
Behemoth derives every key from a master secret that you supply. The example application reads the secret from the environment:
# Database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/behemoth?sslmode=disable
# Behemoth master secret (hex, at least 32 bytes)
BEHEMOTH_SECRET=your-hex-encoded-secretThe 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:
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.