API Server

Provisioning

Provisioning is step after server is started and API becomes available. It allows you to directly influence how a fresh Corteza instance is configured on first run. This entire process can be disabled by setting env. variables PROVISION_MIGRATE_DATABASE and PROVISION_CONFIGURATION to false.

Table 1. Control provisioning procedure
Type	Default value	Description
`PROVISION_MIGRATE_DATABASE`
`boolean`	`true`	Controls if database migration (creation of tables, changes of schema between versions) should be done before each service is started. It’s recommended to keep this setting on. Disabling it on a running server prevents migration between version udpates
`PROVISION_CONFIGURATION`
`boolean`	`true`	Runs various auto-setup procedures and creates resources: - creates default permission rules and roles - default channels are created - default applications are created - compose resources (namespaces, modules, charts,…) - settings auto-discovery

Table 2. Provision authentication settings:
Type	Default value	Description
`PROVISION_SETTINGS_AUTH_EXTERNAL_ENABLED`
`auth.external.enabled`
`boolean`	`true`	Is OAuth2 enabled or disabled OAuth2 flow redirection URL.
`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`
`bool`	`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. Where the frontend SPA is located, password email confirmation page.
`PROVISION_SETTINGS_AUTH_FRONTEND_URL_EMAIL_CONFIRMATION`
`auth.frontend.url.email-confirmation`
`string`	`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) Is internal auth enabled? Enable this to allow users to use all (enabled) internal features (sign-up, log in….)
`auth.internal.signup`
`PROVISION_SETTINGS_AUTH_INTERNAL_ENABLED`
`boolean`	`true`
`PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_ENABLED`
`auth.internal.signup.enabled`
`boolean`	`true`	Is internal sign-up enabled? Enable this to allow users to register if you do not have external authentication providers.
`PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_EMAIL_CONFIRMATION_REQUIRED`
`auth.internal.signup-email-confirmation-required`
`boolean`	`false`	Is email confirmation required for internal sign-ups? 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`	Is password reset enabled for internal account? Auto-discovery enables this if server has email capabilities (`SMTP_HOST` variable is set)

Table 3. Provision OIDC providers:
Type	Default value	Description
`PROVISION_OIDC_PROVIDER`
`string`		Registers all given providers on start. Provide a list of space delimited provider 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. and `PROVISION_SETTINGS_AUTH_EXTERNAL_REDIRECT_URL`.
`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/%s/callback`

Table 4. Provision other external provider
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_GPLUS`
`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>`

Server options

Type Default value Description

Type	Default value	Description
`CORREDOR_ENABLED`
`bool`	`true`	Enable/disable Corredor integration
`CORREDOR_ADDR`
`string`	`corredor:80`	Hostname and port of the Corredor gRPC server
`CORREDOR_LOG_ENABLED`
`bool`	`false`	Log communication with Corredor
`CORREDOR_MAX_BACKOFF_DELAY`
`duration`	`1 minute`	Max delay for backoff on connection
`CORREDOR_API_BASE_URL_SYSTEM`
`string`		Instructions passed to Corredor on every call - where Corteza API is located.
`CORREDOR_API_BASE_URL_MESSAGING`
`string`		Instructions passed to Corredor on every call - where Corteza API is located.
`CORREDOR_API_BASE_URL_COMPOSE`
`string`		Instructions passed to Corredor on every call - where Corteza API is located.
`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_LOGGER`
`bool`	`false`	Log SQL queries
`DB_MAX_TRIES`
`int`	`100`	Max number of connection retries
`DB_CONN_ERR_DELAY`
`duration`	`5 seconds`	How long do we wait between retries
`DB_CONN_TIMEOUT`
`duration`	`1 minute`	For how long do we try to connect
`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`	Max delay for backoff on connection
`GRPC_CLIENT_LOG`
`bool`	`false`	Log gRPC communication
`HTTP_ADDR`
`string`	`:80`	IP & port for HTTP server
`HTTP_LOG_REQUEST`
`bool`	`false`	Log requests
`HTTP_LOG_RESPONSE`
`bool`	`false`	Log responses
`HTTP_ENABLE_VERSION_ROUTE`
`bool`	`false`	Enable /version route
`HTTP_ENABLE_DEBUG_ROUTE`
`bool`	`false`	Enable /debug route
`HTTP_METRICS`
`bool`	`false`	Enable (prometheus) metrics
`HTTP_METRICS_NAME`
`string`	`corteza`	Name for metrics endpoint
`HTTP_METRICS_USERNAME`
`string`	`metrics`	Username for metrics endpoint
`HTTP_METRICS_PASSWORD`
`string`	`(random)`	Password for metrics endpoint
`HTTP_REPORT_PANIC`
`bool`		Report panic to Sentry
`HTTP_CLIENT_TSL_INSECURE`
`bool`	`false`	Allow insecure (invalid, expired TSL/SSL cert)
`HTTP_CLIENT_TIMEOUT`
`bool`	`30 seconds`	Default timeout for clients
`AUTH_JWT_SECRET`
`string`	`(random)`	Secret used for signing JWT tokens
`AUTH_JWT_EXPIRY`
`duration`	`1 month`	Expiration time
`MONITOR_INTERVAL`
`duration`	`5 minutes`	Output (log) interval for monitoring
`PROVISION_MIGRATE_DATABASE`
`bool`	`true`	Migrate database (if needed) on server start
`PROVISION_CONFIGURATION`
`bool`	`true`	Import configuration (only on empty database) on server start
`SENTRY_DSN`
`string`		Set to enable Sentry client
`SENTRY_DEBUG`
`bool`	`false`	Print out debugging information
`SENTRY_ATTACH_STACKTRACE`
`bool`	`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
`SMTP_HOST`
`string`	`localhost:25`
`SMTP_PORT`
`int`
`SMTP_USER`
`string`
`SMTP_PASS`
`string`
`SMTP_FROM`

`STORAGE_PATH`
`string`	`var/store`	Where do we store uploaded files
`MINIO_ENDPOINT`
`string`
`MINIO_SECURE`
`bool`	`true`
`MINIO_ACCESS_KEY`
`string`
`MINIO_SECRET_KEY`
`string`
`MINIO_SSEC_KEY`
`string`
`MINIO_BUCKET`
`string`
`MINIO_STRICT`
`bool`	`false`

CORREDOR_ENABLED

bool

true

Enable/disable Corredor integration

CORREDOR_ADDR

string

corredor:80

Hostname and port of the Corredor gRPC server

CORREDOR_LOG_ENABLED

bool

false

Log communication with Corredor

CORREDOR_MAX_BACKOFF_DELAY

duration

1 minute

Max delay for backoff on connection

CORREDOR_API_BASE_URL_SYSTEM

string

Instructions passed to Corredor on every call - where Corteza API is located.

CORREDOR_API_BASE_URL_MESSAGING

string

Instructions passed to Corredor on every call - where Corteza API is located.

CORREDOR_API_BASE_URL_COMPOSE

string

Instructions passed to Corredor on every call - where Corteza API is located.

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_LOGGER

bool

false

Log SQL queries

DB_MAX_TRIES

int

100

Max number of connection retries

DB_CONN_ERR_DELAY

duration

5 seconds

How long do we wait between retries

DB_CONN_TIMEOUT

duration

1 minute

For how long do we try to connect

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

Max delay for backoff on connection

GRPC_CLIENT_LOG

bool

false

Log gRPC communication

HTTP_ADDR

string

:80

IP & port for HTTP server

HTTP_LOG_REQUEST

bool

false

Log requests

HTTP_LOG_RESPONSE

bool

false

Log responses

HTTP_ENABLE_VERSION_ROUTE

bool

false

Enable /version route

HTTP_ENABLE_DEBUG_ROUTE

bool

false

Enable /debug route

HTTP_METRICS

bool

false

Enable (prometheus) metrics

HTTP_METRICS_NAME

string

corteza

Name for metrics endpoint

HTTP_METRICS_USERNAME

string

metrics

Username for metrics endpoint

HTTP_METRICS_PASSWORD

string

(random)

Password for metrics endpoint

HTTP_REPORT_PANIC

bool

Report panic to Sentry

HTTP_CLIENT_TSL_INSECURE

bool

false

Allow insecure (invalid, expired TSL/SSL cert)

HTTP_CLIENT_TIMEOUT

bool

30 seconds

Default timeout for clients

AUTH_JWT_SECRET

string

(random)

Secret used for signing JWT tokens

AUTH_JWT_EXPIRY

duration

1 month

Expiration time

MONITOR_INTERVAL

duration

5 minutes

Output (log) interval for monitoring

PROVISION_MIGRATE_DATABASE

bool

true

Migrate database (if needed) on server start

PROVISION_CONFIGURATION

bool

true

Import configuration (only on empty database) on server start

SENTRY_DSN

string

Set to enable Sentry client

SENTRY_DEBUG

bool

false

Print out debugging information

SENTRY_ATTACH_STACKTRACE

bool

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

SMTP_HOST

string

localhost:25

SMTP_PORT

int

SMTP_USER

string

SMTP_PASS

string

SMTP_FROM

STORAGE_PATH

string

var/store

Where do we store uploaded files

MINIO_ENDPOINT

string

MINIO_SECURE

bool

true

MINIO_ACCESS_KEY

string

MINIO_SECRET_KEY

string

MINIO_SSEC_KEY

string

MINIO_BUCKET

string

MINIO_STRICT

bool

false

Delaying API execution

With WAIT_FOR* Delaying API execution, waiting for external (HTTP) services.

This might aid you in complex setup where another service should be running and accessible before Corteza is ready.

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`
`bool`	`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

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

bool

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.