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:
- Manually set values in the workpsace configuration directly in the workspace. If none is set:
- Manually set values in the environment variables configuration file (on the server). If none is set:
- 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).
The UI screen
To edit a setting in the UI, click on the dropdown in the manual value column to see the options. Choose the option you want to set, set its value and click "Save".
Editing a setting in the UI
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
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 |