Configuration

All configuration is done via environment variables.

Core

Variable	Required	Default	Description
BASE_URL	✅	—	Public URL of the Taco instance (e.g. https://taco.example.com)
BETTER_AUTH_SECRET	✅	—	32-byte random secret for session signing. Generate with npm run auth:secret
PLAN_TIER	—	lite	lite, team, or business. Baked into the Docker image at build time

Caution

PLAN_TIER must match the Docker image you are using. The plan is baked into the image at build time.

Database

Variable	Required	Default	Description
DATABASE_URL	✅	—	PostgreSQL connection string (e.g. pgsql://user:pass@host:5432/taco)
DATABASE_DIALECT	—	postgresql	Database dialect. Only postgresql is supported
DATABASE_CLIENT	—	postgresql	Database client. Only postgresql is supported

Email

Variable	Required	Default	Description
EMAIL_FROM	✅	—	Sender address (e.g. Taco <noreply@example.com>)
EMAIL_SERVER	✅	—	SMTP connection string (e.g. smtps://user:pass@smtp.example.com)

OIDC / SSO login (optional)

Protect the Taco dashboard itself behind an upstream OIDC provider.

Variable	Required	Default	Description
AUTH_CLIENT_OPENID_CONFIGURATION_URL	—	—	Discovery URL of the upstream OIDC issuer
AUTH_CLIENT_ID	—	—	OIDC client ID for Taco’s own login
AUTH_CLIENT_SECRET	—	—	OIDC client secret
AUTH_CLIENT_SCOPE	—	openid profile email	Requested scopes

Provider selection

Variable	Required	Default	Description
OPENID_PROVIDER	✅	—	Provisioning backend: ory, auth0, entra, or rfc7592

Provider management API authentication

Generic credentials Taco uses to call the selected provider’s management API. Not needed for Auth0 or Entra ID, which use their own provider-specific variables (see below).

Variable	Required	Default	Description
OPENID_PROVIDER_AUTH_TYPE	—	—	none or client_credentials
OPENID_PROVIDER_AUTH_ISSUER	when client_credentials	—	Token endpoint issuer used to fetch admin access tokens
OPENID_PROVIDER_AUTH_CLIENT_ID	when client_credentials	—	Admin client ID
OPENID_PROVIDER_AUTH_CLIENT_SECRET	when client_credentials	—	Admin client secret
OPENID_PROVIDER_AUTH_TOKEN_METHOD	—	client_secret_post	client_secret_post or client_secret_basic
OPENID_PROVIDER_AUTH_SCOPE	—	—	Scope requested for the admin access token
OPENID_PROVIDER_AUTH_AUDIENCE	—	—	Audience requested for the admin access token

Ory Hydra

Variable	Required	Default	Description
ORY_BASE_URL	✅	—	Base URL of the Hydra Admin API (e.g. http://localhost:4445)

Auth0

Variable	Required	Default	Description
AUTH0_DOMAIN	✅	—	Your Auth0 tenant domain (e.g. your-tenant.auth0.com)

Uses OPENID_PROVIDER_AUTH_CLIENT_ID / OPENID_PROVIDER_AUTH_CLIENT_SECRET above as the Management API M2M application credentials.

Azure Entra ID

Variable	Required	Default	Description
ENTRA_TENANT_ID	✅	—	Directory (tenant) ID
ENTRA_CLIENT_ID	✅	—	Application (client) ID of the app registration Taco uses to call Microsoft Graph
ENTRA_CLIENT_SECRET	✅	—	Client secret for that app registration
ENTRA_SIGN_IN_AUDIENCE	—	AzureADMyOrg	AzureADMyOrg, AzureADMultipleOrgs, or AzureADandPersonalMicrosoftAccount

RFC 7592

Variable	Required	Default	Description
RFC7592_BASE_URL	✅	—	Base URL of the authorization server. Taco uses {RFC7592_BASE_URL}/register as the registration endpoint

Statistics aggregation (Team / Business tiers)

Variable	Required	Default	Description
STATS_CRON_SECRET	✅	—	Bearer token required by POST /api/cron/aggregation
STATS_AGGREGATION_INTERVAL_MINUTES	—	1440	Business tier only — aggregation interval in minutes
STATS_WEBHOOK_SECRET	—	—	Optional — validates incoming webhook payloads to /api/events/ingest

Tip

Running locally? Use docker-compose.dev.yml combined with a provider compose file (docker-compose.hydra.yml or docker-compose.rfc7592.yml) to get a working provider without external accounts.