Configuration & Environment

Configuration & Environment#

As a BaSyx AAS Web UI user
I want to configure the Web UI to connect to my AAS infrastructure
so that I can access and interact with my Asset Administration Shells.

Feature Overview#

The BaSyx AAS Web UI provides flexible configuration options to connect to different AAS infrastructures and customize the application behavior. You can configure the Web UI through the user interface itself, using environment variables, or by pre-configuring infrastructure connections for your users.

Configuring Infrastructure Connections#

The Web UI allows you to connect to one or multiple AAS infrastructures, each potentially using different authentication methods and component endpoints.

Managing Infrastructures Through the UI#

The most user-friendly way to configure backend connections is directly through the Web UI:

Viewing and Selecting Infrastructures#

  1. Click on the gear icon in the top right corner of the Web UI

  2. You’ll see a list of available infrastructure configurations to select from

Infrastructure Selector

Selecting an infrastructure from the dropdown#

From this view, you can:

  • Switch between infrastructures using the dropdown selector

  • View all configured infrastructures in a list

  • Edit existing infrastructures by clicking the edit icon

  • Delete infrastructures you no longer need

  • Add new infrastructures by clicking the “Add Infrastructure” button

Infrastructure List

List of available infrastructures with management actions#

Creating or Editing an Infrastructure#

When creating a new infrastructure or editing an existing one, you’ll configure:

Required Component Endpoints:

  • AAS Registry: For discovering Asset Administration Shell endpoints

  • Submodel Registry: For discovering Submodel endpoints

  • AAS Repository: For accessing AAS data

  • Submodel Repository: For accessing Submodel data

  • Concept Description Repository: For semantic information and concept descriptions

Optional Component Endpoints:

  • AAS Discovery Service: For discovering AAS by asset IDs

Security Configuration: See the Security page for detailed information on authentication and authorization options.

Infrastructure Configuration Form

Form for creating or editing an infrastructure configuration#

Note

Infrastructure configurations created or modified through the UI are stored in your browser’s local storage and will persist across sessions on the same device. However, they are not shared across different browsers or devices.

Multiple Infrastructures Support#

The BaSyx AAS Web UI supports connecting to multiple AAS infrastructures simultaneously. This is particularly useful when:

  • Working with development, testing, and production environments

  • Connecting to different organizational units with separate AAS infrastructures

  • Integrating with partner organizations that use different identity providers

  • Testing against multiple backend versions

Each infrastructure can have:

  • Its own set of component endpoints (registries, repositories, discovery)

  • Different authentication methods (OAuth2, Basic Auth, Bearer Token, or none)

  • Different identity providers (Keycloak, Azure AD, Auth0, or any OAuth2-compatible IDP)

Hint

You can quickly switch between infrastructures using the selector in the settings panel without needing to reconfigure each time.

See also

For details on authentication and authorization for multiple infrastructures, see the Security page.

General Application Configuration#

Beyond infrastructure connections, the Web UI can be configured through environment variables to customize its appearance and behavior.

Branding and Corporate Design#

  • Logo customization: Set custom logos for light and dark themes

  • Color scheme: Configure primary colors for your organization

  • Application theme: Customize the overall look and feel

See also

For details on corporate design customization, see the Corporate Design page.

Feature Flags#

Control which features are available in your deployment:

  • Editor mode: Enable or disable the AAS Editor (ALLOW_EDITING)

  • File uploads: Control whether users can upload AAS environments (ALLOW_UPLOADING)

  • Submodel Viewer: Enable or disable the standalone Submodel Viewer (SM_VIEWER_EDITOR)

  • Logout functionality: Control logout behavior when authentication is enabled (ALLOW_LOGOUT)

Application Behavior#

  • Base path: Deploy the Web UI under a custom URL path (BASE_PATH)

  • Single AAS mode: Configure the UI to display only one specific AAS (SINGLE_AAS)

  • Editor ID prefix: Set a default prefix for AAS IDs created in the editor (EDITOR_ID_PREFIX)

  • Start page: Choose which page is shown when the application first loads (START_PAGE_ROUTE_NAME)

Configurable Start Page#

By default, the Web UI opens the AAS Viewer page when you first navigate to it. You can change this default landing page by setting the START_PAGE_ROUTE_NAME environment variable to the name of any available page, such as:

  • AASViewer (default) – The main AAS Viewer

  • AASEditor – The editor mode of the BaSyx UI (requires ALLOW_EDITING to be enabled)

  • SubmodelViewer – The standalone Submodel Viewer (requires SM_VIEWER_EDITOR to be enabled)

If the configured page is not available (for example, because its feature flag is disabled), the Web UI will automatically fall back to the default start page.

Hint

This is especially useful for deployments where the primary use case is editing Asset Administration Shells rather than viewing them or if the main entry point should be a domain specific view (module).

See also

For a complete list of environment variables and how to set them in Docker, see the Docker Configuration page.

System Administrator Setup#

If you are a system administrator deploying the BaSyx AAS Web UI for multiple users, you can pre-configure infrastructure connections using a YAML configuration file. This allows you to:

  • Define multiple infrastructures that all users can access

  • Configure authentication settings centrally

  • Prevent users from creating or modifying infrastructure configurations

  • Ensure consistent backend connections across your organization

Key Benefits:

  • Centralized management: Configure once, deploy everywhere

  • Security: Pre-configure authentication without exposing credentials to end users

  • Consistency: Ensure all users connect to the correct backends

See also

For detailed instructions on YAML-based infrastructure preconfiguration, including file structure, authentication options, and Docker deployment, see the Infrastructure Configuration section in the developer documentation.

Configuration Precedence#

When multiple configuration sources are present, the Web UI follows this precedence order (highest first):

  1. User modifications in browser (stored in local storage)

  2. Environment variables (set via Docker or system environment)

  3. YAML configuration file (basyx-infra.yml)

  4. Application defaults

This layered approach allows system administrators to provide default configurations while still enabling users to customize settings when permitted.

Configuration Locking#

System administrators can control whether users can modify infrastructure configurations:

  • ENDPOINT_CONFIG_AVAILABLE=true (default): Users can create, edit, and delete infrastructures through the UI

  • ENDPOINT_CONFIG_AVAILABLE=false: Infrastructure configuration is locked; users can only select from pre-configured infrastructures

Hint

Setting ENDPOINT_CONFIG_AVAILABLE=false is recommended for production environments where you want to enforce specific backend connections and prevent users from accidentally misconfiguring the application.

Connecting to Different Environments#

The flexible configuration system makes it easy to work with multiple environments:

Development:

  • Connect to local BaSyx instances running on your development machine

  • Quickly switch between different local setups

  • Test with or without authentication

Testing:

  • Connect to shared test infrastructure

  • Validate configurations before production deployment

  • Test multi-infrastructure scenarios

Production:

  • Use pre-configured YAML files for consistent connections

  • Lock configuration to prevent unauthorized changes

  • Enable authentication and access control

Troubleshooting Connection Issues#

If you’re having trouble connecting to your AAS infrastructure:

  1. Verify Endpoints:

    • Ensure all component URLs are correct and accessible from your browser

    • Check that services are running and responding to requests

    • Test endpoint URLs directly in your browser

  2. Check Network Connectivity:

    • Verify that your browser can reach the backend services

    • Check for firewall rules that might block connections

    • Ensure proper DNS resolution for domain names

  3. Review CORS Settings:

    • Backend services must allow requests from the Web UI’s origin

    • Check CORS headers in the backend service configuration

    • Verify that the Web UI’s URL is whitelisted in backend CORS settings

  4. Inspect Authentication:

    • Verify that authentication tokens or credentials are properly configured

    • Check token expiration and refresh behavior

    • Ensure the identity provider is accessible

  5. Use Browser Developer Tools:

    • Open the browser console (F12) and check for error messages

    • Look for failed network requests in the Network tab

    • Check for CORS errors or authentication failures

See also

For authentication and authorization troubleshooting, see the Security page.

For Docker-specific issues, see the Docker Configuration page.

Next Steps#