Configuration & Environment

Configuration & Environment#

This section explains how the BaSyx AAS Web UI is configured in development and production environments. It describes the different configuration layers, their precedence, and how they interact at runtime.

Understanding this configuration model is essential when running the UI in complex infrastructures, multi-environment setups, or secured deployments.

Configuration Layers and Precedence#

The Web UI supports multiple configuration mechanisms that are intentionally layered to maintain backward compatibility and runtime flexibility.

The effective precedence (highest first) is:

  1. Infrastructure configuration stored in localStorage (only if ENDPOINT_CONFIG_AVAILABLE=true)

  2. Legacy infrastructure environment variables (kept for backward compatibility)

  3. Environment variables

    • env.development in development mode

    • Docker-injected environment variables in production

  4. public/config/basyx-infra.yml

  5. Application defaults

Note

Legacy infrastructure-related environment variables intentionally have higher precedence than the YAML configuration to avoid breaking existing deployments.

Infrastructure Configuration#

The primary and recommended way to configure backend infrastructures is the YAML file:

public/config/basyx-infra.yml

This file defines:

  • One or more AAS infrastructures

  • Component endpoints (registry, repository, discovery, etc.)

  • Authentication configuration per infrastructure

Characteristics#

  • The file name is currently fixed and cannot be changed

  • It is loaded at runtime, not build time

  • It supports multi-infrastructure setups

Warning

Changes made via the UI infrastructure editor are stored in localStorage only and are not written back to basyx-infra.yml.

Environment Variables#

Environment variables are used for build-agnostic configuration such as branding, feature flags, authentication toggles, and (for legacy reasons) infrastructure endpoints.

Development Mode#

In development mode:

  • Configuration is read from env.development

  • Variables must be prefixed with VITE_

  • Values are injected by Vite at runtime

Production Mode#

In production:

  • Environment variables are injected via Docker

  • Variables are not prefixed with VITE_

  • The entrypoint.sh script replaces placeholders at container startup

Hint

The same configuration keys are used in development and production. Only the prefix handling differs.

Supported Environment Variables#

General#

  • BASE – application base path (runtime replaced) (only available in dev mode!, use BASE_PATH in production)

  • VITE_LOGO_LIGHT_PATH

  • VITE_LOGO_DARK_PATH

  • VITE_PRIMARY_LIGHT_COLOR

  • VITE_PRIMARY_DARK_COLOR

Infrastructure (Legacy – Deprecated)#

The following variables are deprecated in favor of basyx-infra.yml, but still supported:

  • VITE_AAS_DISCOVERY_PATH

  • VITE_AAS_REGISTRY_PATH

  • VITE_SUBMODEL_REGISTRY_PATH

  • VITE_AAS_REPO_PATH

  • VITE_SUBMODEL_REPO_PATH

  • VITE_CD_REPO_PATH

Warning

These variables remain available to avoid breaking existing deployments but should not be used for new setups.

Authentication & Security#

  • VITE_KEYCLOAK_ACTIVE (deprecated; automatically set in production if Keycloak variables are present)

  • VITE_KEYCLOAK_URL (deprecated; use basyx-infra.yml instead)

  • VITE_KEYCLOAK_REALM (deprecated; use basyx-infra.yml instead)

  • VITE_KEYCLOAK_CLIENT_ID (deprecated; use basyx-infra.yml instead)

  • VITE_KEYCLOAK_FEATURE_CONTROL

  • VITE_KEYCLOAK_FEATURE_CONTROL_ROLE_PREFIX

  • VITE_OIDC_ACTIVE (deprecated; automatically set in production if OIDC variables are present)

  • VITE_OIDC_URL (deprecated; use basyx-infra.yml instead)

  • VITE_OIDC_SCOPE (deprecated; use basyx-infra.yml instead)

  • VITE_OIDC_CLIENT_ID (deprecated; use basyx-infra.yml instead)

  • VITE_PRECONFIGURED_AUTH (deprecated; use basyx-infra.yml instead with client_Credentials flow)

  • VITE_PRECONFIGURED_AUTH_CLIENT_SECRET (deprecated; use basyx-infra.yml instead with client_Credentials flow)

  • VITE_BASIC_AUTH_ACTIVE (deprecated; automatically set in production if basic auth variables are present)

  • VITE_BASIC_AUTH_USERNAME (deprecated; use basyx-infra.yml instead)

  • VITE_BASIC_AUTH_PASSWORD (deprecated; use basyx-infra.yml instead)

  • VITE_AUTHORIZATION_HEADER_PREFIX (deprecated; use basyx-infra.yml instead)

  • VITE_AUTHORIZATION_HEADER_DESCRIPTION_ENDPOINT_EXEMPTION

Danger

Never commit OAuth client secrets or credentials into version control. Frontend applications expose configuration to end users and secrets can be extracted easily.

Feature Flags & Behavior#

  • VITE_ENDPOINT_CONFIG_AVAILABLE

  • VITE_SINGLE_AAS

  • VITE_SINGLE_AAS_REDIRECT

  • VITE_SM_VIEWER_EDITOR

  • VITE_ALLOW_EDITING

  • VITE_ALLOW_UPLOADING

  • VITE_ALLOW_LOGOUT

  • VITE_START_PAGE_ROUTE_NAME

Miscellaneous#

  • VITE_INFLUXDB_TOKEN

  • VITE_EDITOR_ID_PREFIX

Base Path Configuration#

The Web UI supports deployment under a custom base path (e.g. /basyx-ui/).

  • Controlled via the BASE environment variable

  • Replaced at runtime by entrypoint.sh in production (BASE_PATH)

This affects:

  • Routing

  • Static asset resolution

  • Mounted configuration files (e.g. basyx-infra.yml, logos)

Hint

When deploying under a non-root base path, all mounted static files must be available under the same base path.

Start Page Configuration#

The Web UI supports configuring which page is shown when the application is first loaded.

  • Controlled via the VITE_START_PAGE_ROUTE_NAME environment variable (START_PAGE_ROUTE_NAME in production)

  • The value must be a valid named route defined in the application router (e.g. AASViewer, AASEditor, SubmodelViewer)

  • Validated at startup: the configured route must exist, its associated feature flag must be enabled, and the corresponding module must be visible

  • If the value is invalid or the route is not accessible, the application falls back to the default start page

  • After authentication, the application automatically redirects to the configured start page

Note

The main viewer route has moved from / to /aasviewer. Navigating to / now shows a 404 page unless an explicit start page redirect is configured. The default start page route is AASViewer.

Behavior#

  • On initial load: the root path (/) redirects to the resolved start page route

  • After authentication: the user is redirected to the configured start page

  • Invalid route names: fall back to the application default

  • Feature flag gating: if the target route’s feature flag is disabled, the fallback is used

Infrastructure Editing via UI#

If enabled, the Web UI allows users to edit infrastructure configurations directly.

  • Controlled by ENDPOINT_CONFIG_AVAILABLE=true

  • Enabled by default in development and production

Edits:

  • Are stored in localStorage

  • Override YAML and environment configuration

  • Are local to the browser instance

Note

Infrastructure editing does not modify backend configuration or YAML files.

Docker and Runtime Injection#

In containerized deployments:

  • Configuration is injected via environment variables

  • entrypoint.sh performs:

    • Base path replacement

    • Environment variable injection into Pinia stores

    • Configuration file placement

This allows the same image to be reused across environments without rebuilding.

Development vs Production Summary#

Aspect

Development

Production

Env vars

env.development (VITE_*)

Docker env vars

Infra config

basyx-infra.yml

basyx-infra.yml

Overrides

localStorage

localStorage

Base path

runtime

runtime

Common Pitfalls#

  • Committing local changes to basyx-infra.yml

  • Assuming UI-edited infrastructure is persisted globally

  • Using OAuth client secrets in frontend configuration

  • Forgetting to adjust mounted paths when changing BASE/BASE_PATH

  • Setting START_PAGE_ROUTE_NAME to a route whose feature flag is disabled (the app will fall back silently)

  • Using a path (e.g. /aasviewer) instead of a named route (e.g. AASViewer) for START_PAGE_ROUTE_NAME

YAML Infrastructure Configuration#

The primary and recommended method for configuring infrastructure connections is through the basyx-infra.yml file. This section provides comprehensive technical details for system administrators and developers.

File Locations#

  • Development Mode: /aas-web-ui/public/config/basyx-infra.yml

  • Production Mode (Docker): Mount to /basyx-infra.yml in the container

The configuration file is copied to the application’s config directory at container startup and parsed client-side by the browser using the js-yaml library.

Basic Structure#

infrastructures:
  default: <default-infra-key>

  <infra-key>:
    name: <infrastructure-name>
    components:
      aasDiscovery:
        baseUrl: "<url>"
      aasRegistry:
        baseUrl: "<url>"
        hasDiscoveryIntegration: <true|false>  # optional
      submodelRegistry:
        baseUrl: "<url>"
      aasRepository:
        baseUrl: "<url>"
        hasRegistryIntegration: <true|false>   # optional
      submodelRepository:
        baseUrl: "<url>"
        hasRegistryIntegration: <true|false>   # optional
      conceptDescriptionRepository:
        baseUrl: "<url>"
    security:
      type: <auth-type>
      config:
        # Authentication-specific configuration

Configuration Examples#

No Authentication#

infrastructures:
  default: local

  local:
    name: Local Development Environment
    components:
      aasDiscovery:
        baseUrl: "http://localhost:9084"
      aasRegistry:
        baseUrl: "http://localhost:9082"
        hasDiscoveryIntegration: true
      submodelRegistry:
        baseUrl: "http://localhost:9083"
      aasRepository:
        baseUrl: "http://localhost:9081"
        hasRegistryIntegration: true
      submodelRepository:
        baseUrl: "http://localhost:9081"
        hasRegistryIntegration: true
      conceptDescriptionRepository:
        baseUrl: "http://localhost:9081"
    security:
      type: none

OAuth2 Authorization Code Flow#

infrastructures:
  default: production

  production:
    name: Production Environment
    components:
      aasRegistry:
        baseUrl: "https://aasreg.basyx.example.com"
      submodelRegistry:
        baseUrl: "https://smreg.basyx.example.com"
      aasRepository:
        baseUrl: "https://aasenv.basyx.example.com"
      submodelRepository:
        baseUrl: "https://aasenv.basyx.example.com"
      conceptDescriptionRepository:
        baseUrl: "https://aasenv.basyx.example.com"
      aasDiscovery:
        baseUrl: "https://discovery.basyx.example.com"
    security:
      type: oauth2
      config:
        flow: auth_code
        issuer: "https://keycloak.example.com/auth/realms/BaSyx"
        clientId: "basyx-web-ui"
        scope: "openid profile email"

OAuth2 Client Credentials Flow#

Danger

Client Credentials Flow exposes the client secret in the browser. Only use for internal/trusted environments.

infrastructures:
  default: service

  service:
    name: Service Account Environment
    components:
      aasRegistry:
        baseUrl: "https://aasreg.internal.basyx.com"
      submodelRegistry:
        baseUrl: "https://smreg.internal.basyx.com"
      aasRepository:
        baseUrl: "https://aasenv.internal.basyx.com"
      submodelRepository:
        baseUrl: "https://aasenv.internal.basyx.com"
      conceptDescriptionRepository:
        baseUrl: "https://aasenv.internal.basyx.com"
    security:
      type: oauth2
      config:
        flow: client_credentials
        issuer: "https://keycloak.internal.basyx.com/auth/realms/BaSyx"
        clientId: "basyx-service-client"
        clientSecret: "your-client-secret-here"
        scope: ""

Basic Authentication#

infrastructures:
  default: staging

  staging:
    name: Staging Environment
    components:
      aasRegistry:
        baseUrl: "https://aasreg.staging.basyx.com"
      submodelRegistry:
        baseUrl: "https://smreg.staging.basyx.com"
      aasRepository:
        baseUrl: "https://aasenv.staging.basyx.com"
      submodelRepository:
        baseUrl: "https://aasenv.staging.basyx.com"
      conceptDescriptionRepository:
        baseUrl: "https://aasenv.staging.basyx.com"
    security:
      type: basic
      config:
        username: "admin"
        password: "admin123"

Bearer Token Authentication#

infrastructures:
  default: test

  test:
    name: Test Environment
    components:
      aasRegistry:
        baseUrl: "https://aasreg.test.basyx.com"
      submodelRegistry:
        baseUrl: "https://smreg.test.basyx.com"
      aasRepository:
        baseUrl: "https://aasenv.test.basyx.com"
      submodelRepository:
        baseUrl: "https://aasenv.test.basyx.com"
      conceptDescriptionRepository:
        baseUrl: "https://aasenv.test.basyx.com"
    security:
      type: bearer
      config:
        token: "your-bearer-token-here"

Multiple Infrastructures#

infrastructures:
  default: production

  production:
    name: Production Environment
    components:
      # ... production components
    security:
      type: oauth2
      config:
        flow: auth_code
        issuer: "https://auth.prod.example.com/realms/basyx"
        clientId: "basyx-web-ui"
        scope: "openid profile email"

  development:
    name: Development Environment
    components:
      # ... development components
    security:
      type: none

  partner-a:
    name: Partner A Infrastructure
    components:
      # ... partner A components
    security:
      type: oauth2
      config:
        flow: auth_code
        issuer: "https://auth.partner-a.com/realms/basyx"
        clientId: "basyx-integration"
        scope: "openid"

Docker Deployment#

Mounting the Configuration File#

services:
  aas-web-ui:
    image: eclipsebasyx/aas-gui:latest
    ports:
      - '3000:3000'
    volumes:
      - ./basyx-infra.yml:/basyx-infra.yml:ro
    environment:
      # Control whether users can edit infrastructures
      ENDPOINT_CONFIG_AVAILABLE: "false"  # Locked mode

Configuration Precedence#

Environment variables take precedence over YAML for backward compatibility:

  1. Environment Variables (highest): If any infrastructure-related env vars are set (e.g., AAS_REGISTRY_PATH, KEYCLOAK_URL), the YAML file is ignored

  2. YAML Configuration: Only used when no env vars are configured

  3. User Edits (localStorage): User modifications in the UI (if ENDPOINT_CONFIG_AVAILABLE=true)

Configuration Locking#

Control user ability to modify infrastructures with ENDPOINT_CONFIG_AVAILABLE:

  • false (Locked Mode):

    • Configuration source (env vars or YAML) takes full precedence

    • Users cannot add or edit infrastructures

    • Recommended for production

  • true (Editable Mode - Default):

    • Configurations from source are loaded as templates

    • Users can edit and create infrastructures

    • Changes stored in browser localStorage

    • Recommended for development

Security Configuration Reference#

Authentication Types#

The security.type field accepts:

  • none: No authentication

  • oauth2: OAuth2/OIDC authentication

  • basic: HTTP Basic authentication

  • bearer: Bearer token authentication

OAuth2 Fields#

Common Fields (Both Flows):

  • flow (required): auth_code or client_credentials

  • issuer (required): OAuth2 authorization server URL

  • clientId (required): Client identifier

  • scope (optional): Space-separated OAuth2 scopes (default: "")

Client Credentials Flow Only:

  • clientSecret (required): Client secret for authentication

Warning

Client secrets in YAML files are visible in the browser. Never use client credentials flow in production environments with external access.

Basic Authentication Fields#

  • username (required): Username for authentication

  • password (required): Password for authentication

Bearer Token Fields#

  • token (required): Bearer token string

Component Integration Options#

These optional boolean flags control who is responsible for synchronizing descriptors and asset links when AAS or submodels change.

aasRegistry:

  • hasDiscoveryIntegration (optional, default: true): When true, the backend is expected to handle Discovery Service synchronization itself — the Web UI will not create, update, or delete asset links in the Discovery Service. When false, the Web UI takes over this responsibility and directly manages asset links based on changes to AAS.

aasRepository and submodelRepository:

  • hasRegistryIntegration (optional, default: true): When true, the backend is expected to handle Registry synchronization itself — the Web UI will not create, update, or delete descriptors in the corresponding registry. When false, the Web UI takes over this responsibility and directly manages descriptors based on changes to AAS and submodels.

Note

Set these flags to false when your backend components do not have built-in registry or discovery integration. In that case, the Web UI automatically keeps registries and discovery in sync whenever AAS or submodels are created, updated, or deleted.

Implementation Details#

Infrastructure IDs#

  • YAML-based: yaml_<yamlKey> (stable across reloads)

  • User-created: infra_<timestamp> (unique per creation)

YAML to Internal Format Mapping#

  • YAML baseUrl → Internal url

  • YAML field names match internal store structure

  • Security types map: none → No Authentication, oauth2 → OAuth2, etc.

Loading Process#

  1. Container Startup (entrypoint.sh):

    if [ -f "/basyx-infra.yml" ]; then
  cp /basyx-infra.yml /usr/src/app/dist/config/basyx-infra.yml
fi

  2. Application Startup (useInfrastructureConfigLoader):

    • Determine base path (dev: import.meta.env.BASE_URL, prod: envStore.getEnvBasePath)

    • Fetch from ${basePath}/config/basyx-infra.yml

    • Return null if file doesn’t exist (404)

  3. YAML Parsing (useInfrastructureYamlParser):

    • Convert YAML structure to internal format

    • Transform baseUrl to url for each component

    • Map security types to internal enums

    • Generate infrastructure IDs: yaml_<yamlKey>

  4. Configuration Merging (useInfrastructureStorage):

    • Check if environment variables are configured

    • Load YAML file and parse infrastructures

    • Merge with localStorage based on ENDPOINT_CONFIG_AVAILABLE

    • Authenticate client credentials flows automatically

OAuth2 Client Credentials Auto-Authentication#

When client_credentials flow is detected:

  • Application automatically authenticates on load

  • Token refresh handled automatically

  • No user interaction required

Best Practices#

  1. Use YAML for Production: Avoid deprecated environment variables for infrastructure config

  2. Lock Configuration: Set ENDPOINT_CONFIG_AVAILABLE=false in production

  3. Secure Secrets: Never use client credentials flow with external access

  4. Multiple Infrastructures: Define all environments in one YAML file

  5. Default Infrastructure: Always set a sensible default key

  6. Version Control: Commit YAML templates, not files with real credentials

  7. Read-Only Mount: Mount YAML files as read-only (:ro) in Docker

Introducing new Environment Variables#

When introducing new environment variables, the following files need to be updated accordingly:

  • env.development – for development mode (including dev defaults)

  • entrypoint.sh – for production mode (including prod defaults)

  • src/store/EnvironmentStore.ts – to define placeholders that will be replaced at runtime (including application defaults)

Next Steps#