Skip to main content
Version: 10 - TBD

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

NameDescriptionDefault valueRequiredWorkspaceAuth
SOCKET and SANDBOX_SOCKETPath 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_PROBESIf non-empty, the workspace will not create /alive and /ready REST endpoints for monitoring.
LISTEN_IPThe IP address the REST API will bind to.0.0.0.0
LISTEN_PORTThe port number the REST API will bind to.8080
POSTGRES_HOSTThe hostname of the Engine database. required
POSTGRES_PORTThe port number of the Engine database.5432
POSTGRES_DATABASEThe name of the Engine database. required
POSTGRES_USERThe username used to authenticate against the database. required
POSTGRES_PASSWORDThe password used to authenticate against the database.
POSTGRES_PASSWORD_FILEPath to a file containing the database password. required if POSTGRES_PASSWORD is unset
POSTGRES_SERVER_CA_FILEPath to the databases certificate file.
POSTGRES_CLIENT_CERT_FILEPath to a database client certificate file.
POSTGRES_CLIENT_KEY_FILEPath to a database client certificate key file.
TMPTemporary path./c/tmp
TMP_GIT_TASKTemporary path for the GIT connector./c/tmp_git_task
TMP_GIT_SYNCTemporary path where the git repositories are synced to./c/tmp
SMTP_HOSTThe hostname of the SMTP server used to send notifications.
SMTP_PORTThe port number of the SMTP server.25
SMTP_USE_TLSIf to use the SMTP "usetls" command.true
SMTP_USERThe username used to authenticate against the SMTP server.
SMTP_PASSWORDThe password used to authenticate against the SMTP server.
NOTIFICATION_PATHPath to a folder where internal notifications are written to. Only used when no SMTP connection is configured.
REPORT_ENABLEIf to periodically write a usage report.True
REPORT_PATHThe path where usage report is written to./tmp/report.csv
DOMAINThe domain where your workspace is accessible. Used to generate links to the workspace in mails. required
SUBDOMAINThe subdomain where your workspace is accessible. Used to generate links to the workspace in mails. required
SELF_URLThe 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.

NameDescriptionRequired
WORKSPACE_IDThe ID of the workspace installation. required
WORKSPACE_NAMEThe name of the workspace. required
ORGANIZATION_IDThe ID of the organization. required
ORGANIZATION_NAMEThe name of the organization. required
API_KEYAn API key used for the communication between the workspace and the license server. required

Security Settings

NameDescriptionDefault valueRequiredWorkspaceAuth
LOGIN_TOKEN_VALIDITY_HOURSThe number of hours a login token remains valid after login. Cannot be more than 720 (30 days).720
INVITATION_CODE_VALIDITY_HOURSThe number of hours an invitation code is valid. Cannot be more than 168 (7 days)168
RECOVER_CODE_VALIDITY_HOURSThe number of hours a recovery code is valid. Cannot be more than 24 (1 day)1
MAX_FAILED_AUTH_COUNTNumber of failed login attempts before an Engine user is locked out. Cannot be less than 15
JWT_PUBLIC_KEYPath to the public RSA key used to verify login tokens. required
JWT_PRIVATE_KEYPath to the private RSA key used to generate login tokens. required
JWT_PUBLIC_KEY_2Path to the previous public RSA key used to verify login tokens during key rotation.
COOKIE_SAME_SITEThe value used for the SameSite cookie flag of login tokens. One of Strict, Lax, or unsetLax
BOOTSTRAP_USERThe email address of the initial user of the workspace. This use cannot be renamed or deleted and has all permissions. required
INACTIVE_IDLE_LIMIT_MINUTESAfter how many minutes of inactivity development-mode executions will be paused.10
HTTP_PROXYThe proxy server to use for http:// requests. Eg. http://my-proxy:8080
HTTPS_PROXYThe proxy server to use for https:// requests. Eg. http://my-proxy:8080
WS_PROXYThe proxy server to use for ws:// (web-socket) requests. Eg. http://my-proxy:8080
WSS_PROXYThe proxy server to use for wss:// (web-socket secure) requests. Eg. http://my-proxy:8080
REQUIRE_SECOND_FACTORIf set to true new users must activate a 2FA device and it is not possible to disable 2FAfalse

Performance Settings

All performance settings are only applicable for the workspace container.

NameDescriptionDefault value
DB_KEEPALIVE_INTERVALHow 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_TIMEOUTA process which did not register as "alive" after this timeout will be considered "dead" and removed from the database.120
GIT_SYNC_INTERVALHow often to synchronize git repositories (in seconds).600 (10 minutes)
POLL_DELAYThe number of seconds between checks of the primary process.30
POLL_SLOW_DELAYThe number of seconds between database consistency checks.1800 (30 minutes)
CHUNK_SIZEThe number of bytes to read from a file at once.4194304 (4 MiB)
SLEEP_MAX_SECONDSExecutions being idle longer than this setting will be unloaded from memory.5