Mnestix Browser is an open source software designed to simplify the implementation of the Asset Administration Shell. Together with increasing contributions from users and developers, a growing community is working on further development under the leadership of XITASO, a leading high-end software development company in the engineering industry. Mnestix Browser is the perfect tool to demonstrate the power and potential of AAS (Asset Administration Shells) for the implementation of standardized digital twins. It opens the way for use cases such as the Digital Product Passport (DPP).

You can find a demo here. Some screenshots can be found in the screenshots folder.

All you need to start your first Mnestix instance is the compose.yml (or clone the repository). In the root directory run the following command and open http://localhost:3000 in your web browser.

docker compose up

If you want to further configure your mnestix instance, read about configuration.

• Next.js

Before you begin, ensure you have the following tools installed on your system:

1. Node.js

2. Yarn

3. Docker: Docker is required to create and run the application containers.

   • Install Docker

4. Docker Compose: Docker Compose is a tool for defining and running multi-container Docker applications.

   • Install Docker Compose

Windows users may use WSL for their docker instance.

The easiest way to get Mnestix up and running is by using the prepared development environment. This setup includes:

• Mnestix Browser (This repository)
• Mnestix Backend
• BaSyx Repository
• BaSyx Discovery Service
• BaSyx Registry
• BaSyx Submodel Registry

To start all mentioned services together, run the following command:

yarn docker:dev

This will build the Mnestix Browser and start all mentioned services with a default configuration, to adapt this setup have a look at configuration. The Mnestix Browser is now running on http://localhost:3000.

If you want to start the browser through your IDE separately start BaSyx and the backend with

yarn docker:backend

In your IDE you can then simply start the dev environment with hot reloading by running

yarn dev

The Mnestix Browser is now running on http://localhost:3000 and will update on changed files.

If you want to activate debug breakpoints in the code, you may have to open the website through a debug environment:

• In JetBrains WebStorm you can run a debug browser with the JS Debug run configuration.
• In Visual Studio Code you can set up a debug browser by creating a launch.json file in the Run and Debug tab and create a run configuration for your preferred browser.

You may need to set the initial URL to http://localhost:3000.

To check what other options exist to run the Mnestix Browser, see the yarn scripts in package.json. Highlights are:

• yarn dev to start the browser in a hot reloading dev environment.
• yarn prettier, yarn format and yarn lint to apply code formatting and linting.
• yarn test and yarn test:headless to run cypress tests locally.
• yarn docker:prod will build everything with the production flag.
• yarn docker:test will run all tests in the docker environment.
• yarn docker:prune will stop all docker containers, remove them from the list and prune all volumes. Start with a blank slate :)
• yarn docker:keycloak will setup a local keycloak instance and start Mnestix with keycloak support enabled

You can (and should) create your personal .env file in the root directory. Simply rename .env.example to .env and enter your secrets. The secrets may be arbitrary strings.

This .env file will be used automatically by docker compose and Next.js.

AD_SECRET_VALUE: '<<YOUR_SECRET>>'
MNESTIX_BACKEND_API_KEY: '<<YOUR_API_KEY>>'
NEXTAUTH_SECRET: '<<YOUR_SECRET>>'

⚠️ Important: If you have not configured these secrets, a public secret will be used as a fallback!

• compose.yml - runs Mnestix Browser in production environment. Production image will be build if not found in local Docker Image Cache.
  Mnestix Browser on port 3000 - http://localhost:3000
  
  

• docker-compose/compose.dev.yml - override file to run Mnestix Browser in a development environment. A development image will be built if it is not found in the local Docker Image Cache.
  Mnestix Browser on port 3000 - http://localhost:3000
  Mnestix Api on port 5064 - http://localhost:5064
  AAS Repo on port 8081 - http://localhost:8081/swagger-ui/index.html
  
  

• docker-compose/compose.test.yml - override file used to configure and run end-to-end (E2E) tests using Cypress. When this file is executed, it will start the necessary services for the application and execute the Cypress tests. If any test fails, the results and logs will be saved in a designated directory for further analysis.
  
  

• docker-compose/compose.azure_ad.yml - override file to activate authentication using Azure Entra ID. You will need to provide your own Authentication Endpoint. Configuration can be found here.
  
  

• docker-compose/compose.keycloak.yml - override file to activate authentication using keycloak. Configuration can be found here.
  keycloak admin page - http://localhost:8080

The files in the docker-compose directory are override compose files, which must be added with the -f <filename> flag (Look inside the package.json for examples).
The services are grouped into three compose profiles: basyx, backend and frontend. They can be started together without defining --profile or separately by adding --profile <profilename> to the docker command. One example to start the backend in dev mode with authentication:

docker compose -f compose.yml -f docker-compose/compose.dev.yml -f docker-compose/compose.azure_ad.yml --profile basyx --profile backend up

Additional services used by the Mnestix browser:

• mnestix-api - API service from the Mnestix ecosystem designed to expand Mnestix Browser functionalities, adding AAS List, Template Builder and allowing for the configuration of custom settings such as themes and aasId generation. (On port 5054 - http://localhost:5064/swagger/index.html#/)
• mongodb - NoSql database to store data
• aas-environment - service of AAS repository (BaSyx component aas-environment)
• aas-registry - registry to register and search for AAS in multiple repositories
• submodel-registry - registry to register and search for submodels in multiple repositories
• aas-discovery - discovery service to register and search for an AAS by assetId

docker compose -f compose.yml logs <service-name>

Info: For Keycloak setup instructions, please refer to the Keycloak configuration section.

Our Docker images are available on Docker Hub Mnestix Browser and Mnestix Api. You can pull the images using the following commands:

docker pull mnestix/mnestix-browser:tag

docker pull mnestix/mnestix-api:latest

Install all packages for the frontend.

yarn install

We provide a simple AAS in the folder test-data which you can use as a first test AAS. You can upload the .aasx file to your BaSyx repository by using the upload endpoint of BaSyx (check http://localhost:8081/swagger-ui/index.html and search for the /upload endpoint to get more information).
Afterward, you can visit your running Mnestix Browser and search for the AAS ID https://vws.xitaso.com/aas/mnestix to visualize the test AAS.

The Mnestix Browser enables you to browse through the different AAS Dataspaces. It allows you to visualize Asset Administration Shells and their submodels. It supports the AAS Metamodel and API in version 3.

You configure the endpoint of an AAS repository and browse the different AAS, if a Discovery Service is available, it is also possible to search for AssetIds and visualize the corresponding AAS.

Mnestix AAS Browser is also optimized for mobile view to have a great user experience on mobile phones.

Mnestix can visualize every submodel even if it is not standardized by IDTA. There are some submodels visualized in an extra user-friendly manner. These are:

• Digital Nameplate
• Handover Documentation
• Carbon Footprint
• and more!

Moreover, dedicated visualizations for submodels can be added as a further feature.

It is possible to change the look and feel by setting a theme color and a personal logo when deploying the Mnestix Browser, see here.

• Mnestix is using BaSyx, by appending /repo to our URLs, we are forwarding the requests to BaSyx via proxy: BaSyx AAS API Collection
• With this, BaSyx endpoints can be reached through Mnestix.
  • AAS Repository Api: http://localhost:3000/repo/shells/{YourAasIdInBase64}
  • Submodel Repository Api: http://localhost:3000/repo/submodels/{YourAasIdInBase64}
  • The BaSyx Swagger UI gives a detailed overview of all available endpoints: http://localhost:8081/swagger-ui/index.html

Mnestix provides the following configuration options. You can adapt the values in your docker compose file.

There are multiple ways to set a logo, you can either use Option 1 or Option 2:

First you need to mount your logo to the container, e.g. by adding it to the docker compose file

environment:
  - THEME_LOGO_MIME_TYPE: 'image/svg+xml'
---
volumes:
  - /path/to/my/logo.svg:/app/public/logo

When using the provided compose.yaml File you can just replace the image in the data folder with your preferred logo.

Remember to set the mime type correctly in order for the browser to parse your image correctly. Only image mime types are allowed. https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

This version overwrites the previous settings, you can either use one or the other. To use this just set an environment variable to a link hosted that is publicly accessible:

---
environment:
  THEME_LOGO_URL: https://xitaso.com/wp-content/uploads/XITASO-Logo-quer.svg

You will need your own AzureAD authentication service!

You can activate authentication with Azure Entra ID by starting the Mnestix docker container with the -f docker-compose/compose.azure_ad.yml flag. Please configure the tenant ID in both services and both client IDs for your own authentication service in this file.

Use the .env file to configure your sensitive information:

AD_SECRET_VALUE: '<<YOUR_SECRET>>'

Note (Mnestix version 1.1.0 and above): With NextAuth, authentication now happens server-side. You'll need an Azure Secret AD_SECRET_VALUE for secure server-side communication, unlike the previous client-side SPA setup.

⚠️ Important: Ensure that you update any confidential variables from their default values before deploying to a production environment.

If you want to start the browser with Next.js and Azure authentication directly, take a look at the .env.local file and update the environment variables mentioned above in there. Notably, the following flags must be set AUTHENTICATION_FEATURE_FLAG: true and KEYCLOAK_ENABLED: false.

Without specifying your own API key, Mnestix will use the default 'verySecureApiKey'!

To have the full functionality of the Mnestix Browser you can configure the environment variables for the mnestix-api service in the compose.yml file. It is also necessary to set MNESTIX_BACKEND_API_KEY. This may be any string and acts as your password for the backend api service and the repo proxy. This can be done directly in the compose.yml or by defining the environment variable in your .env file:

MNESTIX_BACKEND_API_KEY: '<<YOUR_API_KEY>>'

The Discovery Service enables Mnestix to find all AASs that belong to one Asset. We are standard conform but recommend the usage of the BaSyx Implementation of the Discovery Service.

The AAS Registry is designed to retrieve AAS Descriptors that contain the endpoint for the Asset Administration Shell (AAS) Interface.

( Source: IDTA)

A tutorial about the Discovery Service along with the registries can be found on the IDTA website.

There also exists the Mnestix API, that provides different business comfort features. Here it is possible to set an API Key, for example, to secure your backend services like the repository or the discovery service. When running the Mnestix API you can change the paths to the different services like described in the Mnestix API Documentation. For example (change {{MNESTIX_BACKEND_API_URL}} to the URL of the running Mnestix API)

DISCOVERY_API_URL: '{{MNESTIX_BACKEND_API_URL}}/discovery'
AAS_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
SUBMODEL_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
MNESTIX_BACKEND_API_URL: '{{MNESTIX_BACKEND_API_URL}}'

This is the easiest configuration, for when you only want to visualize and browse through AAS. If you choose to run the Mnestix Browser without the Mnestix API, the Feature Flags AUTHENTICATION_FEATURE_FLAG and AAS_LIST_FEATURE_FLAG will be overwritten to false as these Features use the functionality of the API. The other environment variables should be configured as described.

We recommend the usage of Mnestix together with the BaSyx AAS Repository. This component stores all the different AAS (type 2), it is recommended to configure it to use a database for persistence. We recommend to set the following environment variables (replace {{MNESTIX VIEWER URL}}, {{MNESTIX API URL}} with the corresponding values):

# Allow to upload bigger AASX files
SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE: 100000KB
SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE: 100000KB
# Allow mnestix frontend and backend to call basyx
BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD

If you are using the Mnestix API see here on how to set the Frontend Flags. If you are using only the Mnestix Browser just set the environment variables AAS_REPO_API_URL and SUBMODEL_REPO_API_URL accordingly.

We recommend the usage of Mnestix together with the BaSyx AAS Discovery Service. This component links Asset IDs to AAS IDs. It is recommended to configure it to use a database for persistence. We recommend to set the following environment variables (replace {{MNESTIX VIEWER URL}}, {{MNESTIX API URL}} with the corresponding values):

# Allow mnestix frontend and backend to call discovery service
BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD

If you are using the Mnestix API see here on how to set the Frontend Flags. If you are using only the Mnestix Browser just set the environment variable DISCOVERY_API_URL accordingly.

The functions that are described in the Specification AAS - Part 2: API were implemented in the discoveryServiceApi.ts. They make the respective GET, POST and DELETE requests to the specified DISCOVERY_API_URL. Two additional functions were added that simplify the usage of the Discovery Service by just requiring the globalAssetId and no additional AssetLinks.

These functions are LinkAasIdAndAssetId(aasId: string, assetId: string) and GetAasIdsByAssetId(assetId: string). The return of all functions is the response from the Discovery Service parsed as an object. So they can be used like in the example below:

await LinkAasIdAndAssetId(aasId, assetId);
const foundAasIds = (await discoveryServiceClient.GetAasIdsByAssetId(assetId)).result;

The AAS Registry Service is designed to provide descriptors for Asset Administration Shells (AAS), including endpoints to various repositories that may be stored elsewhere. This architecture ensures support for multiple repositories, provided they are registered in the designated AAS registry.

When an AAS for the specified AAS-Id is found, it is displayed in the detail view. If the AAS is not found, the service will search in the local repository for the requested information.

If the discovery service is configured, it will initially identify the relevant AAS-ID for the searched Asset ID before querying the Registry Service. Configuration of the Registry Service is optional. If the AAS Registry Service is not configured, the search will default to the local repository.

To configure the AAS registry, please provide the URL in the Frontend Configuration variables.

REGISTRY_API_URL: '{{REGISTRY-SERVICE-URL}}'

By setting the REGISTRY_API_URL, you enable the AAS Registry Service, ensuring efficient retrieval of AAS descriptors.

The Submodel Registry feature provides an optional configuration that allows you to manage and resolve submodels efficiently. When the Submodel Registry is configured, any reference to a submodel will first check if the submodel is available in the specified registry endpoint. If the submodel is found in the registry, it will be fetched from there. If the submodel is not found in the registry, the system will then check the local repository for the submodel.

Configuring the Submodel Registry is optional. If not configured, all submodel references will default to being resolved from the local repository only.

To configure the Submodel registry, please provide the URL in the Frontend Configuration variables.

SUBMODEL_REGISTRY_API_URL: '{{SUBMODEL_REGISTRY_API_URL}}'

By setting the SUBMODEL_REGISTRY_API_URL, you enable the Submodel Registry Service, ensuring efficient retrieval of Submodel descriptors.

The functions that are described in the Specification AAS - Part 2: API were implemented in the registryServiceApi.ts. They make the respective GET, POST and DELETE requests to the specified REGISTRY_API_URL.

There are multiple scenarios possible on how to deploy the Mnestix Browser with different configurations. In the following, it is described, what scenarios were thought of and how to configure them

If you just want to view AAS and integrate it into your existing environment, you can run only the mnestix-viewer without its API. See Running Mnestix without its API.

There are also some more advanced features one might want to use. For this you need to enable the Mnestix API, see here. It enables you to secure all POST/PATCH/DELETE-Request with an API-Key. The API-Key needs to be sent within the Header ApiKey to make those requests. Normal GET/FETCH-Requests are not affected by this.

When using it is also possible to restrict some functions that you possibly don't want to be accessible. For example, it is possible to restrict the access to the /shells endpoint of the AAS repository by setting the backend environment variable Features__AllowRetrievingAllShellsAndSubmodels: false. Remember that this also means that the functionality to list all AAS won't work anymore in the Mnestix Browser, so disable this functionality with the environment variable AAS_LIST_FEATURE_FLAG: false.

The AAS_LIST_V2_FEATURE_FLAG is a feature flag introduced as part of a preview release. It enables access to an updated list implementation that operates independently of the Mnestix API.

This flag is currently disabled by default (false) and is available only in preview. It is not yet recommended for production environments.

To enable the feature for testing or preview purposes, set the flag to true in your configuration.

One can also add an AzureAD Service to give people deeper access, this enables the "Login" Button in the Mnestix Browser. After logging in, users have access to even more functionality. To see how to connect to an Azure Tenant and enable the login functionality see the official Mnestix API documentation.

This option builds upon the advanced features described in the previous section. After logging in it is possible to configure the ID Generation Functionality of the backend. Here it is possible to automatically generate AAS using only a short ID of the Asset. How the AAS Creator in conjunction with the ID Generations Functionality works can be seen in the official Mnestix API documentation.

One can also use the Template Builder with the Data Ingest Endpoint to send arbitrary JSON files to the API and automatically add them to a specified AAS. This enables easy integration into existing ETL processes. How exactly this works can be seen in the official Mnestix API documentation.

Below you'll find a small overview on how the components interact with each other:

See .vscode/extensions.json for a list of recommended extensions. VSCode will suggest to install them when opening the project.

See .vscode/settings.json for defined workspace settings.

Check the configurations for Rider under .idea/ folder

We use Prettier and ESLint to keep our frontend code clean. Having a ESLint warning will break the pipeline. It's therefore always a good idea to run yarn format and yarn lint before you commit.

yarn prettier

yarn format

yarn lint

If you want specific files or folders to be excluded from linting (e.g. generated files), you can add them to .eslintignore and .prettierignore

We use Cypress for End-to-End-Testing. In order to navigate to the right folder and run Cypress you can use the following command. In order to use cypress testing the Mnestix Browser must be running.

yarn test

yarn test:headless

Cypress will put videos and screenshots of the tests inside the cypress folder.

In order to run your own E2E-Tests you can put your test files in /cypress/e2e.

In the fixtures folder you can put data to use in your E2E-Tests as json files.

If you have commands you want to use in multiple tests you can put them into the commands.ts file inside the support folder. Don't forget to write the method header of your custom commands inside the e2e.ts file as well. This way the IDE will stop marking your custom commands as wrong.

The YARP proxy route /repo/shells now limits resource and list returns to 104 elements due to the lack of pagination support. This change aims to prevent server overload and ensure smoother navigation through resource lists.

Note: Keycloak support is available starting from version 1.1.0 and above.

For Mnesitx API configuration details, please refer to the API documentation available on Docker Hub.

To start Mnestix along with Keycloak as the authorization server, use one of the following commands:

docker compose -f compose.yml -f docker-compose/compose.dev.yml -f docker-compose/compose.keycloak.yml up -d

or, alternatively:

yarn docker:keycloak

On the first startup, the Keycloak Docker image (docker-compose/data/keycloak/Dockerfile) will be built with an initializer configured for the BaSyx repository. This setup ensures that localhost can be resolved within the Docker network. Additionally, a preconfigured Keycloak realm (docker-compose/data/keycloak/realm/BaSyx-realm.json) will be imported, eliminating the need for any initial Keycloak configuration.

The Keycloak Admin Console will be accessible at http://localhost:8080/admin.

For initial access, use the following temporary credentials:

• Username: admin
• Password: admin

A test user is preconfigured with the following credentials allowing login to Mnestix Browser:

• Username: test
• Password: test

KEYCLOAK_LOCAL_URL:

• Local Development: This variable should be left empty when running Mnestix in a local browser environment.
• Docker Environment: When running in a Docker environment, set this variable to localhost:8080 to enable user credential input. In Docker, the token, user info, and other endpoints will function correctly within the Docker network.

NEXTAUTH_URL: Required variable to configure redirect URL for NextAuth.

NEXTAUTH_SECRET: Required variable used to encrypt the NextAuth.js JWT, and to hash email verification tokens.

⚠️ Important: Ensure that you update any confidential variables from their default values before deploying to a production environment.

Right now, we are building a community around Mnestix. If you are looking for a way to support us, you can start contributing to Mnestix right away. For this purpose, issues which are particularly suitable for a first contribution are labeled with the tag good first issue.
If this is your first time contributing to an eclipse project, we recommend having a look at this guide: Contributing to a Eclipse project.
We would be more than happy to have you on board. If there is anything you want to know, feel free to contact us mnestix@xitaso.com or through our website here.