# 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 ```txt 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: ```bash # 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](kubernetes.md) for detailed instructions, including: - Complete deployment manifests - Ingress configuration examples - Environment variable reference - Troubleshooting common issues **Quick Start:** ```bash # 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 ```bash # 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:** ```bash git clone https://github.com/eclipse-aasportal/AASPortal.git cd AASPortal ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Build all workspaces:** ```bash npm run build -ws ``` 4. **Start the development server:** ```bash 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://
:/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. ```txt 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=`*``* 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=`*``* ### 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=`*``* `JWT_PUBLIC_KEY=`*``* ## HTTPS To enable HTTPS `HTTPS_CERT_FILE=`*``* `HTTPS_KEY_FILE=`*``*