1. Create your project
Generate it
Open a terminal in the folder where you keep your projects and run:
npx selfauth@latest init notes-app --backend gin --database sqlite --frontend nonenotes-app is the name of the new folder. It's also the Go module name, so your imports will read notes-app/internal/.... To use a module path like github.com/you/notes-app, add --module github.com/you/notes-app.
SelfAuth shows you the list of files it's about to create and writes them. If you leave out the options, npx selfauth@latest init notes-app asks you the same questions one at a time.
Using PostgreSQL, MySQL or MongoDB instead?
Change --database:
npx selfauth@latest init notes-app --backend gin --database postgresql --frontend noneThe values are postgresql, mysql, sqlite, mongodb and memory. You'll need an empty database ready, and in the next step you'll put its address in .env.
Want React or Vue pages too?
Use --frontend react or --frontend vue. Your project then has two folders: server/ holds the Go code and client/ holds the pages. Every Go file this guide mentions is inside server/, so internal/routes/routes.go becomes server/internal/routes/routes.go. Run go commands inside server/. Chapter 9 explains the rest.
Your settings
cd notes-appCreate your settings file by copying the example:
cp .env.example .envCopy-Item .env.example .env.env holds settings that differ between your computer and production: the port, your frontend's address, and the database address. For SQLite it already points at a file called app.db.
The DATABASE_URL for other databases
Open .env and set DATABASE_URL to your database:
# PostgreSQL
DATABASE_URL=postgresql://postgres:secret@localhost:5432/notes
# MySQL
DATABASE_URL=mysql://root:secret@localhost:3306/notes
# MongoDB
DATABASE_URL=mongodb://localhost:27017/notesLoad them into your terminal
Here's one difference from the Node backends: the Go server reads settings from the environment, and doesn't open .env by itself. So load the file into your terminal:
set -a; source .env; set +aGet-Content .env | Where-Object { $_ -match '^[A-Z_]+=' } | ForEach-Object { $k, $v = $_ -split '=', 2; Set-Item "env:$k" $v }You need to do this once in every new terminal window. If a command later says DATABASE_URL is required, this is the step you missed.
Create the database
Create the tables SelfAuth needs. First look at what will happen:
npx selfauth db planPending migrations (1):
• 20261116085533_selfauth_init (db/migrations/20261116085533_selfauth_init/migration.sql)
✓ Nothing here loses data or touches SelfAuth's tables.A migration is a file of SQL that changes the database. This one creates SelfAuth's tables: users, sessions, roles and so on. plan reads it and tells you whether it would lose any data. It wouldn't, so apply it:
npx selfauth db migrateApplied: [20261116085533_selfauth_init]
✓ Migrations applied.Then write the roles from your configuration into the database:
go run ./cmd/seedSynchronized roles: [admin user]The first go run downloads the project's dependencies, so it takes a minute. After that it's quick.
MongoDB
MongoDB has no SQL migrations. npx selfauth db migrate creates the indexes SelfAuth needs instead (the one that keeps emails unique, for example). The commands are the same.
Check it worked
npx selfauth validateThe last line should be All checks passed. You now have a working Go API with sign-up and sign-in. Next you'll start it and try it.
If something went wrong
DATABASE_URL is requiredorDATABASE_URL is not set. Load.envinto your terminal (above), in this terminal window.go: command not found. Go isn't installed, or isn't on yourPATH. Open a new terminal after installing it.Can't reach database serverorconnection refused(PostgreSQL, MySQL, MongoDB). The database isn't running, or the address, user or password inDATABASE_URLis wrong.
Next: Run it and sign in