Environment variables

Alongside the command-line interface (SAF CLI) parameters, SAF supports configuration through the use of environment variables. Solutions can be configured using multiple methods; when multiple methods are used, SAF resolves conflicts based on a defined order of precedence.

Configuration methods

You can use either SAF CLI or Solutions Manager to configure the solution using SAFCLI parameters, system environment variables, or an environment file. The following sections describe each method.

CLI parameters

SAF CLI parameters are configuration options passed directly via the command-line interface when launching the solution. You can use these to configure the solution only if you are using SAF CLI.

my_solution api --port 50002 --host 0.0.0.0

Environment variables

System environment variables are set in your shell or system configuration. You can configure the solution with these using either SAF CLI or Solutions Manager.

SAF CLI

Set environment variables using SAF CLI:

Windows (PowerShell)

$env:GLOW_API_PORT = "50001"
$env:GLOW_API_HOST = "0.0.0.0"

Linux/macOS

export GLOW_API_PORT=50001
export GLOW_API_HOST=0.0.0.0

Solutions Manager

Set environment variables using Solutions Manager:

1. Open Visual Studio Code.

2. In the Activity Bar, click the Solutions Manager icon.

3. Expand the Run Solution view.

4. Under Solution environment, click the Configure solution environment.

   The SAF Environment Configuration interface opens in the editor. Environment settings are divided into categories.

5. Find the environment variable you want to set:

   • Use the search bar to search for a specific environment variable.

   • Expand the Filter by category and select a category.

     

6. Modify the configuration parameters as needed:

   • Select or deselect the check box to enable or disable an environment variable.

   • Once an environment variable is enabled, you can modify its value in the Value field, either by selecting from a drop-down list or by entering a value.

   • Click the Enable all or Disable all button to quickly enable or disable all environment variables in the selected category.

7. Click the Save configuration button to save your changes.

   Solutions Manager stores the configuration for each solution. It does not write it to a .env file. When you launch the solution from Solutions Manager, the enabled variables are applied as environment variables. They take precedence over the values from a selected environment file. The saved configuration does not apply when you run the solution with SAF CLI.

8. Close the editor page to exit the SAF Environment Configuration interface.

Environment file

An environment file (.env) contains key-value pairs for configuration variables. By default, the file is loaded from your current working directory. You can configure the solution with this file using either SAF CLI or Solutions Manager.

SAF CLI

Use the --env-file SAF CLI parameter to specify a custom location:

# .env file
GLOW_API_PORT=50000
GLOW_API_HOST=127.0.0.1
GLOW_DEBUG=True

To use a custom environment file:

my_solution api --env-file /path/to/custom.env

When the solution is launched from SAF CLI, it will use the selected environment configuration file.

Solutions Manager

Select an environment file using Solutions Manager:

1. Open Visual Studio Code.

2. In the Activity Bar, click the Solutions Manager icon.

3. Expand the Run Solution view.

4. Under Solution environment, click the button next to the Select an environment file search bar, then browse to and select the .env file you want to use.

   Alternatively, enter the path to the .env file directly in the search bar.

   

When the solution is launched from Solutions Manager, it will use the selected environment configuration file.

Order of precedence

When multiple configuration methods are used, SAF resolves conflicts based on a defined order of precedence. This ensures that the most specific configuration takes priority over more general settings. Configuration values follow a standard precedence hierarchy, from highest to lowest:

1. CLI parameters (highest precedence):

   Command-line arguments override all other configuration sources.

2. Environment variables:

   System environment variables override values from the environment file.

3. Environment file (lowest precedence):

   Values from the environment file (.env) are used if not specified elsewhere.

Order of precedence example

Consider the configuration for the GLOW_API_PORT setting:

• If you define GLOW_API_PORT=50000 in your .env file, the value is used as the base configuration.

• If you set the environment variable before execution, as shown below, the environment variable value (50001) overrides the .env file value:

  Windows (PowerShell)

  $env:GLOW_API_PORT = "50001"
  

  Linux/macOS

  export GLOW_API_PORT=50001
  

• If you provide a SAF CLI parameter during execution, as shown below, the SAFCLI parameter value (50002) takes precedence over both the environment variable and the .env file:

  my_solution api --port 50002
  

See also

Variables that accept a Boolean value accept the values documented in the Types/booleans section of the official Pydantic documentation.

Configuration environment variables

The environment variables used to configure SAF are listed below. The default values are provided for reference, but they may vary based on the solution and deployment context.

Deployment

Deployment environment variables

Variable	Description	Default values
GLOW_DEPLOYMENT	Specifies the deployment where SAF GLOW Engine runs.	Permitted values: Desktop (default) DockerCompose

API server

API server environment variables

Variable	Description	Default values
GLOW_API_HOST	Specifies the host on which the solution API server runs.	127.0.0.1
GLOW_API_PORT	Specifies the port on which the solution API server listens.	5432
GLOW_SOLUTION_DEFINITION	Specifies the solution definition module to use when launching the API application directly with a production server instead of the SAF GLOW Engine CLI. Example: ansys.solutions.my_solution.solution.definition	Auto-discovered (varies by solution)

UI server

UI server environment variables

Variable	Description	Default values
GLOW_UI_HOST	Specifies the host on which the solution UI server runs.	127.0.0.1
GLOW_UI_PORT	Specifies the port on which the solution UI server listens.	5433
GLOW_API_URL	Specifies the URL for the solution API server.	http://127.0.0.1:5432
GLOW_EXTERNAL_API_URL	Specifies the GLOW API server URL that the user machine can access (for example, http://127.0.0.1:5432). Enables the user machine, such as a browser, to access entity-handle content or file references. In desktop deployments, this value is automatically set to GLOW_API_URL. In on-premises deployments, you must set this value because GLOW_API_URL contains a URL accessible only from within the UI container (for example, http://my-solution-api:50000).	The value of GLOW_API_URL
GLOW_PORTAL_URL	Specifies the URL for the Portal server.	None
GLOW_UI_PROJECT_FILES_DIRECTORY	Specifies the absolute path to the project files directory shared with the GLOW API server and accessible to the UI server when the servers run on different systems.	None
GLOW_WS_EVENTS_ADDR	Specifies the GLOW API server URL that the host machine can access (for example, http://127.0.0.1:5432), prefixed with the WebSocket protocol (for example, ws://127.0.0.1:5432 or wss://127.0.0.1:5432). Enables WebSockets created by the Dash client to connect to the WebSocket endpoint in the GLOW API server. In desktop deployments, this value is automatically resolved from GLOW_API_URL. In on-premises deployments, you must set this value because GLOW_API_URL contains a URL accessible only from within the UI container (for example, http://my-solution-api:50000).	Resolved from the GLOW_API_URL: ws://127.0.0.1:5432
GLOW_GRAPHQL_POOL_SIZE	Specifies the number of GraphQL clients available for concurrent use. (DashClient is using GraphQL internally to communicate with the GLOW API. Therefore, a small pool size may impact the performance for a solution used by many concurrent users.)	3
GLOW_UI_MODULE	Specifies the module that contains the UI Dash application. Used to specify the module when launching the UI application directly via a production server instead of GLOW’s CLI. Example: ansys.solutions.my_solution.ui.app

BDM Python API

BDM Python API environment variables

Variable	Description	Default values
GLOW_BDM_GC_DISABLED	Disables garbage collection for the BDM Python API when set to True.	False

Product Instance Manager

Product Instance Manager environment variables

Variable	Description	Default values
GLOW_PRODUCT_INSTANCE_SYSTEM	Specifies the Product Instance Manager system to use.	Permitted values: PIM (default) HPS
GLOW_PRODUCT_INSTANCE_SYSTEM_HOST	Specifies the host on which the Product Instance Manager system runs.	127.0.0.1
GLOW_PRODUCT_INSTANCE_SYSTEM_PORT	Specifies the port on which the Product Instance Manager system listens.	None
GLOW_PIM_SOCKET_PATH	Specifies the path to the UNIX socket file that PIM Light Server uses. Required to connect to PIM Light Server on Linux when GLOW_PRODUCT_INSTANCE_SYSTEM_HOST is set to localhost.	None
GLOW_PRODUCT_HOST	Specifies the host on which the product runs, not the manager system. For HPS, must be set in the environment where the product instance is running, not in the GLOW API environment. For PIM, set it in the GLOW API environment. Overrides the value retrieved automatically from the Product Instance Manager system.	None
GLOW_PRODUCT_BINDING_HOST	Specifies the TCP host or IP address on which the product instance listens for connections. (Not to be confused with the GLOW_PRODUCT_HOST environment variable. GLOW_PRODUCT_HOST is the address used to connect to the product instance from outside, whereas GLOW_PRODUCT_BINDING_HOST is the address where the product instance listens for connections). For HPS, must be set in the environment where the product instance runs (the HPS evaluator or scaler process), not in the GLOW API environment. For PIM, must be set in the environment where PIM runs. Product instances bound to localhost are only reachable from the same system. For more information, see gRPC transport modes.	localhost for secure product configurations 0.0.0.0 for insecure product configurations
GLOW_PRODUCT_INSTANCE_SYSTEM_PROJECT_FILES_DIRECTORY	Specifies the absolute path to the project files directory shared with the GLOW API server and accessible to the product when the Product Instance Manager system runs on a different system.	None
GLOW_PRODUCT_INSTANCE_SYSTEM_PLATFORM	Specifies the platform on which the Product Instance Manager system runs when it is on a different system than the GLOW API server. Permitted values: Windows Linux	None
ANSYS_GRPC_CERTIFICATES	Specifies the path to the directory that stores the gRPC certificates used by PIM Light Server. These certificates are required to connect to PIM Light Server when GLOW_PRODUCT_INSTANCE_SYSTEM_HOST is not localhost.	None
SAF_OPTISLANG_TIMEOUT	Specifies the timeout, in seconds, for requests that manage the OptiSLang server instance.	300
SAF_VISOR_TIMEOUT	Specifies the timeout, in seconds, for requests that manage the Visor server instance.	300

HPS system for job and parametric study submission

HPS system environment variables

Variable	Description	Default values
GLOW_HPS_HOST	Specifies the host on which the HPS system runs.	127.0.0.1
GLOW_HPS_PORT	Specifies the port on which the HPS system listens.	None

Note

If the noted pair of values are not present, then the HPS system for job and parametric will be the one configured to be the product instance manager system if it is a HPS system. See the section on configuring the product instance manager system.

Authentication

Authentication environment variables

Variable	Description	Default values
GLOW_AUTH_ISSUER_URL	Specifies the address of the identity provider, usually Keycloak, for authenticated access to the GLOW API. Example: https://localhost:8443/hps/auth/realms/rep	None
GLOW_AUTH_CLIENT_ID	Specifies the public OAuth 2.0 identifier of the solution API. Example: my-solution-api	None
GLOW_AUTH_DISABLED	Disables API authorization when set to True.	True
GLOW_AUTH_REQUIRED_ROLES	Comma-separated list of client roles. When authorization is enabled, the Solution UI and API servers reject requests whose access token does not grant all of these roles with a 403 Forbidden error, unless the token grants a role listed in GLOW_AUTH_BYPASS_ROLES. Roles are read from the resource_access.<GLOW_AUTH_CLIENT_ID>.roles claim (Keycloak client roles). Example: portal_user,my-solution-role	None (any valid token is accepted)
GLOW_AUTH_BYPASS_ROLES	Comma-separated list of client roles. A token that grants at least one of them is not subject to GLOW_AUTH_REQUIRED_ROLES. Example: portal_admin	None
GLOW_API_KEY	Provides the API key for authenticating local requests to the API server. When set, requests originating from localhost that carry this value in the x-api-key header are authenticated without OIDC validation. Mutually exclusive with GLOW_API_KEY_FILE.	None
GLOW_API_KEY_FILE	Provides the absolute path to a file containing the API key for authenticating local requests to the API server. The path must be absolute and the file must exist. Mutually exclusive with GLOW_API_KEY.	None

HPS authentication

HPS authentication environment variables

Variable	Description	Default values
GLOW_HPS_CLIENT_ID	Specifies the client ID of the HPS system in Keycloak for Keycloak-based authentication. Example: rep-jms-web	rep-jms-web
GLOW_HPS_USERNAME	Specifies the username to log in to the HPS system for username/password authentication. Example: repadmin	""
GLOW_HPS_PASSWORD	Specifies the password to log in to the HPS system for username/password authentication. Example: repadmin	None

Note

If both types of HPS authentication are configured, Keycloak-based has priority.

Solution configuration

Solution configuration environment variables

Variable	Description	Default values
GLOW_OVERWRITE_SOLUTION_CONFIG	Specifies whether to overwrite a persisted solution configuration when it is incompatible with the current solution configuration schema.	None

Directories

Directories environment variables

Variable	Description	Default values
GLOW_PROJECT_FILES_DIRECTORY	Specifies the full operating system path to the directory that stores project files.	%APPDATA%/ansys/glow/SOLUTION_NAME/project_files/

Transaction method child processes

Transaction method child processes environment variables

Variable	Description	Default values
GLOW_METHOD_CLEANUP_CHILD_PROCS	Specifies whether to automatically terminate child processes that a long-running transaction method spawns after the method completes. For more information, see Child process cleanup.	True

Database

Database environment variables

Variable	Description	Default values
GLOW_DATABASE_TYPE	Specifies the type of database to use.	Permitted values: sqlite (default) postgresql
GLOW_DATABASE_LOCATION	Specifies the database location. Can be a file path (for sqlite) or a postgres connection URI of the form postgresql://username:password@host:port	%APPDATA%/ansys/glow/SOLUTION_NAME/glow.db

Data repository

Data repository environment variables

Variable	Description	Default values
GLOW_DATA_REPOSITORY_TYPE	Specifies the type of data repository to use. Permitted values: FileSystem (only for development) Minerva	None
GLOW_DATA_REPOSITORY_UPLOAD_ROOT	Specifies the absolute path in the data repository to which SAF appends a relative upload path when uploading data. If the upload path is an absolute path, the upload path is used.	/Data

Project migration

Project migration environment variables

Variable	Description	Default values
GLOW_ENABLE_AUTOMATIC_PROJECT_MIGRATION	Enables automatic project migration when set to True. This environment variable should only be enabled for development, never in a production environment.	False

Logging

Logging environment variables

Variable	Description	Default values
SAF_DESKTOP_LOG_TO_FILES	Specifies whether to log to files under $APPDATA/ansys/glow/<MySolution>/logs/ and disable the OTel Dashboard. This option is mutually exclusive with OTEL_EXPORTER_OTLP_ENDPOINT. If both environment variables are set, an error is raised. (Note that this sets the SAF GLOW Engine environment variables for log configuration files, overriding any existing value.)	False
GLOW_LOG_CONFIG	Specifies the full operating system path to the YAML logging configuration file for the API service.	None
GLOW_UI_LOG_CONFIG	Specifies the full operating system path to the YAML logging configuration file for the UI service.	None
GLOW_METHOD_LOG_CONFIG	Specifies the full operating system path to the YAML logging configuration file for the Method Runner.	None
GLOW_LOGGING_LEVEL	Specifies the logging level for ansys loggers. Overwrites values from log configurations.	INFO

Telemetry

Telemetry environment variables

Variable	Description	Default values
OTEL_EXPORTER_OTLP_ENDPOINT	Specifies the endpoint for the OTLP exporters for traces, logs, and metrics. Non-URL values enable export to process output.	None

Debugging

Debugging environment variables

Variable	Description	Default values
GLOW_DEBUG	Specifies whether to enable debugging in SAF GLOW Engine.	False
GLOW_API_HOT_RELOAD	Enables API hot reload when set to True. Only works if debug mode is activated.	True
GLOW_API_HOT_RELOAD_MONITORING_DIR	Specifies the directory that SAF GLOW Engine monitors for changes when API hot reload is enabled. For solutions generated with SAF CLI, the default behavior prevents unnecessary API server reloads when only UI files are modified.	If the module location can be resolved, that directory is used; otherwise, the current working directory is used.
GLOW_UI_PYTHON_DEBUGGING	Enables Python debugging in the GLOW UI. Setting it to True implies that debugpy.listen is invoked by the UI server process and the debug functionality of Dash / Flask is disabled.	False
GLOW_DEBUG_API_PORT	Specifies the Python debugger port for the GLOW API service.	5724
GLOW_DEBUG_UI_PORT	Specifies the Python debugger port for the GLOW UI service.	5725

Note

Debugging works only when the solution is executed via SAF GLOW Engine’s CLI, not when it is executed using a production server.

Events

Events environment variables

Variable	Description	Default values
GLOW_WS_EVENT_POLL_INTERVAL	Specifies the interval, in seconds, between iterations of the event transmission loop for a WebSocket connection. Each iteration of the loop queries the database for new events and transmits those events via the websocket. GLOW_WS_EVENT_POLL_INTERVAL is the duration of the pause between iterations of the loop. If a solution raises events in a transaction method and consumes them via web sockets, then: Reducing this value makes a solution UI respond more quickly to those events, but increases the load on the database server and may negatively impact the overall performance of the solution. Increasing this value reduces the load on the database server and may positively impact the overall performance of the solution, but makes the solution UI respond more slowly to the transaction method events.	1.0

Portal API

Portal API environment variables

Variable	Description	Default values
PORTAL_API_VERSION	Specifies the SAF Portal API version to use for communication.	v1

Services

Services environment variables

Variable	Description	Default values
SAF_DESKTOP_HEALTH_CHECK_TIMEOUT	Specifies the maximum time, in seconds, to wait for a service, such as the API, UI, Portal, or PIM, to become healthy after startup.	25 seconds