Environment Variables

Environment variables provides global configuration

Main Server Environment Variables

Main server environment variable provides global configuration for main server.

MAIN_LISTEN_ADDR

This sets the listen address of the main server. The default is 0.0.0.0:3000.

RESOLVER_LISTEN_ADDR

This sets the listen address of the resolver server. The default is 0.0.0.0:3001.

ADMIN_LISTEN_ADDR

This sets the listen address of the Admin API server. The default is 0.0.0.0:3002.

TLS_CERT_FILE_PATH

This sets the file path of TLS certificate. It is only used when development mode is enabled. The default is tls-cert.pem.

TLS_KEY_FILE_PATH

This sets the file path of TLS private key. It is only used when development mode is enabled. The default is tls-key.pem.

ADMIN_API_AUTH

This sets the authorization mode of the Admin API. Valid values are jwt and none. The default is jwt.

When the value is jwt, all requests to the Admin API must bear a valid JWT.

When the value is none, no authorization is needed. You must NOT use none in production unless you know the implied consequences.

CONFIG_SOURCE_TYPE

This sets the type of the configuration. Valid values are local_fs and kubernetes. The default is local_fs.

CONFIG_SOURCE_KUBECONFIG

This indicates the path to the .kubeconfig config file. It is only used when configuration type is kubernetes.

CONFIG_SOURCE_KUBE_NAMESPACE

This indicates the namespace where Kubernetes resources of all apps reside. It is only used when configuration type is kubernetes.

CONFIG_SOURCE_WATCH

This indicates whether the configuration source would watch for changes and reload automatically. The default is true.

CONFIG_SOURCE_DIRECTORY

This sets the path to app configuration directory file for local FS sources. The default is ..

BUILTIN_RESOURCE_DIRECTORY

This sets the directory for built-in resource files. The default is resources/authgear.

CUSTOM_RESOURCE_DIRECTORY

This sets the directory for customized resource files.

STATIC_ASSET_SERVING_ENABLED

This sets whether the bundled static asset should be served. Default is true. You should never modify it.

STATIC_ASSET_DIR

This sets the filepath of the directory containing the bundled static asset. The default value of the provided Docker image does the right thing so you should never need to set it.

Portal Environment Variable

Portal environment variable provides global configuration for Authegar portal.

PORTAL_LISTEN_ADDR

This sets the listen address of the portal server. The default is 0.0.0.0:3003.

CONFIG_SOURCE_TYPE

This sets the type of the configuration. Valid values are local_fs and kubernetes. The default is local_fs.

CONFIG_SOURCE_KUBECONFIG

This indicates the path to the .kubeconfig config file. It is only used when configuration type is kubernetes.

CONFIG_SOURCE_KUBE_NAMESPACE

This indicates the namespace where Kubernetes resources of all apps reside. It is only used when configuration type is kubernetes.

CONFIG_SOURCE_WATCH

This indicates whether the configuration source would watch for changes and reload automatically. The default is true.

CONFIG_SOURCE_DIRECTORY

This sets the path to app configuration directory file for local FS sources. The default is ..

AUTHGEAR_CLIENT_ID

This sets the OAuth client ID for Authgear portal.

AUTHGEAR_ENDPOINT

This sets the OAuth endpoint for Authgear portal.

AUTHGEAR_APP_ID

This sets the OAuth app ID for Authgear portal.

ADMIN_API_TYPE

This sets the type of the admin API. The only supported value for now is static. The default is static, so you should never change it.

ADMIN_API_ENDPOINT

This sets the endpoint of Admin API server. The default is http://localhost:3002.

ADMIN_API_HOST_TEMPLATE

This sets the host for tenant resolution. The default is localhost:3002.

APP_HOST_SUFFIX

This sets the host suffix for Authgear portal.

APP_ID_PATTERN

This sets the regular expression pattern for app ID validation. The defaults is ^[a-z0-9][a-z0-9-]{2,30}[a-z0-9]$.

APP_KUBERNETES_INGRESS_TEMPLATE_FILE

This sets the file of Kubernetes ingress template. It is only used when configuration type is kubernetes.

APP_KUBERNETES_DEFAULT_DOMAIN_TLS_CERT_TYPE

This sets the TLS cert type for default domain. Valid values are none, static, and cert-manager. The default is none. It is only used when configuration type is kubernetes.

APP_KUBERNETES_DEFAULT_DOMAIN_TLS_CERT_SECRET_NAME

This sets the secret name for default domain. It is only used when configuration type is kubernetes and TLS cert type is static.

APP_KUBERNETES_DEFAULT_DOMAIN_TLS_CERT_ISSUER_KIND

This sets the issuer kind for default domain. It is only used when configuration type is kubernetes and TLS cert type is cert-manager.

APP_KUBERNETES_DEFAULT_DOMAIN_TLS_CERT_ISSUER_NAME

This sets the issuer name for default domain. It is only used when configuration type is kubernetes and TLS cert type is cert-manager.

APP_KUBERNETES_CUSTOM_DOMAIN_TLS_CERT_TYPE

This sets the TLS cert type for custom domain. Valid values are none, static, and cert-manager. The default is none. It is only used when configuration type is kubernetes.

APP_KUBERNETES_CUSTOM_DOMAIN_TLS_CERT_SECRET_NAME

This sets the secret name for custom domain. It is only used when configuration type is kubernetes and TLS cert type is static.

APP_KUBERNETES_CUSTOM_DOMAIN_TLS_CERT_ISSUER_KIND

This sets the issuer kind for custom domain. It is only used when configuration type is kubernetes and TLS cert type is cert-manager.

APP_KUBERNETES_CUSTOM_DOMAIN_TLS_CERT_ISSUER_NAME

This sets the issuer name for custom domain. It is only used when configuration type is kubernetes and TLS cert type is cert-manager.

APP_BUILTIN_RESOURCE_DIRECTORY

This sets the directory for built-in resource files. The default is resources/authgear.

APP_CUSTOM_RESOURCE_DIRECTORY

This sets the directory for customized resource files.

APP_MAX_OWNED_APPS

This sets the maximum number of apps user owned. When the value is -1, owned apps limit is disabled. The default is -1.

STATIC_ASSET_SERVING_ENABLED

This sets whether the bundled static asset should be served. Default is true. You should never modify it.

STATIC_ASSET_DIR

This sets the filepath of the directory containing the bundled static asset. The default value of the provided Docker image does the right thing so you should never need to set it.

DATABASE_URL

This sets the URL of backend database.

DATABASE_SCHEMA

This sets the database schema of backend database. The default is public.

DATABASE_MAX_OPEN_CONN

This sets the maximum open connections of backend database. The default is 2.

DATABASE_MAX_IDLE_CONN

This sets the maximum idle connections of backend database. The default is 2.

DATABASE_CONN_MAX_LIFETIME

This sets the maximum lifetime of backend database connection in seconds. The default is 1800.

DATABASE_CONN_MAX_IDLE_TIME

This sets the maximum idle time of backend database connection in seconds. The default is 300.

SMTP_HOST

This sets the server host of SMTP server.

SMTP_PORT

This sets the server port of SMTP server.

SMTP_USERNAME

This sets the username of SMTP server.

SMTP_PASSWORD

This sets the password of SMTP server.

SMTP_MODE

This sets the SMTP mode. Valid values are normal and ssl. The default is normal.

MAIL_SENDER

This sets the sender field of admin invitation email.

MAIL_REPLY_TO

This sets the reply to field of admin invitation email.

PORTAL_BUILTIN_RESOURCE_DIRECTORY

This sets the directory for built-in resource files. The default is resources/portal.

PORTAL_CUSTOM_RESOURCE_DIRECTORY

This sets the directory for customized resource files.

Common Environment Variable

Common environment variable provides global configuration for both main server and Authgear portal.

TRUST_PROXY

This sets whether incoming HTTP headers such as x-forwarded-host can be trusted. If you deploy Authgear behind a reverse proxy capable of writing these headers, you should set the value to true. The default is false.

DEV_MODE

This sets whether Authgear should run in development mode. You should never need to set it. The default is false.

When development mode is enabled:

• TLS certificate is required, to enable secure cookies.

• All Host header values are allowed.

• External message sending (SMS/Email) is disabled; messages to send are logged instead.

LOG_LEVEL

This sets the global log level. Valid values are debug, info, warn and error. The default is warn.

STATIC_ASSET_URL_PREFIX

This sets the URL prefix of the bundled static asset. The default value includes commit hash so it is cache-friendly.

SENTRY_DSN

The sets the Sentry DSN, where errors/logs are reported to.

TL;DR

The only environment variable you should be aware of is TRUST_PROXY.