Getting Started

Prerequisites

  • Visual Studio Code

  • Node.js v24.12.0

  • GIT 2.36.0.windows.1

  • Docker Desktop 4.x

AASPortal is a mono-repository project. It is implemented using the npm workspaces concept. The project consists of the following workspaces:

  • aas-core: Shared types, utilities, and AAS data models used across workspaces

  • aas-package: Node.js library for reading and writing AASX package files (JSON/XML, V1/V2/V3 support)

  • aas-portal: The browser app of AASPortal. It’s an Angular-based frontend application using Bootstrap 5 and NgRx state management

  • aas-node: Node.js/Express.js backend with REST API, authentication (JWT), and OpenAPI/Swagger documentation

  • aas-lib: Angular library containing reusable UI components and services

  • aas-server: AAS server application with IDTA Part 2 compliant API

  • aas-browser: Frontend application for the AAS server

aasportal
  ├── projects
  │     ├── aas-core
  │     │     └── package.json
  │     ├── aas-package
  │     │     └── package.json
  │     ├── aas-lib
  │     │     └── package.json
  │     ├── aas-node
  │     │     └── package.json
  │     ├── aas-portal
  │     │     └── package.json
  │     ├── aas-server
  │     │     └── package.json
  │     └── aas-browser
  │          └── package.json
  └── package.json

Using Docker/Podman (Easiest)

Run the all-in-one image from DockerHub:

# Docker
docker run -p 80:80 fraunhoferiosb/aasportal_aio

# Podman
podman run -p 80:80 docker.io/fraunhoferiosb/aasportal_aio

Then open http://localhost/ in your browser.

Using Kubernetes

For production deployments in Kubernetes, AASPortal supports:

  • Standard root path deployment (/)

  • Sub-path deployment (e.g., /aasportal/) via BASE_HREF environment variable

  • Ingress configuration with path rewriting

  • High availability with horizontal pod autoscaling

See the Kubernetes Deployment Guide for detailed instructions, including:

  • Complete deployment manifests

  • Ingress configuration examples

  • Environment variable reference

  • Troubleshooting common issues

Quick Start:

# Deploy at root path
kubectl apply -f https://raw.githubusercontent.com/eclipse-aasportal/AASPortal/main/kubernetes/deployment.yaml

# Or deploy under sub-path (e.g., /aasportal/)
# Set BASE_HREF=/aasportal/ in deployment manifest
# Configure ingress with path rewriting
# See Kubernetes guide for details

Or build a complete image from the Dockerfile, run the entire AASPortal application in a container, expose the application on port 80 (intended for production-like deployment) using

# Docker
npm run start

# Podman
npm run podman

Start AASPortal

The following command creates and executes a composed Docker image:

npm run start

Open one of the supported web browsers and go to the Web site:

http://localhost/

Local Development Setup

  1. Clone the repository:

    git clone https://github.com/eclipse-aasportal/AASPortal.git
cd AASPortal

  2. Install dependencies:

    npm install

  3. Build all workspaces:

    npm run build -ws

  4. Start the development server:

    npm run serve

  5. Open http://localhost/ in your browser

Alternatively, the application can be started by specifying an Asset Administration Shell:

http://localhost/?id='value'

value can be the AAS identification:

http://localhost/?id=http://boschrexroth.com/shells/0608842005/917004878

the identification base64URL encoded

http://localhost/?id=aHR0cDovL2Jvc2NocmV4cm90aC5jb20vc2hlbGxzLzA2MDg4NDIwMDUvOTE3MDA0ODc4

or the name (idShort) of the AAS

http://localhost/?id=Bosch_NexoPistolGripNutrunner

AASNode

AASNode is a Node.js server application based on the Express framework. The main feature of AASNode is the provision of Asset Administration Shells from different data sources (AASX server, OPC UA server, file system). AASNode can read Asset Administration Shells in JSON, XML and OPC UA format. An Asset Administration Shell is always provided to a web client (AASPortal) in JSON version 3 format.

AASNode provides a user management. Authentication of a user is based on Json Web Token.

Environment Variables

Name

default

ASSETS

AASNode root directory local endpoints and templates.

‘./assets’

CONTENT_ROOT

The root directory where AASNode is located.

‘./’

CORS_ORIGIN

‘*’

ENDPOINTS

The URLs of the initial AAS container endpoints.

[‘file:///samples’]

HTTPS_CERT_FILE

Certification file to enable HTTPS.

HTTPS_KEY_FILE

Key file to enable HTTPS.

JWT_EXPIRES_IN

The period for the validity of a JWT.

604800 (1 week)

JWT_PUBLIC_KEY

Public key file for RS256 encryption.

JWT_SECRET

Secret for HS256 encryption or private key file for RS256 encryption.

‘The quick brown fox jumps over the lazy dog.’

MAX_WORKERS

Number of background worker that scan AAS containers.

8

AAS_NODE_PORT

The port number where AASNode is listening.

80

USER_STORAGE

URL of the user database.

‘./users’

TIMEOUT

Timeout until a new scan starts (ms).

5000

WEB_ROOT

The root directory for static file resources.

‘./wwwroot’

Endpoints

An endpoint is an URL and a unique name to an AAS container. An AAS container can be:

  • AASX Server

  • OPC UA Server

  • AAS Registry

  • Directory in a file system that contains *.aasx files

Users

AASPortal supports anonymous (guest) and authenticated access. The guest has limited read-only access to data and functions of AASPortal. AASPortal offers the possibility to manage data of registered users in a MongoDB. For this purpose, a URL to a MongoDB must be entered in the environment variable USER_STORAGE:

USER_STORAGE=mongodb://<address>:<port>/aasportal-users

A local, file-based user database is available for testing purposes.

AAS Templates

Templates denote submodels or concrete submodel elements for creating and editing Asset Administration Shells.

templates
  ├── submodel
  │     └── *.json
  └── submodel-element
        └── *.json

OpenAPI (Swagger)

The AASNode provides an OpenAPI-compliant REST API. The Swagger UI is accessible via the URL:

http://localhost/api-docs

Authentication with Json Web Tokens (JWT)

AASPortal uses JSON web tokens for authorization. Environment variables can be used to choose between HS256 or RS256 encryption. The expiration date of a token can also be defined via an environment variable.

JWT_EXPIRES_IN=<seconds>

The value is to be entered in seconds. By default, a token is valid for one week.

HS256 Encryption

HS256 (HMAC with SHA-256) involves a combination of a hashing function and one (secret) key that is shared between the two parties used to generate the hash that will serve as the signature. Since the same key is used both to generate the signature and to validate it, care must be taken to ensure that the key is not compromised.

JWT_SECRET=<secret>

RS256 Encryption

RS256 (RSA Signature with SHA-256) is an asymmetric algorithm, and it uses a public/private key pair: the identity provider has a private (secret) key used to generate the signature, and the consumer of the JWT gets a public key to validate the signature.

JWT_SECRET=<path to private key file>

JWT_PUBLIC_KEY=<path to public key file>

HTTPS

To enable HTTPS

HTTPS_CERT_FILE=<path to certificate file>

HTTPS_KEY_FILE=<path to key file>