Installation

There are two ways to configure GoBetterAuth in your project: as a standalone server or as a library integrated into your existing API server.

The following sections will guide you through both methods.

Standalone Mode

Setup configuration file

Make a copy of the config.example.toml file provided in the repository.
Rename the copied file to config.toml.
Populate the configuration fields with your desired settings. Most of these settings allow you to configure the server according to your needs.
It is recommended that you do not set secret values within the config.toml file directly. Instead, use environment variables to manage sensitive information securely.

config.toml

app_name = "GoBetterAuth"
base_url = "http://localhost:8080"
base_path = "/auth"

[database]
provider = "postgres"

# ... other settings

Set environment variables via .env file

Make a copy of the .env.example file provided in the repository.
Rename the copied file to .env.
Populate the environment variables with your desired values. These values will override any corresponding values set in the config.toml file.

.env

# Path to your configuration file (e.g., ./config.toml) (optional)
GO_BETTER_AUTH_CONFIG_PATH=

# Gives admin access to update and manage the GoBetterAuth server
# Generate using `echo gba_sk_$(openssl rand -base64 50 | tr -dc 'A-Za-z0-9' | cut -c -35)`
GO_BETTER_AUTH_ADMIN_API_KEY=

# The base URL of your API
GO_BETTER_AUTH_BASE_URL=

# Used for encryption. Generate using `openssl rand -base64 50 | tr -dc 'A-Za-z0-9' | cut -c -40`
GO_BETTER_AUTH_SECRET=

# sqlite/postgres/mysql connection string
GO_BETTER_AUTH_DATABASE_URL=

Run the server via Docker

$ docker run -itd \ 
  -p 8080:8080 \
  -v $(pwd)/config.toml:/home/appuser/config.toml \
  -e GO_BETTER_AUTH_ADMIN_API_KEY=my-admin-api-key \
  -e GO_BETTER_AUTH_BASE_URL=http://localhost:8080 \
  -e GO_BETTER_AUTH_SECRET=my-app-secret \
  -e GO_BETTER_AUTH_DATABASE_URL=<your_connection_string> \
  ghcr.io/gobetterauth/go-better-auth:latest

Library Mode

Set environment variables

Create a .env file in the root of your project and add the following environment variables:

.env

# The base URL of your API
GO_BETTER_AUTH_BASE_URL=

# Used for encryption. Generate using `openssl rand -base64 50 | tr -dc 'A-Za-z0-9' | cut -c -40`
GO_BETTER_AUTH_SECRET=

# sqlite/postgres/mysql connection string
GO_BETTER_AUTH_DATABASE_URL=

Install the Package

$ go get "github.com/GoBetterAuth/go-better-auth"

Create auth config

import (
  gobetterauthconfig "github.com/GoBetterAuth/go-better-auth/config"
  gobetterauthmodels "github.com/GoBetterAuth/go-better-auth/models"
)

config := gobetterauthconfig.NewConfig(/*...*/)
auth := gobetterauth.New(config)

Configure database

GoBetterAuth supports multiple database providers. You can select a database provider by supplying it in the config.

gobetterauthconfig.NewConfig(
  gobetterauthconfig.WithDatabase(gobetterauthmodels.DatabaseConfig{
    Provider:   "sqlite",
  }),
)

GoBetterAuth already runs core migrations automatically when you create a new instance so all the important database tables are created for you automatically without any additional steps. But GoBetterAuth also provides migration files which you can run directly against your database of choice. Or you can run the migrations programmatically by running the RunMigrations() function. An example is shown below:

// Create the config
config := gobetterauthconfig.NewConfig(/*...*/)
auth := gobetterauth.New(config)

Authentication Methods

Configure the authentication methods you want to use in your config struct. GoBetterAuth supports the basic Email/Password authentication method and will soon support social sign-on providers such as Google, GitHub, Discord and more.

config := gobetterauthconfig.NewConfig(
  gobetterauthconfig.WithEmailPassword(gobetterauthmodels.EmailPasswordConfig{
    Enabled:                  true,
    RequireEmailVerification: true,
    AutoSignIn:               true,
  }),
)

Mount Handlers

To handle API requests, you need to integrate the GoBetterAuth handlers in your API.

This is an example of how it can be done with the standard library server:

// Initialise auth
config := gobetterauthconfig.NewConfig(/*...*/)
auth := gobetterauth.New(config)

// Mount auth routes
http.Handle("/auth/", auth.Handler())

// Start the server
log.Println("Server running on http://localhost:8080")
log.Fatal(http.ListenAndServe(":8080", nil))

Take a look at the Examples section to see how to integrate it with other frameworks.