⚠️ Important Notice: Breaking Changes in main

The main branch contains breaking changes compared to previous versions of the system.

These changes may require adjustments in existing integrations, configurations, or deployments. Please review the changes carefully before upgrading.

What This Means

• Existing setups may no longer work without modification
• Migration effort may be required
• Db Schema has changed
• -NET 9.0 is used now

Legacy Support

If you need to continue working with the previous version, please use the dedicated legacy branch:

➡️ main-db1

This branch is maintained to support the older version and ensure compatibility with existing systems. Docker images for main-db1 are tagged legacy.

Recommendation

• Use main for all new development and future-ready integrations
• Use main-db1 only if you depend on the legacy implementation

Eclipse AASPE Server

Status

Docker Images

Dotnet Version

We currently use Dotnet Version

AASPE Server is a companion app for the AASPE Package Explorer. Some source code is shared, especially AasCore.
AASPE Server is a AAS Repository, a Submodel Repository and a Concept Description Repository.
It can also import and export AASX packages by the AASX File Server API and supports the Serialization API.
AAS and Submodel Queries can be made by the Query Repository API.
A readonly AAS Registry can be provided automatically by the AAS Repository.

AASPE Server uses Entity Framework and stores data in the SQL database SQLite. (Other SQL databases like PostgreSQL may be supported later.)
Performance has been tested with up to 100K AAS, 500K SM, 50M SME and 100M Values, where AASQL queries can be made in less than 10 seconds. Many optimizations have been made by testing with SQLite.

The Core variant exposes REST endpoints and provides changed data by MQTT.
The Blazor variant offers the same functionality and uses Blazor for a browser-based UI.

IMPORTANT

AASX Server is in V3; see Releases.
Ongoing development is also tracked on branches such as newdb2-main (see Docker tag develop below).

TIP

The current reference demo (large dataset, security and row-level filtering enabled) is https://big.aas-voyager.com/.
Explore the API at /swagger, the live access rules at /access, and the DB browser at /db.
See docs/security.md for how the roles, rule language and FILTER blocks used by that server are wired up.

Older demo endpoints such as v3.admin-shell-io.com and v3security.admin-shell-io.com are outdated; prefer big.aas-voyager.com for all new tests and screenshots.

Quick reference (V3)

Topic	Detail
Repository	eclipse-aaspe/server
Default HTTP port	5001 (Kestrel; configure with Kestrel__Endpoints__Http__Url or ASPNETCORE_URLS)
API exploration	Open /swagger on the same base URL as the UI (e.g. http://localhost:5001/swagger)
AASX files	Place packages under ./aasxs (or the path you pass to --data-path)

The legacy V2 REST surface (--rest, --host, --port, fixed port 51310) is no longer the primary API. Ignore the “Connect to REST by:” message in old tooling.

How-to

Currently, AasxServerBlazor is the primary entry point; AasxServerCore may still be used in some deployments. AasxServerWindows is not actively developed; use .NET 8 on Windows with the Blazor variant.

Running from source (development)

Solution file: src/AasxServer.sln. Typical local run (from repository root):

dotnet restore src/AasxServer.sln
dotnet run --project src/AasxServerBlazor/AasxServerBlazor.csproj -- --no-security --data-path ./aasxs --external-blazor http://localhost:5001

Arguments after -- are passed to the server. Adjust --data-path and --external-blazor to match your environment. See also src/AasxServerBlazor/Properties/launchSettings.json for examples.

Remote debugging over SSH (Linux)

For a non-Docker run on a remote machine (bind http://*:PORT, optional Kestrel debug), start from an example script:

• Copy scripts/run-dev-ssh.sh.example to run.sh, set APP_DIR to your publish folder containing AasxServerBlazor.dll, then chmod +x run.sh.

From your laptop, forward the port, e.g.:

ssh -L 50010:127.0.0.1:50010 user@remote-host

Running with .NET (published build)

After publishing AasxServerBlazor, run the DLL (replace YOURPORT / YOURURL):

export DOTNET_gcServer=1
export Kestrel__Endpoints__Http__Url=http://*:YOURPORT
dotnet AasxServerBlazor.dll --no-security --data-path ./aasxs --external-blazor YOURURL

Default port in many configs is 5001. .NET 9 Runtime / SDK is required to build and run.

Running with Docker

Image: docker.io/adminshellio/aasx-server-blazor-for-demo

Tags (there is no latest tag; always specify a tag):

Tag	Meaning
main	Built automatically by the GitHub pipeline on each push to main
develop	Built manually when needed from the current development branch (e.g. newdb2-main)
Version tags	Use when you need a fixed release build

Example (main — CI build from branch main):

docker run \
  -p 5001:5001 \
  --restart unless-stopped \
  -v ./aasxs:/AasxServerBlazor/aasxs \
  docker.io/adminshellio/aasx-server-blazor-for-demo:main

Example (develop — manual build from the active dev branch, e.g. newdb2-main):

docker pull docker.io/adminshellio/aasx-server-blazor-for-demo:develop

docker run \
  -p 5001:5001 \
  --restart unless-stopped \
  -v ./aasxs:/AasxServerBlazor/aasxs \
  docker.io/adminshellio/aasx-server-blazor-for-demo:develop

The same :main / :develop tags apply to the other adminshellio/aasx-server-…-for-demo images (Core, arm32, arm64) when published.

Docker Compose (repository file)

The repository includes a Compose file you can use or adapt:

docker compose -f src/docker/docker-compose.yaml up --build

See src/docker/docker-compose.yaml for ports, volumes (./aasxs), and default command line. There is also src/docker/docker-compose-demo.yaml for demo variants.

Docker Hub variants (architectures)

Variant	linux/amd64	Tags (examples)
Blazor	aasx-server-blazor-for-demo	:main, :develop, version tags
Blazor arm32	aasx-server-blazor-for-demo-arm32	:main, :develop, …
Blazor arm64	aasx-server-blazor-for-demo-arm64	:main, :develop, …
Core	aasx-server-core-for-demo	:main, :develop, …

Multi-architecture

If you want to help with multi-arch images or Raspberry Pi, open an issue.

Build Docker images locally

Use src/BuildDockerImages.ps1 on Windows/PowerShell (see script for prerequisites).

Persistence (database)

V3 can persist data with Entity Framework (SQLite is common; PostgreSQL has been used in tests).

For a walkthrough of the relational schema (entity model, IdShortPath flattening) and how AASQL is translated to SQL (the CombineTablesLEFT pipeline with $$path{n}$$ / $$match{n}$$ / EXISTS placeholders and the recursive smePath{k} / Path{k} / Part1_{..}_{..} aliases), see docs/database-and-query.md.

Flag	Purpose
--with-db	Enable database storage
--start-index 0	First import: load AASX from --data-path into the DB
--start-index N	Later starts: use N greater than the number of AASX files (e.g. 1000) so files are not re-imported
--save-temp SEC	Periodically write API changes to the DB every SEC seconds
--aasx-in-memory N	Limit how many AAS appear in the Blazor tree (only the most recently changed may be shown when limited)

Reference demo with DB enabled: big.aas-voyager.com · DB view · access rules · Swagger.

Security (authentication, roles, access rules)

Security is configured through AAS submodels (SecuritySettingsForServer, SecurityMetamodelForServer) plus a JSON rule file served at /Access. The reference deployment big.aas-voyager.com has role-based authentication and row-level FILTER rules enabled.

For the role catalogue (isNotAuthenticated, isReaderOnly, isAuthenticatedUser, isSuperDuperUser, …), the AllAccessPermissionRules rule language served at /Access, and how FORMULA / FILTER expressions are merged into the AASQL pipeline, see docs/security.md.

Example GraphQL query:

{
   searchSubmodels (semanticId: "https://admin-shell.io/zvei/nameplate/1/0/Nameplate")
   {
     submodelId
     url
   }
}

Registry / auto-POST topics: see issue tracker.

REST API (V3)

• Prefer OpenAPI: GET /swagger (or /swagger/index.html) on your server base URL.
• The implementation follows the Asset Administration Shell REST API (Part 2) for V3; path layout differs from the old V2 tables that used port 51310.

Legacy documentation (V2 paths, AasxServerCore, Mono, port 51310, long path tables) is kept in docs/legacy-readme.md for reference only.

CREATE NEW RELEASES

We've transitioned to semantic versioning for better version distinctness. All versions follow this schema:

<major>.<minor>.<patch>.<buildnumber>-<AAS Schema Version>-<alpha>-<stable|latest|develop>

• buildnumber: An incremented value for each build, crucial for distinguishing between builds, particularly for development or latest releases without new version numbers.
• AAS Schema Version: Indicates the AAS main schema used in this version.
• alpha: Denotes an alpha build, indicating it's not yet a finished release.
• stable: Represents the latest stable release, confirming that main features are working.
• latest: Indicates the most recent build on the main branch, generally stable but may have minor issues.
• develop: Refers to builds from branches other than main or develop, primarily for testing and potentially unstable.

Release a New Version

With the switch to semantic versioning, our release process has been enhanced:

1. Update the Changelog

   • Move all recent changes to the [Released] section in the changelog.
   • Determine the new version number based on semantic versioning and include the release date.

2. Update the Version Configuration

   • Update the current_version.cfg with the new version number.

3. Push Changes

   • Push these changes to the new branch, you made from the main branch state you want to release.

4. Create a New PR to Release Branch

   • Submit a pull request targeting the release branch. Ensure all necessary details are provided.

5. Rebase to Main

   • After the PR is merged into the release branch, rebase these changes onto the main branch. This ensures consistency across branches and updates current_version.cfg and changelog on the main branch.

Once the branch is merged into the release branch, GitHub Workflows will automatically initiate, creating a new draft release. Review the release to confirm everything is in order before publishing it in the release settings.

Docker image releases are handled automatically at this stage.

Nightly Releases

We employ a cron job to check nightly for changes on the main branch. If changes are detected, it creates a new prerelease latest alpha build. This process automatically assigns a new version number, creates a tag, and releases the corresponding Docker images. A changelog is also automatically generated based on PR changes; however, direct merges into main are not included in this changelog.

You can manually trigger this process using the workflow here.

Example Version Tags

• v1.0.0.1-aasV3-alpha-develop: Alpha build on a develop branch.
• v1.0.0.2-aasV3-alpha-stable: Stable release.
• v1.0.0.3-aasV3-alpha-latest: Latest build on the main branch.

Issues

If you want to request new features or report bugs, please create an issue.

Contributing

Please see CONTRIBUTING for instructions on joining the development and general contribution guidelines. For a complete list of all contributing individuals and companies, please visit our CONTRIBUTORS page.