Workspace Configuration

This page describes how to configure an Engine workspace.

Engine workspaces can be configured directly in the workspace or through environment variables contained in a configuration file on the server. Not all configuration options are available in both places, particularly fundamental configurations like database access can only be set via environment variables. All configuration options have a built-in default value.

The order of application of workspace configuration values is:

1. Manually set values in the workpsace configuration directly in the workspace. If none is set:
2. Manually set values in the environment variables configuration file (on the server). If none is set:
3. Default values

Workspace Configuration in the Workspace

Via the UI

Engine provides a UI screen for editing workspace settings easily.

You can access workspace settings through this menu

The UI provides an overview of all available setting, their default and environment values, and their effective values (e.g. if the setting is overwritten by a manual value). Once you edit a setting, the change immediately takes effect.

The UI screen

Via REST API

Refer to the REST API documentation under the header "System" for information on how to access and update the workspace configuration via the REST API. Refer to Workspace Configuration Options for a list and description of all available options.

To be able to change workspace_configuration via the REST API the calling identity must have UPDATE permissions on the workspace record type.

Environment Variables

note

For on-premise installations these options can be set by users managing the Engine installation as environment variables on the docker containers. For cloud installations the options are managed by us. Please get in touch with support@cloudomation.com to request a change.

Below table shows all recognized options and their description for configuration options which can only be set in the environment variables. Please note that all options listed in Workspace Configuration Options can also be set via environment variables.

Note the order of application of environment variables: if an option is set both in environment variables, as well as in the workspace directly, the option configured in the workspace directly will take precedence over the option set in the environment variables.

Some of the settings are applicable for the workspace container, others for the auth container, some for both. For on-premise installations the values can be set in workspace.env and auth.env respectively.

Main Settings

Name	Description	Default value	Required	Workspace	Auth
SOCKET and SANDBOX_SOCKET	Path to a writable unix-domain-socket file used for communication between the workspace and the sandbox. The workspace will create the file.	/socket/socket
SKIP_PROBES	If non-empty, the workspace will not create /alive and /ready REST endpoints for monitoring.
LISTEN_IP	The IP address the REST API will bind to.	0.0.0.0
LISTEN_PORT	The port number the REST API will bind to.	8080
POSTGRES_HOST	The hostname of the Engine database.		required
POSTGRES_PORT	The port number of the Engine database.	5432
POSTGRES_DATABASE	The name of the Engine database.		required
POSTGRES_USER	The username used to authenticate against the database.		required
POSTGRES_PASSWORD	The password used to authenticate against the database.
POSTGRES_PASSWORD_FILE	Path to a file containing the database password.		required if POSTGRES_PASSWORD is unset
POSTGRES_SERVER_CA_FILE	Path to the databases certificate file.
POSTGRES_CLIENT_CERT_FILE	Path to a database client certificate file.
POSTGRES_CLIENT_KEY_FILE	Path to a database client certificate key file.
TMP	Temporary path.	/c/tmp
TMP_GIT_TASK	Temporary path for the GIT connector.	/c/tmp_git_task
TMP_GIT_SYNC	Temporary path where the git repositories are synced to.	/c/tmp
SMTP_HOST	The hostname of the SMTP server used to send notifications.
SMTP_PORT	The port number of the SMTP server.	25
SMTP_USE_TLS	If to use the SMTP "usetls" command.	true
SMTP_USER	The username used to authenticate against the SMTP server.
SMTP_PASSWORD	The password used to authenticate against the SMTP server.
NOTIFICATION_PATH	Path to a folder where internal notifications are written to. Only used when no SMTP connection is configured.
REPORT_ENABLE	If to periodically write a usage report.	True
REPORT_PATH	The path where usage report is written to.	/tmp/report.csv
DOMAIN	The domain where your workspace is accessible. Used to generate links to the workspace in mails.		required
SUBDOMAIN	The subdomain where your workspace is accessible. Used to generate links to the workspace in mails.		required
SELF_URL	The FQDN to your workspace. Used to generate links to the workspace in mails.		required

License Settings

All license settings are only applicable for the workspace container.

Name	Description	Required
WORKSPACE_ID	The ID of the workspace installation.	required
WORKSPACE_NAME	The name of the workspace.	required
ORGANIZATION_ID	The ID of the organization.	required
ORGANIZATION_NAME	The name of the organization.	required
API_KEY	An API key used for the communication between the workspace and the license server.	required

Security Settings

Name	Description	Default value	Required	Workspace	Auth
LOGIN_TOKEN_VALIDITY_HOURS	The number of hours a login token remains valid after login. Cannot be more than 720 (30 days).	720
INVITATION_CODE_VALIDITY_HOURS	The number of hours an invitation code is valid. Cannot be more than 168 (7 days)	168
RECOVER_CODE_VALIDITY_HOURS	The number of hours a recovery code is valid. Cannot be more than 24 (1 day)	1
MAX_FAILED_AUTH_COUNT	Number of failed login attempts before an Engine user is locked out. Cannot be less than 1	5
JWT_PUBLIC_KEY	Path to the public RSA key used to verify login tokens.		required
JWT_PRIVATE_KEY	Path to the private RSA key used to generate login tokens.		required
JWT_PUBLIC_KEY_2	Path to the previous public RSA key used to verify login tokens during key rotation.
COOKIE_SAME_SITE	The value used for the SameSite cookie flag of login tokens. One of Strict, Lax, or unset	Lax
BOOTSTRAP_USER	The email address of the initial user of the workspace. This use cannot be renamed or deleted and has all permissions.		required
INACTIVE_IDLE_LIMIT_MINUTES	After how many minutes of inactivity development-mode executions will be paused.	10
HTTP_PROXY	The proxy server to use for http:// requests. Eg. http://my-proxy:8080
HTTPS_PROXY	The proxy server to use for https:// requests. Eg. http://my-proxy:8080
WS_PROXY	The proxy server to use for ws:// (web-socket) requests. Eg. http://my-proxy:8080
WSS_PROXY	The proxy server to use for wss:// (web-socket secure) requests. Eg. http://my-proxy:8080
REQUIRE_SECOND_FACTOR	If set to true new users must activate a 2FA device and it is not possible to disable 2FA	false

Performance Settings

All performance settings are only applicable for the workspace container.

Name	Description	Default value
DB_KEEPALIVE_INTERVAL	How often to register the process as "alive" in the database. If the database does not respond within this timeout the process will shut down.	60
DB_KEEPALIVE_TIMEOUT	A process which did not register as "alive" after this timeout will be considered "dead" and removed from the database.	120
GIT_SYNC_INTERVAL	How often to synchronize git repositories (in seconds).	600 (10 minutes)
POLL_DELAY	The number of seconds between checks of the primary process.	30
POLL_SLOW_DELAY	The number of seconds between database consistency checks.	1800 (30 minutes)
CHUNK_SIZE	The number of bytes to read from a file at once.	4194304 (4 MiB)
SLEEP_MAX_SECONDS	Executions being idle longer than this setting will be unloaded from memory.	5
RECURSE_MAX_SIZE	Limits how many items a nested data structure can have for it to be recursively walked for the purpose of secret expansion, datatype conversion or the application of default values. Eg. an executemany argument for an MSSQL connection with params=[a, list, of, 15_000, rows] will not apply datatype conversions and the items in the list will be passed to the connection as is.	100