Skip to main content
Version: ACE 5

Service configuration

This page describes configuration options for ACE services. For general information about ACE services see system design.

Designer Web

DEV_API_BASE_URL: <internal-runtime-server-url>/ace
PUBLIC_API_BASE_URL: <public-runtime-server-url>

ACE_DESIGNER_MONGO_URL: <mongo-connection-string>
ACE_DESIGNER_MONGO_DB: <mongo-designer-db>

ACE_UI_URL: <designer-web-public-url>
ACE_OIDC_AUDIENCE: <keycloak-client-id>
ACE_OIDC_ISSUER_BASE_URL: <keycloak-url>/realms/<keycloak-realm>
ACE_SECRET_ENCRYPTION_KEY: <long-random-encryption-secret>
KEYCLOAK_AUTH_SERVER_URL: <keycloak-url>
KEYCLOAK_CLIENT_SECRET: <keycloak-client-secret>
KEYCLOAK_CLIENTID: <keycloak-client-id>
KEYCLOAK_REALM: <keycloak-realm>

Main options

  • DEV_API_BASE_URL (since: 5.29.0) - internal development API base url, including DEV_API_PATH ( i.e. http://ace-runtime-server/ace). Runtime server must be reachable from Designer Web using this URL.
  • PUBLIC_API_BASE_URL (since: 5.29.0) - browser accessible deployed API base url ( i.e. https://ace-runtime-server.sapienspaas.com)

Storage

  • ACE_ENABLE_DESIGNER_DB (since: 5.31.0, default: true (since 24.1.0), removed: 24.3.0) - enables persistent storage of user settings. If enabled, requires Mongo and Authentication to be configured.
  • ACE_DESIGNER_MONGO_URL (required) (since: 5.31.0) - connection string (e.g., mongodb://[host]:[port]).
  • ACE_DESIGNER_MONGO_DB (required) (since: 5.31.0) - Mongo database name (e.g., ace-designer). Different from runtime Mongo DB!
  • ACE_SECRET_ENCRYPTION_KEY (since: 5.31.0) - key used for encrypting/decrypting sensitive Designer user data. The secret should be a complex character combination at least 32 characters long.

Security

  • ACE_UI_AUTH_STRATEGY (since: 5.29.0, default: keycloak) - Authentication strategy used for Designer Web. Currently supported authentication strategies are keycloak and oidc.
  • ACE_UI_URL (since: 5.29.0) - Public URL of Designer Web, used for redirect from identity provider.
  • ACE_OIDC_SIGNING_ALG (since: 24.1.0, default: RS256) - The configured signing algorithm. Can be either RS256 or HS256. Algorithms using SHA384 and SHA512 are also configurable.
  • ACE_OIDC_SIGNING_SECRET (since: 24.1.0) - The configured secret. Only required if using symmetric HS* algorithm.
  • ACE_DISABLE_TOKEN_VALIDATION (since: 24.1.0) - Skips token validation for development. Set this to true in RUNTIME_MODE=production to make API_SPEC_VIEW_PATH endpoint public.

Authentication

Keycloak

Settings used in case ACE_UI_AUTH_STRATEGY is keycloak.

  • KEYCLOAK_AUTH_SERVER_URL (since: 5.29.0) - URL of Keycloak.
  • KEYCLOAK_CLIENTID (since: 5.29.0) - ACE app client ID in Keycloak.
  • KEYCLOAK_REALM (since: 5.29.0) - ACE realm in Keycloak.
  • KEYCLOAK_CLIENT_SECRET (since: 5.29.0) - ACE app client secret in Keycloak.
  • KEYCLOAK_DESIGNER_ACCESS_ROLE (since: 5.29.0) - Role defined in keycloak to allow access to Designer. This is optional config, if not defined then any Keycloak user can access ACE Designer.
  • ACE_OIDC_ISSUER_BASE_URL (since: 24.1.0) - Realm URL of Keycloak (e.g. http://keycloak/realms/ACE if KEYCLOAK_AUTH_SERVER_URL=http://keycloak and KEYLCOAK_REALM=ACE)
  • ACE_OIDC_AUDIENCE (since: 24.1.0) - Expected audience of keycloak issued access token. Configurable from keycloak. Can be set to the same value as KEYCLOAK_CLIENTID. This is optional configuration, but highly recommended to configure it for security purpoess.

For migration guide to version 24.1.0, see keycloak migration guide.

For detailed documentation on how to set up keycloak See keycloak setup guide

OpenID Connect

Settings used in case ACE_UI_AUTH_STRATEGY is oidc.

  • ACE_OIDC_ISSUER_BASE_URL (since: 5.33.0) - Base URL of the OIDC provider. Issuer base URL should match 'isuser' field in <ACE_OIDC_ISSUER_BASE_URL>/.well-known/openid-configuration endpoint. It will also be used to validate token iss claim.
  • ACE_OIDC_CLIENT_ID (since: 5.33.0) - The client ID from provider.
  • ACE_OIDC_CLIENT_SECRET (since: 24.1.0) - The client secret from provider.
  • ACE_OIDC_AUDIENCE (since: 24.1.0) - Configured audience from provider. It will be used to validate token aud claim.

SaaS integration

  • ACE_ENABLE_MULTI_TENANT (default: false) - If set to true, then enables multi-tenant mode.
  • ACE_SAAS_SECRET_SERVICE_ENABLED (default: false) - If set to true, environment variables will be loaded from SaaS configuration service.
  • ACE_SAAS_SECRET_SERVICE_URL (default: <empty>) - SaaS configuration service URL.
  • ACE_SERVICE_NAME (default: ace-designer-backend) - Used to retrieve values from configuration service.
  • TENANT_ID_KEY (default: <empty>) - JWT token key that contains tenant ID.
  • ACE_SAAS_USER_SECRET_SERVICE_ENABLED (default: false) - If set to true, then uses SaaS configuration service to store sensitive user data. Requires that ACE_SAAS_SECRET_SERVICE_ENABLED is true.

Miscellaneous

  • LOG_LEVEL (default: info) - service log verbosity level. Possible values error, warn, info, http, verbose, debug, silly.
  • ACE_REQUEST_BODY_SIZE_LIMIT (since: 24.1.0, default: 50mb) - Sets limit for maximum request body size.
  • ACE_ALLOW_STATIC_FILE_SERVING (since: 24.1.0, default: true) - If set to false, designer backend won't serve static content (used if there is a need to serve static web content via CDN)
  • ACE_LOG_EXCHANGE(since: 24.2.0, default: <empty>) - If set to true, logs request(url, method, body) and response(statusCode, body) related data at info level.
  • ACE_MULTI_FOLDER_ENABLED (since: 25.1.0, default: true) - If set to true, enables multi-folder feature.

Removed

  • JWT_SECRET (removed: 24.1.0) - Secret to encode JWT tokens. The secret should be a complex character combination at least 32 characters long.
  • JWT_EXPIRE (removed: 24.1.0) - JWT token expiration period in minutes. Timeout is now configurable in Keycloak or other OIDC provider
  • REACT_APP_DEV_API_BASE_URL (removed: 5.29.0) - Development apis base url, including DEV_API_PATH ( i.e. https://ace-runtime.mydomain.com/ace)
  • REACT_APP_GIT_CORS_PROXY (removed: 5.28.0) - Url of the git proxy server ( i.e. https://ace-designer-proxy.com).
  • REACT_APP_AUTH_STRATEGY (removed: 5.29.0) - If this parameter is set designer web application will attempt to authenticate with Identity Provider. Currently supported authentication strategy is keycloak.
  • ACE_API_SPLIT_ENABLED (since: 24.5.0, default: true (since 24.6.0), removed: 25.1.0) - If set to true, enables split API file feature.

Runtime server

Production environment

RUNTIME_MODE: production

# Mongo based deployment (default)
ACE_RUNTIME_MONGO_DB: <mongo-designer-db>
ACE_RUNTIME_MONGO_URL: <mongo-connection-string>

# OR File based deployment
ACE_WORKSPACE_STORAGE: "file"

# Redis cache - URL or individual parameters
REDIS_CACHE_URL: <redis-connection-string-for-data-cache>

# Configure only if scheduler is used
SCHEDULER_ENABLED: "true"
# URL or individual parameters
SCHEDULER_REDIS_URL: <redis-connection-string-for-scheduler>

Development environment

RUNTIME_MODE: development
ACE_OIDC_AUDIENCE: <keycloak-client-id>
ACE_OIDC_ISSUER_BASE_URL: <keycloak-url>/realms/<keycloak-realm>

# Mongo based deployment (default)
ACE_RUNTIME_MONGO_DB: <mongo-designer-db>
ACE_RUNTIME_MONGO_URL: <mongo-connection-string>

# OR File based deployment
ACE_WORKSPACE_STORAGE: "file"

# Redis cache - URL or individual parameters
REDIS_CACHE_URL: <redis-connection-string-for-data-cache>

# CORS configuration - either built-in config or ingress/proxy
CORS_ALLOWED_ORIGINS: <designer-web-public-url>

# Configure only if scheduler is used
SCHEDULER_ENABLED: "true"
# URL or individual parameters
SCHEDULER_REDIS_URL: <redis-connection-string-for-scheduler>

Main options

  • RUNTIME_MODE (default: production) - Server runtime mode. Possible values production, development. In development mode server exposes development APIs which are used for Designer Web test features. For detailed info see system design overview.

Workspace storage

  • ACE_WORKSPACE_STORAGE (since: 5.31.0, default: mongo (since 24.3.0)) - Workspace repository storage. Possible values file, mongo. If file, then workspace is read from WORKSPACE_DIR. If mongo, then Mongo database must be configured.
  • ACE_RUNTIME_MONGO_URL (since: 5.31.0) - Mongo connection string (e.g., mongodb://[host]:[port]).
  • ACE_RUNTIME_MONGO_DB (since: 5.31.0) - Mongo database name (e.g., ace-runtime).
  • WORKSPACE_DIR (default: /var/workspace) - directory which contains deployed workspace

Development mode

  • DEPLOYMENT_SERVICE_URL (since: 5.31.0) - internal deployment service url (i.e. http://ace-deployment-server), used if ACE_WORKSPACE_STORAGE is mongo.
  • DEV_API_PATH (default: /ace) - Development API prefix.
  • DEV_CLEANUP_STRATEGY (default: <empty>) - If set to SLIDING_DEPLOYMENT_AGE dev workspace will be cleaned up if workspace hasn't been deployed more than DEV_CLEANUP_EXPIRATION_HOURS hours
  • DEV_CLEANUP_EXPIRATION_HOURS (default: 24) - The amount of hours server will wait to clean up dev workspace
  • DEV_WORKSPACE_DIR (default: /var/dev_workspace) - directory which contains deployed development workspaces

Scheduler

  • SCHEDULER_ENABLED (default: false) - if true, then enables scheduled job worker
  • SCHEDULER_REDIS_PREFIX (default: bull) - Prefix to use for scheduler keys. Must change it if Redis instance is shared between environments. If Redis cluster is used (e.g., AWS ElastiCache), then it's necessary to put curly braces around prefix (e.g., {bull}). See details here

Connection can be specified either using connection string or through individual parameters.

  • Connection string
    • SCHEDULER_REDIS_URL - Fully qualified URL with redis:// or secure rediss:// protocol.
  • Connection parameters
    • SCHEDULER_REDIS_HOST - Redis host for scheduler
    • SCHEDULER_REDIS_PORT - Redis port
    • SCHEDULER_REDIS_USER - Redis username
    • SCHEDULER_REDIS_PASSWORD - Redis password/authentication key
    • SCHEDULER_REDIS_TLS_ENABLED - Flag, set to true if redis is tls configured.
    • SCHEDULER_REDIS_TLS_KEY - TLS private key
    • SCHEDULER_REDIS_TLS_CERT - TLS cert
    • SCHEDULER_REDIS_TLS_CA - TLS CA

Cache

Uses redis internally.

  • REDIS_KEY_PREFIX (default: ace-cache) - prefix for redis cache keys
  • REDIS_CACHE_DISABLE_KEY_HASH (since: 24.6.0) - option to disable key hashing and use legacy key generation (note: It is not recommended to enable this flag as legacy keys are larger in size and this impacts redis performance and can cause issues with AWS ElastiCache)
  • REDIS_DEFAULT_TTL_MIN (default: 1440 (24h)) - Redis cache time to live before refreshing the result for an item (default TTL value if not specified for step)

Connection can be specified either using connection string or through individual parameters.

  • Connection string
    • REDIS_CACHE_URL - Redis connection string, should start with redis:// or rediss://
  • Connection parameters
    • REDIS_CACHE_HOST - Redis host for data cache
    • REDIS_CACHE_PORT - Redis port
    • REDIS_CACHE_KEY - Redis authentication key
    • REDIS_CACHE_USER - Redis username
    • REDIS_CACHE_TLS_ENABLED - Flag, set to true if redis is tls configured.
    • REDIS_CACHE_TLS_KEY - TLS private key
    • REDIS_CACHE_TLS_CERT - TLS cert
    • REDIS_CACHE_TLS_CA - TLS CA
    • REDIS_CACHE_DB - redis database number

Steps

  • ENABLE_LEGACY_CATCH_BEHAVIOR (default: false, since 24.8.0) - If set to true, then enables legacy catch behavior.
  • RESPONSE_TIMEOUT - default value for rest step response timeout setting, see https://ladjs.github.io/superagent/#timeouts for the explanation
  • DEADLINE_TIMEOUT - default value for rest step deadline timeout setting, see https://ladjs.github.io/superagent/#timeouts for the explanation
  • DISABLE_JS_CODE_STEP (default: false) - If true, prevents execution of JS Code step (deprecated). Can be set as an additional safety measure if JS Code step is not required.
  • DISABLE_CODE_IVM_STEP (default: false) - If true, prevents execution of JS Code step. Can be set as an additional safety measure if JS Code step is not required.
  • REST_STEP_MAX_FILE_SIZE_MB (default: 50) - Specifies the max file size that REST Step will allow downloads for ( in megabytes).

Development mode security

  • ALLOWED_REPOSITORIES - Repositories which are allowed to be deployed separated by ','. If set, only these repositories can be deployed.
  • KEYCLOAK_DESIGNER_ACCESS_ROLE - Role defined in keycloak to allow access to Designer. This is optional config, If not defined then any Keycloak user can access ACE Designer.
  • ACE_DEV_API_AUTH_DISABLE (default: false) - If true then development API authorization is turned off. Use this only if development APIs are protected by other means, like sidecar.
  • ACE_OIDC_ISSUER_BASE_URL (since: 24.1.0) - Configure with same value as designer web.
  • ACE_OIDC_AUDIENCE (since: 24.1.0) - Configure with same value as designer web.
  • ACE_OIDC_SIGNING_ALG (since: 24.1.0, default: RS256) - Configure with same value as designer web.
  • ACE_OIDC_SIGNING_SECRET (since: 24.1.0) - Configure with same value as designer web.

For migration guide to version 24.1.0, see keycloak migration guide.

For detailed documentation on how to set up keycloak See keycloak setup guide

TLS

It is possible to enable TLS for the runtime server. Variables are read on server startup and further changes are ignored.

SaaS integration

  • ACE_ENABLE_MULTI_TENANT (default: false) - If set to true, then enables multi-tenant mode.
  • ACE_SAAS_SECRET_SERVICE_ENABLED (default: false) - If set to true, environment variables will be loaded from SaaS configuration service.
  • ACE_SAAS_SECRET_SERVICE_URL (default: <empty>) - SaaS configuration service URL.
  • ACE_SERVICE_NAME (default: ace-runtime-server) - Used to retrieve values from configuration service.
  • TENANT_ID_KEY (default: <empty>) - JWT token key that contains tenant ID.

Miscellaneous

  • ACE_LOG_CORRELATION_ID (default: x-request-id) - Header name to retrieve correlation id from. Also used as header name for correlation header forwarding. Header value is added in logs (requestId field) and forwarded in network requests.
  • ACE_DISABLE_CORRELATION_HEADER_FORWARDING (default: <empty>) - if set to true, disables correlation header forwarding in network steps.
  • ACE_API_DOCS_ENABLED (default: false, since: 24.4.0) - If set to true, then enables public APIs documentation endpoint /api-docs.
  • ACE_FILE_REF_DOC_LIMIT_MB (default: 5) - File size limit in MB for reading file content using file reference step.
  • ENABLED_EVAL_EXTENSIONS (default: ivm,jsonata) - Enabled expression evaluators. Possible values ivm, jsonata, eval. By default deprecated evaluator eval is disabled.
  • DEFAULT_EVAL_EXTENSION(default: ivm) - Default expression evaluator to be used when one is not specified in input.
  • IVM_TIMEOUT (default: 1000) - Specific to ivm eval extension. Execution timeout in ms.
  • ACE_IVM_MEMORY_LIMIT_MB (since: 5.35.0, default: 128) - Specific to ivm eval extension. Sets max memory limit that can be used by ivm per request.
  • LOG_LEVEL (default: info) - service log verbosity level. Possible values error, warn, info, http, verbose, debug, silly.
  • FULL_DATA_LOGGING (default: false) - If enabled logs additional information like request/response bodies. Note that additional data may contain sensitive information like personally identifiable information or secrets.
  • CACHE_FLOWS(default: true) - If true then caches workflow data in memory to improve performance. It's not necessary to set this property explicitly, unless doing troubleshooting. If it is set to false, then ACE will have serious performance degradation. This is internal ACE cache, and is not related to data (response) caching in ACE.
  • CORS_ENABLED (default: true) - If true, then add CORS headers from runtime server. Sent headers are:
    • access-control-allow-origin: *
    • access-control-allow-methods: GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS
    • access-control-allow-headers: <echo request headers>
  • CORS_ALLOWED_ORIGINS - Comma separated CORS origins (access-control-allow-origin). Used if CORS_ENABLED is true.
  • ACE_USE_MEMORY_STORAGE (since: 5.33.0, default: <empty>) - If set to true, ACE is not going to use file system (file upload/download, file references) and will store files in memory.
  • ACE_REQUEST_BODY_SIZE_LIMIT (since: 24.1.0, default: 50mb) - Sets limit for maximum request body size.
  • ACE_LOG_EXCHANGE(since: 24.2.0, default: <empty>) - If set to true, logs request(url, method, body) and response(statusCode, body) related data at info level.
  • ACE_MULTI_FOLDER_ENABLED (since: 25.1.0, default: true) - If set to true, enables multi-folder feature.

Removed

  • DYNAMIC_API_AUTH_STRATEGY (removed: 24.4.0) - Dynamic APIs security strategy for "Secured" APIs. Currently supported value is bearer (Keycloak).
  • DYNAMIC_API_KEYCLOAK_REALM (removed: 24.4.0) - ACE ream in Keycloak.
  • DYNAMIC_API_KEYCLOAK_AUTH_SERVER_URL (removed: 24.4.0) - URL of Keycloak.
  • ENABLE_API_SPEC_VIEW (removed: 24.4.0) - Enables APIs specification endpoint that is used by Swagger View. By default true in development mode. This endpoint is protected and requires authorization. To make endpoint accessible publicly set ACE_DISABLE_TOKEN_VALIDATION=true when deploying ACE with RUNTIME_MODE=production.
  • API_SPEC_VIEW_PATH (removed: 24.4.0) - APIs specification URL path.
  • JWT_SECRET (removed: 24.1.0) - Secret to encode JWT tokens. The secret should be a complex character combination at least 32 characters long.
  • JWT_EXPIRE (removed: 5.29.0) - JWT token expiration period in minutes. Timeout is now configurable in Keycloak or other OIDC provider.
  • ACE_UI_AUTH_STRATEGY (removed: 5.29.0) - If set development server APIs will require authentication. Currently supported authentication strategy is keycloak.
  • KEYCLOAK_CLIENTID (removed: 5.29.0) - ACE app client ID in Keycloak.
  • KEYCLOAK_REALM (removed: 5.29.0) - ACE realm in Keycloak.
  • KEYCLOAK_CLIENT_SECRET (removed: 5.29.0) - ACE app client secret in Keycloak.
  • KEYCLOAK_AUTH_SERVER_URL (removed: 5.29.0) - URL of Keycloak.
  • ACE_UI_URL (removed: 5.29.0) - Public URL of Designer Web, used for redirect from Keycloak.
  • SELF_EXTERNAL_URL (removed: 5.29.0) - Public URL of Designer Server, used for redirect from Keycloak.
  • ENABLE_EVAL_OPTIMIZATION (removed: 5.23.0, default: false) - If set to true, then improves the performance by running optimized logic for object evaluation
  • DYNAMIC_API_RESULT_PROP (removed: 5.22.0) - Node name in document returned by Flow that is returned as the output of the Flow, by default result.
  • ACE_API_SPLIT_ENABLED (since: 24.5.0, default: true (since 24.6.0), removed: 25.1.0) - If set to true, enables split API file feature.

CORS configuration for development

legacy

Starting from ACE version 5.28.0 development APIs are served through Designer Web service and this configuration is not relevant.

In order to use development APIs for flow and API testing it is required that designer server has configured CORS headers. By default, designer server has CORS_ENABLED, which ensures correct settings, but if CORS headers are overwritten, then it's necessary to ensure that:

  • access-control-allow-origin includes Designer Web host. * also works if that's acceptable.
  • access-control-allow-methods includes POST and all methods used by APIs, typically GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS
  • access-control-allow-headers includes following headers: ace-repository, ace-branch, ace-commit, ace-token, ace-username, ace-authorization, content-type. * also works if that's acceptable.

Deployment server

If using mongo based deployment

ACE_RUNTIME_MONGO_DB: <mongo-designer-db>
ACE_RUNTIME_MONGO_URL: <mongo-connection-string>

# Redis cache - URL or individual parameters
REDIS_CACHE_URL: <redis-connection-string-for-data-cache>

# Configure only if scheduler is used - URL or individual parameters
SCHEDULER_REDIS_URL: <redis-connection-string-for-scheduler>

Workspace storage

Mongo connection details must match with runtime server connection details.

  • ACE_RUNTIME_MONGO_URL - Mongo connection string (e.g., mongodb://[host]:[port]).
  • ACE_RUNTIME_MONGO_DB - Mongo database name (e.g., ace-runtime).

Cache

  • REDIS_KEY_PREFIX - prefix for redis cache keys (default: ace-cache).

Connection can be specified either using connection string or through individual parameters.

  • Connection string
    • REDIS_CACHE_URL - Redis connection string, should start with redis:// or rediss://
  • Connection parameters
    • REDIS_CACHE_HOST - Redis host for data cache
    • REDIS_CACHE_PORT - Redis port
    • REDIS_CACHE_KEY - Redis authentication key
    • REDIS_CACHE_USER - Redis username
    • REDIS_CACHE_TLS_ENABLED - Flag, set to true if redis is tls configured.
    • REDIS_CACHE_TLS_KEY - TLS private key
    • REDIS_CACHE_TLS_CERT - TLS cert
    • REDIS_CACHE_TLS_CA - TLS CA
    • REDIS_CACHE_DB - redis database number

Scheduler

  • SCHEDULER_REDIS_PREFIX (default: bull) - Prefix to use for scheduler keys. Must change it if Redis instance is shared between environments. If Redis cluster is used (e.g., AWS ElastiCache), then it's necessary to put curly braces around prefix (e.g., {bull}). See details here

Connection can be specified either using connection string or through individual parameters.

  • Connection string
    • SCHEDULER_REDIS_URL - Fully qualified URL with redis:// or secure rediss:// protocol.
  • Connection parameters
    • SCHEDULER_REDIS_HOST - Redis host for scheduler
    • SCHEDULER_REDIS_PORT - Redis port
    • SCHEDULER_REDIS_USER - Redis username
    • SCHEDULER_REDIS_PASSWORD - Redis password/authentication key
    • SCHEDULER_REDIS_TLS_ENABLED - Flag, set to true if redis is tls configured.
    • SCHEDULER_REDIS_TLS_KEY - TLS private key
    • SCHEDULER_REDIS_TLS_CERT - TLS cert
    • SCHEDULER_REDIS_TLS_CA - TLS CA

Miscellaneous

  • LOG_LEVEL (default: info) - service log verbosity level. Possible values error, warn, info, http, verbose, debug, silly.
  • ACE_REQUEST_BODY_SIZE_LIMIT (since: 24.1.0, default: 50mb) - Sets limit for maximum request body size.
  • ACE_LOG_EXCHANGE(since: 24.2.0, default: <empty>) - If set to true, logs request(url, method, body) and response(statusCode, body) related data at info level.
  • ACE_MULTI_FOLDER_ENABLED (since: 25.1.0, default: true) - If set to true, enables multi-folder feature.

Removed

  • ACE_API_SPLIT_ENABLED (since: 24.5.0, default: true (since 24.6.0), removed: 25.1.0) - If set to true, enables split API file feature.