Solution servers#

When you run a solution, SAF Desktop Orchestrator launches an instance of the solution stack which, by default, consists of the following server processes:

Solution API server
Solution UI server
OTel Dashboard (Aspire)
Portal server
PIM Light Server
Additional services

Note

This solution stack, while delivering a solution to desktop users, is highly constrained relative to the long-term vision for SAF. By design, a SAF solution can support any UI technology able to invoke a REST interface.

Startup order#

SAF Desktop Orchestrator starts services sequentially in the following order, running health checks concurrently via a thread pool after all services are launched:

Additional services (if SAF_DEFINITION_PATH is set)
OTel Dashboard (unless --log-to-files)
PIM Light Server (if the solution uses product instances)
Solution API
Solution UI (Dash or Streamlit)
SAF Portal (if --portal)

A service is considered healthy when its health-check endpoint responds successfully. The health-check timeout defaults to 25 seconds and can be overridden with the SAF_DESKTOP_HEALTH_CHECK_TIMEOUT environment variable.

Solution API server#

SAF GLOW Engine’s Solution API server serves a REST API derived from a given solution that exposes a view of project data and enables transaction methods to be executed.

The GLOW API server’s responsibilities include:

Reading and writing project data to/from project storage
Starting method execution
Recording state management information about fields, methods, and product instances

Access Solution API server UIs#

The Solution API server implements a solution-specific REST API that is consumed by the Solution UI server (a Dash UI server by default, and potentially other clients) and exposed in a documented, interactive OpenAPI UI.

Note

The REST API UI is intended for use by solution developers and dev-ops. Solution end-users are not expected to access this UI.

Access the REST API UI#

To access the REST API UI:

After running saf run, review the console output.
Find the line starting with Solution API:.

The URL on this line is address of the Solution API server.
Enter the URL into your browser.

The UI that opens enables invocation of the REST API, providing a mechanism both for testing and diagnosing issues in the running solution and for documenting the API.

Invoke a route in the REST API UI#

To invoke a particular route in the REST API UI:

Navigate to the route of interest.
Expand the route.
Click the Try it out button.

Review the REST API’s OpenAPI specification#

The REST API UI also provides access to the OpenAPI specification for the Solution API server, which is automatically generated by SAF GLOW Engine based on the solution code. To access the OpenAPI specification, use either of these methods:

Enter the Solution’s API server URL in your browser and append /openapi.json to it.
In the REST API UI, click the /openapi.json link under the page header.

Solution UI server#

The Solution UI server is responsible for serving the solution’s UI code to the graphical user interface. SAF supports multiple UI frameworks:

Dash (default)—allows the solution UI to be coded entirely in Python.
Streamlit—an alternative Python-based UI framework, started with saf run --streamlit-ui.
JavaScript-based frameworks (React, Angular)—require a custom service configuration.

The Solution UI server provides the solution UI—a solution-specific user interface that users (both solution developers and solution end users) can access from the Portal UI (as described in the Portal server section that follows).

To access the solution UI, run saf run and a PyWebView window or a browser tab will open it.

You can also find the solution UI URL pointing to a specific project in the console output line starting with Solution UI:. Paste it into your browser to interact with that project.

Tip

On Linux, or when using the --browser flag, the UI opens in your default web browser instead of a PyWebView window.

Projects dashboard#

If the ansys-projects-dashboard package is installed, running saf run --portal serves a Projects dashboard page directly from the Solution UI server, instead of starting the Portal server. This page lets users select or create a project without a separate Portal process being started.

The Projects dashboard URL path defaults to /projects. Set the SAF_DESKTOP_PROJECTS_DASHBOARD_PATH environment variable to use a different path (for example, when the solution UI mounts the dashboard at another route).

You can find the Projects dashboard URL in the console output line starting with Projects dashboard:. Paste it into your browser to interact with solution projects.

Portal server#

Enterprise Feature

Available to Ansys customers and Channel Partners

This feature is available to Ansys customers and Channel Partners. Contact the PyAnsys team to request access.

The SAF Portal server serves the project Portal UI and file management system, which users (both solution developers and solution end users) can access via the Portal server URL.

SAF Portal provides:

Project creation, deletion, and renaming
Project export (as .safx archives)
Favorite projects management

To access Portal UI, run saf run --portal to open it in a PyWebView window or a browser tab.

You can also find the Portal UI URL in the console output line starting with SAF Portal:. Paste it in your browser to interact with the solution projects.

Note

If the ansys-projects-dashboard package is installed, SAF Portal is not started. The orchestrator serves the Projects dashboard page from the Solution UI server instead.

OTel Dashboard (Aspire)#

Enterprise Feature

Available to Ansys customers and Channel Partners

This feature is available to Ansys customers and Channel Partners. Contact the PyAnsys team to request access.

The OTel Dashboard is an observability service based on the .NET Aspire Dashboard that collects and displays OpenTelemetry logs, traces, and metrics emitted by the solution stack.

SAF Desktop Orchestrator starts the OTel Dashboard automatically unless the --log-to-files flag is passed to saf run. In that case, all telemetry is written to log files instead.

Access the OTel Dashboard#

After running saf run, review the console output.
Find the line starting with OTEL Dashboard:.

The URL on this line is the address of the OTel Dashboard.
Enter the URL into your browser.

The dashboard provides three main views:

Structured Logs—aggregated, searchable log entries from all solution services.
Traces—distributed traces showing the execution path of API requests and transactions.
Metrics—runtime metrics (request rates, latencies, error counts) from the solution stack.

Disable the OTel Dashboard#

To disable the OTel Dashboard and write telemetry to local files instead, use one of these methods:

Pass the --log-to-files flag:
```
saf run --log-to-files
```
Set the environment variable:
```
SAF_DESKTOP_LOG_TO_FILES=true
```

When file-based logging is active, log files are stored in the solution’s application data directory.

PIM Light Server#

Enterprise Feature

Available to Ansys customers and Channel Partners

This feature is available to Ansys customers and Channel Partners. Contact the PyAnsys team to request access.

PIM Light Server (Product Instance Management) is a lightweight service for launching and managing instances of Ansys products (Mechanical, Fluent, MAPDL, Geometry, and others) used by the solution. SAF Desktop Orchestrator automatically detects whether the solution requires product instances and launches the service if needed.

PIM Light Server responsibilities:

Launching product instances on demand (via @create_instance transactions)
Managing the lifecycle of running product instances
Providing health-check endpoints for each managed instance
Supporting custom product instance configurations loaded from the solution’s product_instance_configs/ directory

Note

On Linux with a localhost configuration, PIM Light Server uses Unix Domain Sockets (UDS) instead of TCP ports for communication.

Access the PIM Light Server#

After running saf run, review the console output.
Find the line starting with PIM Light Server:.

The URL (or socket path on Linux) on this line identifies the PIM Light Server endpoint.

Tip

PIM Light Server always logs to a file (pim_light_server.log in the solution’s application data directory) regardless of the --log-to-files setting, since it does not support OTLP telemetry.

Additional services#

A solution can define additional custom services to be launched alongside the standard solution stack. SAF Desktop Orchestrator reads a YAML specification file and starts each defined service as a subprocess with health checking.

After running saf run, review the console output.
Find the line starting with the service name in uppercase.

Additional services orchestration#

SAF Desktop Orchestrator manages the extraction and execution of additional service specifications from a .yaml file whose path is configured via the SAF_DEFINITION_PATH setting (for example, via environment variables or a .env file), without requiring a specific directory location.

It performs the following sequence of steps for each additional service specified in the YAML file before starting the GLOW API server:

Determine an available port number.
Instantiate the command line template using the port number.
Execute the instantiated command line.
Perform a health check on the service.
The orchestrator logs a clear message indicating whether the health check was successful or failed.

The orchestrator executes health checks based on the type defined in the YAML file. Upon failure, it logs a failure message and proceeds with orchestrating the remaining services. If the health check succeeds, the orchestrator sets the corresponding SAF_<service name>_PORT environment variables.

Additional services specification format#

The additional services specification format is a YAML file consisting of a list of dictionaries. Each dictionary should have the following keys:

Key	Description
`name`	Unique name for the service (displayed in uppercase in the console output).
`command_line_template`	Command to execute. Use `$PORT` as a placeholder—the orchestrator replaces it with a randomly assigned free port. If the command starts with `python`, the orchestrator substitutes the solution’s Python interpreter automatically.
`health_check`	A dictionary with a `type` key (`HTTP`, `TCP`, or `GRPC`) and an optional `route` key (for HTTP health checks, for example `/health`).

Note

Additional services are started before all other services in the stack. This ensures that dependencies are available when the Solution API and UI start.

Example#

The following example shows the YAML file format for specifying additional services, where ansys.solutions.<solution_name>.additional_services.run_http_service and ansys.solutions.<solution_name>.additional_services.run_grpc_service point to hypothetical Python-based services.

- name: "HTTP_Service"
  command_line_template: "python -m ansys.solutions.<solution_name>.additional_services.run_http_service --port $PORT"
  health_check:
    type: "HTTP"
    route: "/health"

- name: "GRPC_Service"
  command_line_template: "python -m ansys.solutions.<solution_name>.additional_services.run_grpc_service --port $PORT"
  health_check:
    type: "GRPC"
    route: ""