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)
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-* headers from reverse proxy (enable when behind nginx, Traefik, etc.)
GOIABADA_AUTHSERVER_SET_COOKIE_SECURE —authserver-set-cookie-secure	false	Set Secure flag on cookies (enable for HTTPS in production)
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_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)	10 req/min	email
POST /auth/otp (OTP verification)	10 req/min	user ID
GET /reset-password	5 req/5min	email
GET /account/activate	5 req/5min	email
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

Logging

Variable / Flag	Default	Description
GOIABADA_AUTHSERVER_LOG_HTTP_REQUESTS —authserver-log-http-requests	false	Log HTTP requests
GOIABADA_AUTHSERVER_LOG_SQL —authserver-log-sql	false	Log SQL statements
GOIABADA_AUTHSERVER_AUDIT_LOGS_IN_CONSOLE —authserver-audit-logs-in-console	true	Log audit events
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
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-* headers from reverse proxy (enable when behind nginx, Traefik, etc.)
GOIABADA_ADMINCONSOLE_SET_COOKIE_SECURE —adminconsole-set-cookie-secure	false	Set Secure flag on cookies (enable for HTTPS in production)
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

Logging

Variable / Flag	Default	Description
GOIABADA_ADMINCONSOLE_LOG_HTTP_REQUESTS —adminconsole-log-http-requests	false	Log HTTP requests

---

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.

---

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