Server configuration

Core Corteza services are configured via the environment (.env) file. It allows a quick deploy to another platform, along with fine-tuning the system’s behaviour and enabled features.

The .env file is at the root of the application. In the context of Docker Compose, it is next to the docker-compose.yaml file.

The .env file affects three levels:

Implicit Docker Compose configuration,
variable substitution in Docker configuration,
service configuration.

When you are using Docker Compose, you must explicitly reference the environment file for each service in the docker-compose.yaml file (env_file: [.env]).

You can use variables defined in the .env inside your docker-compose.yaml file; for example ${VERSION}.

Base configuration

These variables control the base Corteza configurations, such as the port and the database DSN.

Type Default value Description

Type	Default value	Description
DB_DSN
`string`	corteza:corteza@tcp(db:3306)/corteza?collation=utf8mb4_general_ci	Database connection string <username>:<password>@(<host>:<port>)/<dbname>?collation=utf8mb4_general_ci
DB_MAX_TRIES
`int`	100	Maximum number of connection retries.
DB_CONN_ERR_DELAY
`duration`	5 seconds	Duration between database connection retries.
DB_CONN_TIMEOUT
`duration`	1 minute	After how long we should give up on connecting with the database.
GRPC_SERVER_NETWORK
`string`	tcp	Network to use for gRPC.
GRPC_SERVER_ADDR
`string`	:50051	Where do we listen for gRPC connections.
GRPC_CLIENT_BACKOFF_DELAY
`duration`	1 minute	Maximum delay for backoff on connection.
HTTP_ADDR
`string`	:80	IP and port for the HTTP server.
HTTP_METRICS
`boolean`	false	Enable (prometheus) metrics.
HTTP_METRICS_NAME
`string`	corteza	Name for metrics endpoint.
HTTP_METRICS_USERNAME
`string`	metrics	Username for the metrics endpoint.
HTTP_METRICS_PASSWORD
`string`	(random)	Password for the metrics endpoint.
HTTP_CLIENT_TIMEOUT
`boolean`	30 seconds	Default timeout for clients.
MONITOR_INTERVAL
`duration`	5 minutes	Output (log) interval for monitoring.
STORAGE_PATH
`string`	var/store	Where do we store uploaded files

DB_DSN

string

corteza:corteza@tcp(db:3306)/corteza?collation=utf8mb4_general_ci

Database connection string <username>:<password>@(<host>:<port>)/<dbname>?collation=utf8mb4_general_ci

DB_MAX_TRIES

int

100

Maximum number of connection retries.

DB_CONN_ERR_DELAY

duration

5 seconds

Duration between database connection retries.

DB_CONN_TIMEOUT

duration

1 minute

After how long we should give up on connecting with the database.

GRPC_SERVER_NETWORK

string

tcp

Network to use for gRPC.

GRPC_SERVER_ADDR

string

:50051

Where do we listen for gRPC connections.

GRPC_CLIENT_BACKOFF_DELAY

duration

1 minute

Maximum delay for backoff on connection.

HTTP_ADDR

string

:80

IP and port for the HTTP server.

HTTP_METRICS

boolean

false

Enable (prometheus) metrics.

HTTP_METRICS_NAME

string

corteza

Name for metrics endpoint.

HTTP_METRICS_USERNAME

string

metrics

Username for the metrics endpoint.

HTTP_METRICS_PASSWORD

string

(random)

Password for the metrics endpoint.

HTTP_CLIENT_TIMEOUT

boolean

30 seconds

Default timeout for clients.

MONITOR_INTERVAL

duration

5 minutes

Output (log) interval for monitoring.

STORAGE_PATH

string

var/store

Where do we store uploaded files

Security

These variables control security aspects of Corteza, such as the JWT token secret and the token lifetime.

Type Default value Description

AUTH_JWT_SECRET

string

(random)

Secret used for signing JWT tokens.

Make sure to provide a secret. If you don’t, a random value is assigned — this causes all of the tokens to become invalid after a server restart.

AUTH_JWT_EXPIRY

duration

1 month

Expiration time for the auth JWT tokens.

HTTP_CLIENT_TSL_INSECURE

boolean

false

Allow insecure (invalid, expired TSL/SSL certificates) connections.

We strongly recommend keeping this value set to false except for local development or demos.

Provisioning

Provisioning allows you to configure a Corteza instance when deployed. It occurs automatically after the Corteza server starts.

We recommend you to keep provisioning enabled as it simplifies version updates by updating the database and updating settings.

If you’re doing local development or some debugging, you can disable this.

Type Default value Description

Type	Default value	Description
PROVISION_ALWAYS
`boolean`	true	Controls if the provisioning should run when the server starts.
UPGRADE_ALWAYS
`boolean`	true	Controls if the upgradable systems should be upgraded when the server starts.

PROVISION_ALWAYS

boolean

true

Controls if the provisioning should run when the server starts.

UPGRADE_ALWAYS

boolean

true

Controls if the upgradable systems should be upgraded when the server starts.

Provision authentication settings

Key Type Default value Description

Key	Type	Default value	Description
PROVISION_SETTINGS_AUTH_EXTERNAL_ENABLED
`auth.external.enabled`	`boolean`	true	Is OAuth2 enabled or disabled.
PROVISION_SETTINGS_AUTH_EXTERNAL_REDIRECT_URL
`auth.external.redirect-url`	`string`		searches env-variables (`DOMAIN`, `LETSENCRYPT_HOST`, `VIRTUAL_HOST`, `HOSTNAME`, `HOST`) and uses additional info (monolith, api-base-url) to calculate the value.
PROVISION_SETTINGS_AUTH_EXTERNAL_SESSION_STORE_SECRET
`auth.external.session-store-secret`	`string`	random 64 char string	generated 64 char long string if missing. Is session cookie "secure" flag used (if yes, cookie can only be access over HTTPS).
PROVISION_SETTINGS_AUTH_EXTERNAL_SESSION_STORE_SECURE
`auth.external.session-store-secure`	`boolean`	false	If HTTPS is used for external auth redirection url, value is set to true.
PROVISION_SETTINGS_AUTH_FRONTEND_URL_BASE
`auth.frontend.url.base`	`string`		Where the frontend SPA is located. Serves as base for generating other `auth.frontend.url…` variables.
PROVISION_SETTINGS_AUTH_FRONTEND_URL_PASSWORD_RESET
`auth.frontend.url.password-reset`	`string`		Where the frontend SPA is located, the password reset form.
PROVISION_SETTINGS_AUTH_FRONTEND_URL_EMAIL_CONFIRMATION
`auth.frontend.url.email-confirmation`	`string`		Where the frontend SPA is located, password email confirmation page. `auth.frontend.url.base` is used as base URL
PROVISION_SETTINGS_AUTH_FRONTEND_URL_REDIRECT
`auth.frontend.url.redirect`	`string`		Where the frontend SPA is located. User will be redirected here on successful external authentication. Auto discovery uses `auth.frontend.url.base` as base URL.
PROVISION_SETTINGS_AUTH_EMAIL_FROM_ADDRESS
`auth.mail.from-address`	`string`	to-be-configured@example.tld	Email address used for sending auth emails (password reset, email confirmation). Name used for sending auth emails (password reset, email confirmation).
PROVISION_SETTINGS_AUTH_EMAIL_FROM_NAME
`auth.mail.from-name`	`string`	Corteza Team (to-be-configured)	The email from parameter.
PROVISION_SETTINGS_AUTH_INTERNAL_ENABLED
`auth.internal.signup`	`boolean`	true	Controls if users are allowed to use internal authentication features, such as login, sign-up, and password reset.
PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_ENABLED
`auth.internal.signup.enabled`	`boolean`	true	Controls if users are allowed to ue internal authentication sign-up.
PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_EMAIL_CONFIRMATION_REQUIRED
`auth.internal.signup-email-confirmation-required`	`boolean`	false	Controls if users are required to confirm the email? Enabled on auto-discovery if server has email capabilities (`SMTP_HOST` variable is set).
PROVISION_SETTINGS_AUTH_INTERNAL_PASSWORD_RESET_ENABLED
`auth.internal.password-reset.enabled`	`boolean`	false	Controls if suers are allowed to use password reset for accounts created via internal sign-up.

PROVISION_SETTINGS_AUTH_EXTERNAL_ENABLED

auth.external.enabled

boolean

true

Is OAuth2 enabled or disabled.

PROVISION_SETTINGS_AUTH_EXTERNAL_REDIRECT_URL

auth.external.redirect-url

string

searches env-variables (DOMAIN, LETSENCRYPT_HOST, VIRTUAL_HOST, HOSTNAME, HOST) and uses additional info (monolith, api-base-url) to calculate the value.

PROVISION_SETTINGS_AUTH_EXTERNAL_SESSION_STORE_SECRET

auth.external.session-store-secret

string

random 64 char string

generated 64 char long string if missing.

Is session cookie "secure" flag used (if yes, cookie can only be access over HTTPS).

PROVISION_SETTINGS_AUTH_EXTERNAL_SESSION_STORE_SECURE

auth.external.session-store-secure

boolean

false

If HTTPS is used for external auth redirection url, value is set to true.

PROVISION_SETTINGS_AUTH_FRONTEND_URL_BASE

auth.frontend.url.base

string

Where the frontend SPA is located. Serves as base for generating other auth.frontend.url… variables.

PROVISION_SETTINGS_AUTH_FRONTEND_URL_PASSWORD_RESET

auth.frontend.url.password-reset

string

Where the frontend SPA is located, the password reset form.

PROVISION_SETTINGS_AUTH_FRONTEND_URL_EMAIL_CONFIRMATION

auth.frontend.url.email-confirmation

string

Where the frontend SPA is located, password email confirmation page. auth.frontend.url.base is used as base URL

PROVISION_SETTINGS_AUTH_FRONTEND_URL_REDIRECT

auth.frontend.url.redirect

string

Where the frontend SPA is located. User will be redirected here on successful external authentication. Auto discovery uses auth.frontend.url.base as base URL.

PROVISION_SETTINGS_AUTH_EMAIL_FROM_ADDRESS

auth.mail.from-address

string

to-be-configured@example.tld

Email address used for sending auth emails (password reset, email confirmation).

Name used for sending auth emails (password reset, email confirmation).

PROVISION_SETTINGS_AUTH_EMAIL_FROM_NAME

auth.mail.from-name

string

Corteza Team (to-be-configured)

The email from parameter.

PROVISION_SETTINGS_AUTH_INTERNAL_ENABLED

auth.internal.signup

boolean

true

Controls if users are allowed to use internal authentication features, such as login, sign-up, and password reset.

PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_ENABLED

auth.internal.signup.enabled

boolean

true

Controls if users are allowed to ue internal authentication sign-up.

PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_EMAIL_CONFIRMATION_REQUIRED

auth.internal.signup-email-confirmation-required

boolean

false

Controls if users are required to confirm the email? Enabled on auto-discovery if server has email capabilities (SMTP_HOST variable is set).

PROVISION_SETTINGS_AUTH_INTERNAL_PASSWORD_RESET_ENABLED

auth.internal.password-reset.enabled

boolean

false

Controls if suers are allowed to use password reset for accounts created via internal sign-up.

Provision OIDC providers

Type Default value Description

Type	Default value	Description
PROVISION_OIDC_PROVIDER
`string`		Registers available providers from a list of space delimited provided pairs (`<name> <provider-url>` or `<name> <provider-url> <name-2> <provider-url-2>`). The provider is auto-discovered only if it does not exist (match by name). Also, make sure that your redirect URL (`auth.external.redirect-url`) is properly configured.
PROVISION_SETTINGS_AUTH_EXTERNAL_REDIRECT_URL
`string`		Sets value for `auth.external.redirect-url` setting. This should be set to `https://api.your-corteza-instance.tld/system/auth/external/{PROVIDER_NAME}/callback`.

PROVISION_OIDC_PROVIDER

string

Registers available providers from a list of space delimited provided pairs (<name> <provider-url> or <name> <provider-url> <name-2> <provider-url-2>).

The provider is auto-discovered only if it does not exist (match by name).

Also, make sure that your redirect URL (auth.external.redirect-url) is properly configured.

PROVISION_SETTINGS_AUTH_EXTERNAL_REDIRECT_URL

string

Sets value for auth.external.redirect-url setting.

This should be set to https://api.your-corteza-instance.tld/system/auth/external/{PROVIDER_NAME}/callback.

Provision other external provider

Type Default value Description

Type	Default value	Description
PROVISION_SETTINGS_AUTH_EXTERNAL_GITHUB
`string`		Github’s app credentials: `<key> <secret>`.
PROVISION_SETTINGS_AUTH_EXTERNAL_FACEBOOK
`string`		Facebook’s app credentials: `<key> <secret>`.
PROVISION_SETTINGS_AUTH_EXTERNAL_GOOGLE
`string`		Google’s app credentials: `<key> <secret>`.
PROVISION_SETTINGS_AUTH_EXTERNAL_LINKEDIN
`string`		LinkedIn’s app credentials: `<key> <secret>`.
PROVISION_SETTINGS_AUTH_EXTERNAL_OIDC
`string`		OIDC provider settings `<name> <issuer> <key> <secret>`.

PROVISION_SETTINGS_AUTH_EXTERNAL_GITHUB

string

Github’s app credentials: <key> <secret>.

PROVISION_SETTINGS_AUTH_EXTERNAL_FACEBOOK

string

Facebook’s app credentials: <key> <secret>.

PROVISION_SETTINGS_AUTH_EXTERNAL_GOOGLE

string

Google’s app credentials: <key> <secret>.

PROVISION_SETTINGS_AUTH_EXTERNAL_LINKEDIN

string

LinkedIn’s app credentials: <key> <secret>.

PROVISION_SETTINGS_AUTH_EXTERNAL_OIDC

string

OIDC provider settings <name> <issuer> <key> <secret>.

SMTP

Type Default value Description

Type	Default value	Description
SMTP_HOST
`string`	localhost:25	The SMTP server hostname.
SMTP_PORT
`int`		The SMTP post.
SMTP_USER
`string`		The SMTP username.
SMTP_PASS
`string`		The SMTP password.
SMTP_FROM
`string`		The `from` email parameter.

SMTP_HOST

string

localhost:25

The SMTP server hostname.

SMTP_PORT

int

The SMTP post.

SMTP_USER

string

The SMTP username.

SMTP_PASS

string

The SMTP password.

SMTP_FROM

string

The from email parameter.

Corredor

Type Default value Description

Type	Default value	Description
CORREDOR_ENABLED
`boolean`	true	Enable/disable Corredor integration.
CORREDOR_ADDR
`string`	corredor:80	Hostname and port of the Corredor gRPC server.
CORREDOR_MAX_BACKOFF_DELAY
`duration`	1 minute	Max delay for backoff on connection.
CORREDOR_MAX_RECEIVE_MESSAGE_SIZE
int	16MB
CORREDOR_DEFAULT_EXEC_TIMEOUT
time	1 minute
CORREDOR_LIST_TIMEOUT
duration	2 second
CORREDOR_LIST_REFRESH
duration	2 second
CORREDOR_RUN_AS_ENABLED
bool	false
CORREDOR_CLIENT_CERTIFICATES_ENABLED
bool	false
CORREDOR_CLIENT_CERTIFICATES_PATH
string	/certs/corredor/client
CORREDOR_CLIENT_CERTIFICATES_CA
string	ca.crt
CORREDOR_CLIENT_CERTIFICATES_PUBLIC
string	public.crt
CORREDOR_CLIENT_CERTIFICATES_PRIVATE
string	private.key
CORREDOR_CLIENT_CERTIFICATES_SERVER_NAME
string	""

CORREDOR_ENABLED

boolean

true

Enable/disable Corredor integration.

CORREDOR_ADDR

string

corredor:80

Hostname and port of the Corredor gRPC server.

CORREDOR_MAX_BACKOFF_DELAY

duration

1 minute

Max delay for backoff on connection.

CORREDOR_MAX_RECEIVE_MESSAGE_SIZE

int

16MB

CORREDOR_DEFAULT_EXEC_TIMEOUT

time

1 minute

CORREDOR_LIST_TIMEOUT

duration

2 second

CORREDOR_LIST_REFRESH

duration

2 second

CORREDOR_RUN_AS_ENABLED

bool

false

CORREDOR_CLIENT_CERTIFICATES_ENABLED

bool

false

CORREDOR_CLIENT_CERTIFICATES_PATH

string

/certs/corredor/client

CORREDOR_CLIENT_CERTIFICATES_CA

string

ca.crt

CORREDOR_CLIENT_CERTIFICATES_PUBLIC

string

public.crt

CORREDOR_CLIENT_CERTIFICATES_PRIVATE

string

private.key

CORREDOR_CLIENT_CERTIFICATES_SERVER_NAME

string

MinIO

The MinIO integration allows you to replace local storage with cloud storage. When configured, STORAGE_PATH is not needed.

Type Default value Description

Type	Default value	Description
MINIO_ENDPOINT
`string`
MINIO_SECURE
`boolean`	true
MINIO_ACCESS_KEY
`string`
MINIO_SECRET_KEY
`string`
MINIO_SSEC_KEY
`string`
MINIO_BUCKET
`string`
MINIO_STRICT
`boolean`	false

MINIO_ENDPOINT

string

MINIO_SECURE

boolean

true

MINIO_ACCESS_KEY

string

MINIO_SECRET_KEY

string

MINIO_SSEC_KEY

string

MINIO_BUCKET

string

MINIO_STRICT

boolean

false

Debugging

These parameters help in the development and testing process. When you are deploying to production, these should be disabled to improve performance and reduce storage usage.

You should configure external services such as Sentry or ELK to keep track of logs and error reports.

Sentry

Type Default value Description

Type	Default value	Description
SENTRY_DSN
`string`		Set to enable Sentry client.
SENTRY_DEBUG
`boolean`	false	Print out debugging information.
SENTRY_ATTACH_STACKTRACE
`boolean`	false	Attach stacktraces.
SENTRY_SAMPLE_RATE
`float32`		Sample rate for event submission (0.0 - 1.0, defaults to 1.0).
SENTRY_MAX_BREADCRUMBS
`int`		Maximum number of breadcrumbs.
SENTRY_SERVERNAME
`string`		Set reported Server name.
SENTRY_RELEASE
`string`	(current version)	Set reported Release.
SENTRY_DIST
`string`		Set reported distribution.
SENTRY_ENVIRONMENT
`string`		Set reported environment.

SENTRY_DSN

string

Set to enable Sentry client.

SENTRY_DEBUG

boolean

false

Print out debugging information.

SENTRY_ATTACH_STACKTRACE

boolean

false

Attach stacktraces.

SENTRY_SAMPLE_RATE

float32

Sample rate for event submission (0.0 - 1.0, defaults to 1.0).

SENTRY_MAX_BREADCRUMBS

int

Maximum number of breadcrumbs.

SENTRY_SERVERNAME

string

Set reported Server name.

SENTRY_RELEASE

string

(current version)

Set reported Release.

SENTRY_DIST

string

Set reported distribution.

SENTRY_ENVIRONMENT

string

Set reported environment.

Logging

Type Default value Description

Type	Default value	Description
DB_LOGGER
`boolean`	false	Log SQL queries.
CORREDOR_LOG_ENABLED
`boolean`	false	Log communication with Corredor.
HTTP_REPORT_PANIC
`boolean`	true	Report HTTP panic to Sentry.
HTTP_LOG_REQUEST
`boolean`	false	Log HTTP requests.
HTTP_LOG_RESPONSE
`boolean`	false	Log HTTP responses.
HTTP_ENABLE_VERSION_ROUTE
`boolean`	false	Enable `/version` route.
HTTP_ENABLE_DEBUG_ROUTE
`boolean`	false	Enable `/debug` route.
GRPC_CLIENT_LOG
`boolean`	false	Log gRPC communication.

DB_LOGGER

boolean

false

Log SQL queries.

CORREDOR_LOG_ENABLED

boolean

false

Log communication with Corredor.

HTTP_REPORT_PANIC

boolean

true

Report HTTP panic to Sentry.

HTTP_LOG_REQUEST

boolean

false

Log HTTP requests.

HTTP_LOG_RESPONSE

boolean

false

Log HTTP responses.

HTTP_ENABLE_VERSION_ROUTE

boolean

false

Enable /version route.

HTTP_ENABLE_DEBUG_ROUTE

boolean

false

Enable /debug route.

GRPC_CLIENT_LOG

boolean

false

Log gRPC communication.

Delaying API execution

You can configure these options to defer API execution until another external (HTTP) service is up and running.

Delaying API execution can come in handy in complex setups where execution order is important.

Type Default value Description

Type	Default value	Description
WAIT_FOR
`duration`	0	Delays API startup for the amount of time specified (10s, 2m…). This delay happens before service (WAIT_FOR_SERVICES) probing.
WAIT_FOR_STATUS_PAGE
`boolean`	true	Show temporary status web page.
WAIT_FOR_SERVICES
`string`		Space delimited list of hosts and/or URLs to probe. Host format: `host` or `host:443` (port will default to 80). Services are probed in parallel.
WAIT_FOR_SERVICES_TIMEOUT
`duration`	1m	Max time for each service probe.
WAIT_FOR_SERVICES_PROBE_TIMEOUT
`duration`	30s	Timeout for each service probe.
WAIT_FOR_SERVICES_PROBE_INTERVAL
`duration`	5s	Interval between service probes.

WAIT_FOR

duration

Delays API startup for the amount of time specified (10s, 2m…).

This delay happens before service (WAIT_FOR_SERVICES) probing.

WAIT_FOR_STATUS_PAGE

boolean

true

Show temporary status web page.

WAIT_FOR_SERVICES

string

Space delimited list of hosts and/or URLs to probe. Host format: host or host:443 (port will default to 80).

Services are probed in parallel.

WAIT_FOR_SERVICES_TIMEOUT

duration

Max time for each service probe.

WAIT_FOR_SERVICES_PROBE_TIMEOUT

duration

30s

Timeout for each service probe.

WAIT_FOR_SERVICES_PROBE_INTERVAL

duration

Interval between service probes.