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.
If you need support feel free to contact us through our website Mnestix.io.
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:
-
Node.js
-
Yarn
-
Docker: Docker is required to create and run the application containers.
-
Docker Compose: Docker Compose is a tool for defining and running multi-container Docker applications.
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 theJS Debug
run configuration. - In
Visual Studio Code
you can set up a debug browser by creating alaunch.json
file in theRun 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
andyarn lint
to apply code formatting and linting.yarn test
andyarn 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.
Name | Default value | Description | required |
---|---|---|---|
DISCOVERY_API_URL |
Address of the Discovery Service to find an AAS for an Asset | required | |
REGISTRY_API_URL |
Address of the AAS Registry Service to retrieve the related descriptor for an AAS | optional | |
SUBMODEL_REGISTRY_API_URL |
Address of the Submodel Registry Service to retrieve the related descriptor for a Submodel | optional | |
AAS_REPO_API_URL |
Default AAS Repository to display when AAS Id is not in AAS Registry | required | |
SUBMODEL_REPO_API_URL |
Default Submodel Repository to display when Submodel Id is not in Submodel Registry | required | |
MNESTIX_BACKEND_API_URL |
Mnestix Backend with a lot of business comfort features like the Repository-Proxy or the Template builder | optional | |
AAS_LIST_FEATURE_FLAG |
false | Enables or disables the AasList in the frontend. This only works in combination with Features__AllowRetrievingAllShellsAndSubmodels being set to true (Needs the Mnestix Backend to work) |
optional |
TRANSFER_FEATURE_FLAG |
false | Enables or disables the Transfer Feature in the frontend. If enabled, it is possible to import a viewed AAS to a configured repository. This feature is currently being developed. | optional |
AUTHENTICATION_FEATURE_FLAG |
false | Enable or disable the authentication in the frontend. (Needs the Mnestix Backend to work) | optional |
COMPARISON_FEATURE_FLAG |
false | Enables or disables the comparison feature. | optional |
LOCK_TIMESERIES_PERIOD_FEATURE_FLAG |
false | Enables or disables the selection of the timerange in the TimeSeries submodel. | optional |
THEME_PRIMARY_COLOR |
Mnestix Primary Color | Changes the primary color of Mnestix Browser, e.g. #00ff00. The following formats are supported: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color() | optional |
THEME_SECONDARY_COLOR |
Mnestix Secondary Color | Changes the secondary color of Mnestix Browser, e.g. #0d2. The following formats are supported: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color() | optional |
THEME_LOGO_MIME_TYPE |
Used in parsing the logo mounted -v /path/to/logo:/app/public/logo the mime type is needed, e.g. image/svg+xml , image/png , image/jpg |
optional | |
THEME_LOGO_URL |
This variable overwrites the Logo in the theme, and thus the environment variable THEME_LOGO_MIME_TYPE will not be evaluated and it is not necessary to mount the image as specified below |
optional | |
KEYCLOAK_ENABLED |
false | By default, it is set to false, meaning Keycloak authentication will be disabled, and the default authentication method will be Azure Entra ID. If you set this variable to true, Keycloak authentication will be enabled instead. | optional |
KEYCLOAK_CLIENT_ID |
mnestix-browser-client-demo | Configuration variable that specifies the client unique identifier used by your application when connecting to the Keycloak server. | optional |
KEYCLOAK_ISSUER |
Configuration variable that specifies the URL of the Keycloak servers issuer endpoint. This endpoint provides the base URL for the Keycloak server that issues tokens and handles authentication requests | optional | |
KEYCLOAK_LOCAL_URL |
Optional configuration variable specifically used for development environments within Docker. This allows your application to connect to a Keycloak instance running in a Docker container | optional | |
KEYCLOAK_REALM |
BaSyx | Configuration variable that specifies the name of the Keycloak realm your application will use for authentication and authorization. | optional |
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
.
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 a github project, we recommend having a look at this
guide: Contributing to a project.
We would be more than happy to have you onboard. If there is anything you want to know, feel free to contact
us mnestix@xitaso.com.