Environment variables

Goiabada consists of two applications, each with its own configuration:

• Auth server (goiabada-authserver) - Handles authentication, OAuth2/OIDC endpoints, and database access
• Admin console (goiabada-adminconsole) - Provides the administrative interface

Configuration can be set via environment variables or command-line flags. When both are set, flags take precedence.

Auth server variables

Initial setup

Used only on first startup:

Variable / Flag	Default	Description
GOIABADA_ADMIN_EMAIL –admin-email	[email protected]	Email for initial admin user
GOIABADA_ADMIN_PASSWORD –admin-password	changeme	Password for initial admin user
GOIABADA_APPNAME –appname	Goiabada	Application name in UI

Database configuration

Variable / Flag	Default	Description
GOIABADA_DB_TYPE –db-type	sqlite	mysql, postgres, mssql, or sqlite
GOIABADA_DB_USERNAME –db-username	root	Database username
GOIABADA_DB_PASSWORD –db-password	(empty)	Database password
GOIABADA_DB_HOST –db-host	localhost	Database hostname
GOIABADA_DB_PORT –db-port	3306	Database port
GOIABADA_DB_NAME –db-name	goiabada	Database name
GOIABADA_DB_DSN –db-dsn	file::memory:	SQLite DSN (only for sqlite)

Tip

For SQLite with a file, use: file:/path/to/goiabada.db?_pragma=busy_timeout=5000&_pragma=journal_mode=WAL

• busy_timeout=5000: Waits up to 5 seconds when the database is locked by another connection, instead of failing immediately. Essential for handling concurrent requests.
• journal_mode=WAL: Enables Write-Ahead Logging, which allows concurrent reads while writing and improves performance. Without WAL, readers block writers and vice versa.

Network configuration

The base URL is the public URL users see in their browser. The internal base URL is used by the admin console for server-to-server API calls. In containerized environments, internal URLs bypass external DNS/proxies for faster, more reliable communication (e.g., http://goiabada-authserver:9090 instead of https://auth.example.com).

These variables are read by both applications: the auth server uses them for JWT issuer and seeding, while the admin console uses them to connect to the auth server.

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_BASEURL –authserver-baseurl	http://localhost:9090	Public URL (used for JWT issuer, browser redirects). An https:// value also enables the Secure flag on cookies automatically (there is no separate cookie-secure setting).
GOIABADA_AUTHSERVER_INTERNALBASEURL –authserver-internalbaseurl	(empty)	Internal URL used by admin console for API calls (if empty, uses base URL)
GOIABADA_AUTHSERVER_LISTEN_HOST_HTTP –authserver-listen-host-http	0.0.0.0	HTTP bind address (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
GOIABADA_AUTHSERVER_LISTEN_PORT_HTTP –authserver-listen-port-http	9090	HTTP port
GOIABADA_AUTHSERVER_LISTEN_HOST_HTTPS –authserver-listen-host-https	0.0.0.0	HTTPS bind address (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
GOIABADA_AUTHSERVER_LISTEN_PORT_HTTPS –authserver-listen-port-https	9443	HTTPS port

Security settings

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_CERTFILE –authserver-certfile	(empty)	TLS certificate path (only needed for direct HTTPS without a reverse proxy)
GOIABADA_AUTHSERVER_KEYFILE –authserver-keyfile	(empty)	TLS private key path (only needed for direct HTTPS without a reverse proxy)
GOIABADA_AUTHSERVER_TRUST_PROXY_HEADERS –authserver-trust-proxy-headers	false	Trust X-Forwarded-For / X-Real-IP from a reverse proxy when resolving the client IP (used for rate limiting and audit logging). Leave false when there is no proxy. See also TRUSTED_PROXIES.
GOIABADA_AUTHSERVER_TRUSTED_PROXIES –authserver-trusted-proxies	(empty)	Comma-separated reverse-proxy IPs/CIDRs, e.g. 10.0.0.0/8,192.168.1.5. When set (with TRUST_PROXY_HEADERS=true), the real client IP is resolved by walking X-Forwarded-For from the right across these trusted hops, which prevents IP spoofing behind multiple proxies or a CDN. When empty, a single proxy hop is trusted.
GOIABADA_AUTHSERVER_SESSION_AUTHENTICATION_KEY	(empty)	64-byte hex HMAC key (see Session keys)
GOIABADA_AUTHSERVER_SESSION_ENCRYPTION_KEY	(empty)	32-byte hex AES key (see Session keys)
GOIABADA_AES_ENCRYPTION_KEY	(empty)	Required. 32-byte hex key that encrypts secrets at rest in the database (see Data-at-rest encryption key). Auth server only; not needed by the admin console.
GOIABADA_AES_ENCRYPTION_KEY_PREVIOUS	(empty)	Optional. Set to the old 32-byte hex key only while rotating GOIABADA_AES_ENCRYPTION_KEY; the auth server re-encrypts data from it to the current key at startup. Remove after rotation. Auth server only.
GOIABADA_AUTHSERVER_RATELIMITER_ENABLED –authserver-ratelimiter-enabled	false	Enable built-in rate limiting (see details below)

Rate limiting details

When enabled, Goiabada applies rate limits to security-sensitive endpoints:

Endpoint	Limit	Key
POST /auth/pwd (password login)	15 req/min	email
POST /auth/pwd (password login)	30 req/min	IP address
POST /auth/otp (OTP verification)	10 req/min	user ID
POST /forgot-password	5 req/5min	email
POST /forgot-password	20 req/5min	IP address
GET and POST /reset-password	30 req/5min	IP address
GET /account/activate	20 req/5min	IP address
POST /connect/register (DCR)	10 req/min	IP address
POST /auth/token (ROPC grant)	5 req/min	client_id + username + IP

You can also implement rate limiting at the infrastructure level (reverse proxy, CDN, cloud WAF) for more flexibility.

Customization

See Customizations for details on how to customize templates and static files.

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_STATICDIR –authserver-staticdir	(empty)	Custom static files directory
GOIABADA_AUTHSERVER_TEMPLATEDIR –authserver-templatedir	(empty)	Custom templates directory
GOIABADA_I18N_OVERRIDES_DIR	(empty)	Directory of override message catalogs. Set on both servers. See Localization.

Logging

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_LOG_HTTP_REQUESTS –authserver-log-http-requests	false	Log HTTP requests, one record per request on the application log (stderr), apart from health checks, static assets and the favicon. Query parameter values are redacted apart from a short assessed-safe list, and the query is re-encoded rather than copied. See Security.
GOIABADA_AUTHSERVER_LOG_SQL –authserver-log-sql	false	Log SQL statements
GOIABADA_AUTHSERVER_DEBUG_API_REQUESTS –authserver-debug-api-requests	false	Verbose API logging

Bootstrap

There are two ways to bootstrap Goiabada:

Recommended: Single-step bootstrap using GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET. Pre-generate credentials (e.g., using goiabada-setup) and provide them to both services. The auth server seeds the database and continues running normally.

Legacy: Two-step bootstrap using GOIABADA_AUTHSERVER_BOOTSTRAP_ENV_OUTFILE. The auth server generates credentials, writes them to a file, and exits. You then copy the credentials to your configuration and restart. This approach requires manual intervention between steps.

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET –adminconsole-oauth-client-secret	(empty)	Recommended. Pre-generated OAuth secret for single-step bootstrap (see note below)
GOIABADA_AUTHSERVER_BOOTSTRAP_ENV_OUTFILE –authserver-bootstrap-env-outfile	(empty)	Legacy two-step bootstrap: path where auth server writes generated credentials before exiting

Understanding GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET

This variable serves different purposes depending on which application reads it:

On auth server (seeding only): When the auth server starts for the first time and seeds the database, it creates an OAuth client for the admin console. If this variable is set, the auth server uses its value as the client secret. After the initial database seed, this variable is no longer needed by the auth server and can be removed from its configuration.

On admin console (runtime): The admin console uses this secret to authenticate with the auth server via OAuth2. It needs this credential to obtain access tokens and make API calls to manage users, clients, and other resources. This variable must remain configured for the admin console to function.

Both applications must have the same value during initial setup. The setup wizard automatically generates a matching secret for both.

---

Admin console variables

Network configuration

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_BASEURL –adminconsole-baseurl	http://localhost:9091	Public URL. An https:// value also enables the Secure flag on cookies automatically (there is no separate cookie-secure setting).
GOIABADA_ADMINCONSOLE_LISTEN_HOST_HTTP –adminconsole-listen-host-http	0.0.0.0	HTTP bind address (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
GOIABADA_ADMINCONSOLE_LISTEN_PORT_HTTP –adminconsole-listen-port-http	9091	HTTP port
GOIABADA_ADMINCONSOLE_LISTEN_HOST_HTTPS –adminconsole-listen-host-https	0.0.0.0	HTTPS bind address (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
GOIABADA_ADMINCONSOLE_LISTEN_PORT_HTTPS –adminconsole-listen-port-https	9444	HTTPS port

OAuth settings

The admin console authenticates with the auth server using OAuth2 to access its APIs.

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_ID –adminconsole-oauth-client-id	admin-console-client	OAuth client ID
GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET –adminconsole-oauth-client-secret	(empty)	Required. OAuth client secret (must match auth server config, see Bootstrap)
GOIABADA_ADMINCONSOLE_ISSUER –adminconsole-issuer	(auth server URL)	Expected JWT issuer

Auth server connection

The admin console needs to know where the auth server is located. See Network configuration for details on these variables - they are shared between both applications.

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_BASEURL –authserver-baseurl	http://localhost:9090	Public URL (used for browser redirects, JWT issuer validation)
GOIABADA_AUTHSERVER_INTERNALBASEURL –authserver-internalbaseurl	(empty)	Internal URL for API calls (if empty, uses base URL)

Security settings

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_CERTFILE –adminconsole-certfile	(empty)	TLS certificate path (only needed for direct HTTPS without a reverse proxy)
GOIABADA_ADMINCONSOLE_KEYFILE –adminconsole-keyfile	(empty)	TLS private key path (only needed for direct HTTPS without a reverse proxy)
GOIABADA_ADMINCONSOLE_TRUST_PROXY_HEADERS –adminconsole-trust-proxy-headers	false	Trust X-Forwarded-For / X-Real-IP from a reverse proxy when resolving the client IP (used for audit logging). Leave false when there is no proxy. See also TRUSTED_PROXIES.
GOIABADA_ADMINCONSOLE_TRUSTED_PROXIES –adminconsole-trusted-proxies	(empty)	Comma-separated reverse-proxy IPs/CIDRs, e.g. 10.0.0.0/8,192.168.1.5. When set (with TRUST_PROXY_HEADERS=true), the real client IP is resolved by walking X-Forwarded-For from the right across these trusted hops, which prevents IP spoofing behind multiple proxies or a CDN. When empty, a single proxy hop is trusted.
GOIABADA_ADMINCONSOLE_SESSION_AUTHENTICATION_KEY	(empty)	64-byte hex HMAC key (see Session keys)
GOIABADA_ADMINCONSOLE_SESSION_ENCRYPTION_KEY	(empty)	32-byte hex AES key (see Session keys)

Customization

See Customizations for details on how to customize templates and static files.

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_STATICDIR –adminconsole-staticdir	(empty)	Custom static files
GOIABADA_ADMINCONSOLE_TEMPLATEDIR –adminconsole-templatedir	(empty)	Custom templates
GOIABADA_I18N_OVERRIDES_DIR	(empty)	Directory of override message catalogs. Set on both servers. See Localization.

Logging

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_LOG_HTTP_REQUESTS –adminconsole-log-http-requests	false	Log HTTP requests, one record per request on the application log (stderr), apart from health checks, static assets and the favicon. Query parameter values are redacted apart from a short assessed-safe list, and the query is re-encoded rather than copied. See Security.

---

Session keys

Both applications require session keys for cookie security in production.

Generate keys

# Authentication key (64 bytes = 128 hex characters)
openssl rand -hex 64

# Encryption key (32 bytes = 64 hex characters)
openssl rand -hex 32

Key purposes

• Authentication key (64 bytes): HMAC signatures to verify cookie integrity
• Encryption key (32 bytes): AES encryption of cookie data

Caution

Never use plain text passwords or example keys. Always generate fresh cryptographic keys for each deployment.

---

Data-at-rest encryption key

The auth server requires GOIABADA_AES_ENCRYPTION_KEY. It is a hex-encoded 32-byte key used to encrypt sensitive values before they are written to the database. The admin console does not use it (it has no direct database access and delegates to the auth server API), so set it on the auth server only.

Generate the key

# 32 bytes = 64 hex characters
openssl rand -hex 32

What it protects

The key encrypts secrets at rest, including:

• Client secrets
• SMTP and SMS provider credentials
• Email and phone verification codes
• OTP (2FA) seeds
• RSA signing keys used to sign tokens

Back up this key separately from the database

Store GOIABADA_AES_ENCRYPTION_KEY in a secure location that is separate from your database backups. If this key is lost, every encrypted secret and signing key becomes permanently unrecoverable. There is no way to decrypt the data without it.

Rotating the key

Upgrading an existing installation. The first time the auth server runs with GOIABADA_AES_ENCRYPTION_KEY set, if it finds secrets still encrypted with the key that was previously stored in the database, it automatically re-encrypts every stored secret and signing key to the env key and clears the old one. This runs in a single transaction at startup and retries safely if interrupted; no extra configuration is needed.

Rotating to a new key. To change the key later, set GOIABADA_AES_ENCRYPTION_KEY to the new key and GOIABADA_AES_ENCRYPTION_KEY_PREVIOUS to the old key, then restart the auth server. At startup it detects that the data is still encrypted under the previous key and re-encrypts everything to the new key (a single transaction). The operation is idempotent, so it is safe to leave GOIABADA_AES_ENCRYPTION_KEY_PREVIOUS set across restarts, but you should remove it once the rotation is confirmed. If the data decrypts under neither key, the auth server refuses to start rather than risk corrupting it.

---

Architecture note (v1.2+)

Since version 1.2, only the auth server accesses the database directly. The admin console communicates with the auth server via HTTP APIs using OAuth2 authentication.

This means:

• Database variables (GOIABADA_DB_*) are only used by the auth server
• The admin console requires OAuth credentials to authenticate with the auth server
• The admin console does not need database configuration