Skip to content

Environment variables ​

Environment variables hold the things that differ between your laptop and production: secrets and addresses. How the code behaves is set in the configuration file instead.

The variables ​

VariableRequiredDefaultUsed byMeaning
NODE_ENVnodevelopmentExpress, Fastifydevelopment, test or production. production turns on strict checks
APP_ENVnodevelopmentGinThe same, for Go
PORTno3000allPort to listen on (1 – 65535)
HOSTno0.0.0.0FastifyInterface to listen on
SELFAUTH_APP_BASE_URLyes–allAddress of your frontend, used to build email links
DATABASE_URLfor a real database–allConnection string. If unset in development the in-memory store is used. Required in production
SELFAUTH_CSRF_SECRETwith csrf.mode: "token"–all32 or more random bytes, base64url
SELFAUTH_CSRF_SECRET_PREVIOUSno–allThe old secret, accepted while rotating
SELFAUTH_CONFIGnoselfauth.config.jsonGinPath to the configuration file
SELFAUTH_API_TARGETnohttp://localhost:3000Vite dev serverWhere the dev server forwards /auth and /api

If a value is invalid the server stops at startup and lists every problem:

text
Invalid environment:
  - SELFAUTH_APP_BASE_URL is required (used to build email links)

SELFAUTH_APP_BASE_URL ​

It must be an absolute http or https address with no spaces or control characters, and in production it has to be https. With a generated frontend the development value is http://localhost:5173. Verification and reset links are built from it (<url>/verify-email#token=…), and its origin is trusted for CSRF and CORS.

DATABASE_URL ​

DatabaseFormat
PostgreSQLpostgresql://user:password@host:5432/dbname
MySQLmysql://user:password@host:3306/dbname
SQLitefile:./app.db
MongoDBmongodb://host:27017/dbname

URL-encode special characters in the password: @ becomes %40, # becomes %23 and / becomes %2F.

CSRF secret ​

You only need this for cross-site setups. To generate one:

bash
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

To rotate it, set the new value as SELFAUTH_CSRF_SECRET, move the old one to SELFAUTH_CSRF_SECRET_PREVIOUS for a while, and remove it once old tokens have expired.

Where to set them ​

Development ​

ProjectHow
Express, FastifyCopy .env.example to .env (full stack: server/.env). The npm scripts load it with node --env-file-if-exists=.env
GinThe server does not read .env. Export the variables in your shell, or use a tool such as direnv
bash
# Gin, macOS / Linux
export APP_ENV=development
export SELFAUTH_APP_BASE_URL=http://localhost:5173
export DATABASE_URL=postgresql://user:password@localhost:5432/app
powershell
# Gin, Windows PowerShell
$env:SELFAUTH_APP_BASE_URL = "http://localhost:5173"

.env is ignored by git. .env.example only has placeholders and is committed. Never commit real secrets.

Production ​

Set variables in your hosting platform, whether that's container environment settings, a service dashboard or a secrets manager. A typical production set:

ini
NODE_ENV=production            # Gin: APP_ENV=production
SELFAUTH_APP_BASE_URL=https://app.example.com
DATABASE_URL=...               # required

If you use csrf.mode: "token", set SELFAUTH_CSRF_SECRET as well. See Going to production.

Add your own variable ​

Read it in the same place as the others, so a missing value stops the server at startup:

ts
const smtpHost = source["SMTP_HOST"];
if (nodeEnv === "production" && !smtpHost) problems.push("SMTP_HOST is required in production");
go
if env.Production() && get("SMTP_HOST", "") == "" {
	bad("SMTP_HOST is required in production")
}

Then add it to the Env type and to .env.example.

SelfAuth is MIT licensed. Generated code is also offered under 0BSD.