From 6e065f2496004fca7bc2a782f51b87c3debe58d2 Mon Sep 17 00:00:00 2001
From: Paul Gerber
Date: Thu, 8 Oct 2026 18:05:49 +0200
Subject: [PATCH 1/7] server: Add `image:`-based compose files alongside
`compose.dev.yml`
Previously, the example configurations in `example_configurations/`
only had `compose.dev.yml`, which builds the image locally from
source. The READMEs already referenced the pre-built DockerHub images
by name, but there was no compose file that actually used them.
This adds a `compose.yml` per profile (repository, registry,
discovery) that pulls the matching `eclipsebasyx/basyx-python-*:latest`
image instead of building. `docker compose up` now uses the published
image by default; `docker compose -f compose.dev.yml up` remains the
explicit way to build from source for development.
Fixes #640
---
.../discovery_standalone/README.md | 15 +++++++++------
.../discovery_standalone/compose.yml | 10 ++++++++++
.../registry_standalone/README.md | 15 +++++++++------
.../registry_standalone/compose.yml | 10 ++++++++++
.../repository_standalone/README.md | 15 +++++++++------
.../repository_standalone/compose.yml | 11 +++++++++++
6 files changed, 58 insertions(+), 18 deletions(-)
create mode 100644 server/example_configurations/discovery_standalone/compose.yml
create mode 100644 server/example_configurations/registry_standalone/compose.yml
create mode 100644 server/example_configurations/repository_standalone/compose.yml
diff --git a/server/example_configurations/discovery_standalone/README.md b/server/example_configurations/discovery_standalone/README.md
index 6acc02c3..583c0ad0 100644
--- a/server/example_configurations/discovery_standalone/README.md
+++ b/server/example_configurations/discovery_standalone/README.md
@@ -20,13 +20,16 @@ The Discovery Service stores and retrieves relations between AAS identifiers and
## Configuration
-The example Docker compose configuration `compose.dev.yml` builds a discovery server locally. This is usually only necessary
-for development:
+This example Docker compose configuration runs a discovery server using the pre-built
+`eclipsebasyx/basyx-python-discovery:latest` image from [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-discovery):
+```
+$ docker compose up
+```
+
+To build the image locally from source instead, use `compose.dev.yml`. This is usually only necessary for development:
```
$ docker compose -f compose.dev.yml up
```
-To just run the discovery server, use the pre-built image `eclipsebasyx/basyx-python-discovery:latest`
-on [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-discovery).
## Persistence
@@ -34,7 +37,7 @@ The discovery service can run in persistent or non-persistent mode.
### Persistent Mode
-Persistent mode configuration is provided in the `compose.dev.yml`.
+Persistent mode configuration is provided in both `compose.yml` and `compose.dev.yml`.
Only the AAS-to-asset-ID mapping is persisted. The reverse lookup index is rebuilt in memory when the service starts.
@@ -44,5 +47,5 @@ If `storage_path` is not set, the discovery service runs in memory only.
## Notes
- Stop the service before manually editing `discovery_store.json`.
-- Note that the image is built from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
+- `compose.dev.yml` builds the image from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
To include the package license, a second additional build context `license` passes in the repository root.
diff --git a/server/example_configurations/discovery_standalone/compose.yml b/server/example_configurations/discovery_standalone/compose.yml
new file mode 100644
index 00000000..46990b4c
--- /dev/null
+++ b/server/example_configurations/discovery_standalone/compose.yml
@@ -0,0 +1,10 @@
+name: basyx-python-server
+services:
+ app:
+ image: eclipsebasyx/basyx-python-discovery:latest
+ ports:
+ - "8084:80"
+ environment:
+ storage_path: /storage/discovery_store.json
+ volumes:
+ - ./storage:/storage
diff --git a/server/example_configurations/registry_standalone/README.md b/server/example_configurations/registry_standalone/README.md
index b78ccae3..b2c2e32e 100644
--- a/server/example_configurations/registry_standalone/README.md
+++ b/server/example_configurations/registry_standalone/README.md
@@ -39,17 +39,20 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su
## Configuration
-The example Docker compose configuration `compose.dev.yml` builds a registry server locally. This is usually only necessary
-for development:
+This example Docker compose configuration runs a registry server using the pre-built
+`eclipsebasyx/basyx-python-registry:latest` image from [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-registry):
+```
+$ docker compose up
+```
+
+To build the image locally from source instead, use `compose.dev.yml`. This is usually only necessary for development:
```
$ docker compose -f compose.dev.yml up
```
-To just run the registry server, use the pre-built image `eclipsebasyx/basyx-python-registry:latest`
-on [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-registry).
Input files are read from `./input` and stored persistently under `./storage` on your host system.
The server can be accessed at http://localhost:8083/api/v3.1.1/ from your host system.
-To get a different setup, the `compose.dev.yml` file can be adapted using the options described in the main server [README.md](../../README.md#options).
+To get a different setup, the `compose.yml` (or `compose.dev.yml`) file can be adapted using the options described in the main server [README.md](../../README.md#options).
-Note that the image is built from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
+Note that `compose.dev.yml` builds the image from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
To include the package license, a second additional build context `license` passes in the repository root.
diff --git a/server/example_configurations/registry_standalone/compose.yml b/server/example_configurations/registry_standalone/compose.yml
new file mode 100644
index 00000000..ea49877e
--- /dev/null
+++ b/server/example_configurations/registry_standalone/compose.yml
@@ -0,0 +1,10 @@
+services:
+ app:
+ image: eclipsebasyx/basyx-python-registry:latest
+ ports:
+ - "8083:80"
+ volumes:
+ - ./input:/input
+ - ./storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
diff --git a/server/example_configurations/repository_standalone/README.md b/server/example_configurations/repository_standalone/README.md
index 5413100b..9c45c930 100644
--- a/server/example_configurations/repository_standalone/README.md
+++ b/server/example_configurations/repository_standalone/README.md
@@ -1,15 +1,18 @@
# Repository Standalone
-The example Docker compose configuration `compose.dev.yml` builds a repository server locally. This is usually only necessary
-for development:
+This example Docker compose configuration runs a repository server using the pre-built
+`eclipsebasyx/basyx-python-repository` image from [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-repository):
+```
+$ docker compose up
+```
+
+To build the image locally from source instead, use `compose.dev.yml`. This is usually only necessary for development:
```
$ docker compose -f compose.dev.yml up
```
-To just run the repository server, use the pre-built image `eclipsebasyx/basyx-python-repository`
-on [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-repository).
Input files are read from `./input` and stored persistently under `./storage` on your host system.
The server can be accessed at http://localhost:8080/api/v3.0/ from your host system.
-To get a different setup, the `compose.dev.yml` file can be adapted using the options described in the main server [README.md](../../README.md#options).
+To get a different setup, the `compose.yml` (or `compose.dev.yml`) file can be adapted using the options described in the main server [README.md](../../README.md#options).
-Note that the image is built from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
+Note that `compose.dev.yml` builds the image from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
To include the package license, a second additional build context `license` passes in the repository root.
diff --git a/server/example_configurations/repository_standalone/compose.yml b/server/example_configurations/repository_standalone/compose.yml
new file mode 100644
index 00000000..2d4c002a
--- /dev/null
+++ b/server/example_configurations/repository_standalone/compose.yml
@@ -0,0 +1,11 @@
+name: basyx-python-server
+services:
+ app:
+ image: eclipsebasyx/basyx-python-repository:latest
+ ports:
+ - "8080:80"
+ volumes:
+ - ./input:/input
+ - ./storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
From c62028192a532ddc8721240411888de118193f08 Mon Sep 17 00:00:00 2001
From: Paul Gerber
Date: Thu, 8 Oct 2026 18:15:15 +0200
Subject: [PATCH 2/7] Fix stale API base path in example_configurations READMEs
---
.../registry_standalone/README.md | 36 +++++++++----------
.../repository_standalone/README.md | 2 +-
2 files changed, 19 insertions(+), 19 deletions(-)
diff --git a/server/example_configurations/registry_standalone/README.md b/server/example_configurations/registry_standalone/README.md
index b2c2e32e..1358d9e2 100644
--- a/server/example_configurations/registry_standalone/README.md
+++ b/server/example_configurations/registry_standalone/README.md
@@ -13,27 +13,27 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su
# AAS Registry:
| Function | Description | Example URL |
|--------------------------------------------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptor | `GET http://localhost:8083/api/v3.1.1/shell-descriptors` |
-| **GetAssetAdministrationShellDescriptorById** | Return a specific AAS descriptor | `GET http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}` |
-| **PostAssetAdministrationShellDescriptor** | Register/create a new AAS descriptor | `POST http://localhost:8083/api/v3.1.1/shell-descriptors` |
-| **PutAssetAdministrationShellDescriptorById** | Create or update an existing AAS descriptor | `PUT http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}` |
-| **DeleteAssetAdministrationShellDescriptorById** | Delete an AAS descriptor by ID | `DELETE http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}` |
-| **GetSubmodelDescriptorsThroughSuperPath** | Return all submodel descriptors under AAS descriptor | `GET http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}/submodel-descriptors` |
-| **PostSubmodelDescriptorThroughSuperPath** | Register/create a new submodel descriptor under AAS descriptor | `POST http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}/submodel-descriptors` |
-| **GetSubmodelDescriptorThroughSuperPath** | Return a specific submodel descriptor under AAS descriptor | `GET http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
-| **PutSubmodelDescriptorThroughSuperPath** | Create or update a specific submodel descriptor under AAS descriptor | `PUT http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
-| **DeleteSubmodelDescriptorThroughSuperPath** | Delete a specific submodel descriptor under AAS descriptor | `DELETE http://localhost:8083/api/v3.1.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
-| **GetDescription** | Return the self‑description of the AAS registry service | `GET http://localhost:8083/api/v3.1.1/description` |
+| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors` |
+| **GetAssetAdministrationShellDescriptorById** | Return a specific AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
+| **PostAssetAdministrationShellDescriptor** | Register/create a new AAS descriptor | `POST http://localhost:8083/api/v3.1/shell-descriptors` |
+| **PutAssetAdministrationShellDescriptorById** | Create or update an existing AAS descriptor | `PUT http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
+| **DeleteAssetAdministrationShellDescriptorById** | Delete an AAS descriptor by ID | `DELETE http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
+| **GetSubmodelDescriptorsThroughSuperPath** | Return all submodel descriptors under AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors` |
+| **PostSubmodelDescriptorThroughSuperPath** | Register/create a new submodel descriptor under AAS descriptor | `POST http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors` |
+| **GetSubmodelDescriptorThroughSuperPath** | Return a specific submodel descriptor under AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
+| **PutSubmodelDescriptorThroughSuperPath** | Create or update a specific submodel descriptor under AAS descriptor | `PUT http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
+| **DeleteSubmodelDescriptorThroughSuperPath** | Delete a specific submodel descriptor under AAS descriptor | `DELETE http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
+| **GetDescription** | Return the self‑description of the AAS registry service | `GET http://localhost:8083/api/v3.1/description` |
# Submodel Registry:
| Function | Description | Example URL |
|----------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------|
-| **GetAllSubmodelDescriptors** | Return all submodel descriptors | `GET http://localhost:8083/api/v3.0/submodel-descriptors` |
-| **PostSubmodelDescriptor** | Register/create a new submodel descriptor | `POST http://localhost:8083/api/v3.0/submodel-descriptors` |
-| **GetSubmodelDescriptorById** | Return a specific submodel descriptor | `GET http://localhost:8083/api/v3.0/submodel-descriptors/{submodelIdentifier}` |
-| **PutSubmodelDescriptorById** | Create or update a specific submodel descriptor | `PUT http://localhost:8083/api/v3.0/submodel-descriptors/{submodelIdentifier}` |
-| **DeleteSubmodelDescriptorById** | Delete a specific submodel descriptor | `DELETE http://localhost:8083/api/v3.0/submodel-descriptors/{submodelIdentifier}` |
-| **GetDescription** | Return the self‑description of the submodel registry service | `GET http://localhost:8083/api/v3.0/description` |
+| **GetAllSubmodelDescriptors** | Return all submodel descriptors | `GET http://localhost:8083/api/v3.1/submodel-descriptors` |
+| **PostSubmodelDescriptor** | Register/create a new submodel descriptor | `POST http://localhost:8083/api/v3.1/submodel-descriptors` |
+| **GetSubmodelDescriptorById** | Return a specific submodel descriptor | `GET http://localhost:8083/api/v3.1/submodel-descriptors/{submodelIdentifier}` |
+| **PutSubmodelDescriptorById** | Create or update a specific submodel descriptor | `PUT http://localhost:8083/api/v3.1/submodel-descriptors/{submodelIdentifier}` |
+| **DeleteSubmodelDescriptorById** | Delete a specific submodel descriptor | `DELETE http://localhost:8083/api/v3.1/submodel-descriptors/{submodelIdentifier}` |
+| **GetDescription** | Return the self‑description of the submodel registry service | `GET http://localhost:8083/api/v3.1/description` |
@@ -51,7 +51,7 @@ $ docker compose -f compose.dev.yml up
```
Input files are read from `./input` and stored persistently under `./storage` on your host system.
-The server can be accessed at http://localhost:8083/api/v3.1.1/ from your host system.
+The server can be accessed at http://localhost:8083/api/v3.1/ from your host system.
To get a different setup, the `compose.yml` (or `compose.dev.yml`) file can be adapted using the options described in the main server [README.md](../../README.md#options).
Note that `compose.dev.yml` builds the image from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
diff --git a/server/example_configurations/repository_standalone/README.md b/server/example_configurations/repository_standalone/README.md
index 9c45c930..d415cc8a 100644
--- a/server/example_configurations/repository_standalone/README.md
+++ b/server/example_configurations/repository_standalone/README.md
@@ -11,7 +11,7 @@ $ docker compose -f compose.dev.yml up
```
Input files are read from `./input` and stored persistently under `./storage` on your host system.
-The server can be accessed at http://localhost:8080/api/v3.0/ from your host system.
+The server can be accessed at http://localhost:8080/api/v3.1/ from your host system.
To get a different setup, the `compose.yml` (or `compose.dev.yml`) file can be adapted using the options described in the main server [README.md](../../README.md#options).
Note that `compose.dev.yml` builds the image from the `server` directory. The local `sdk` directory is passed in as an additional build context named `sdk`.
From 8a038e19864a0921bc85cf54d35c430fa326c2a0 Mon Sep 17 00:00:00 2001
From: s-heppner
Date: Fri, 13 Nov 2026 13:49:51 +0100
Subject: [PATCH 3/7] server: Give example compose projects distinct names
Previously, the repository and discovery examples both used the
compose project name `basyx-python-server` with a service called
`app`, and the registry example set no name at all. Starting one
example with `docker compose up` therefore replaced the container of
the other.
Each standalone example now uses its own project name
(`basyx-python-repository`, `basyx-python-registry`,
`basyx-python-discovery`), in both `compose.yml` and
`compose.dev.yml`, so they can run side by side.
---
.../example_configurations/discovery_standalone/compose.dev.yml | 2 +-
server/example_configurations/discovery_standalone/compose.yml | 2 +-
.../example_configurations/registry_standalone/compose.dev.yml | 1 +
server/example_configurations/registry_standalone/compose.yml | 1 +
.../repository_standalone/compose.dev.yml | 2 +-
server/example_configurations/repository_standalone/compose.yml | 2 +-
6 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/server/example_configurations/discovery_standalone/compose.dev.yml b/server/example_configurations/discovery_standalone/compose.dev.yml
index 6682b0a5..c72ecb58 100644
--- a/server/example_configurations/discovery_standalone/compose.dev.yml
+++ b/server/example_configurations/discovery_standalone/compose.dev.yml
@@ -1,4 +1,4 @@
-name: basyx-python-server
+name: basyx-python-discovery
services:
app:
build:
diff --git a/server/example_configurations/discovery_standalone/compose.yml b/server/example_configurations/discovery_standalone/compose.yml
index 46990b4c..d1d337a8 100644
--- a/server/example_configurations/discovery_standalone/compose.yml
+++ b/server/example_configurations/discovery_standalone/compose.yml
@@ -1,4 +1,4 @@
-name: basyx-python-server
+name: basyx-python-discovery
services:
app:
image: eclipsebasyx/basyx-python-discovery:latest
diff --git a/server/example_configurations/registry_standalone/compose.dev.yml b/server/example_configurations/registry_standalone/compose.dev.yml
index 6f8e6a82..3d3e9f75 100644
--- a/server/example_configurations/registry_standalone/compose.dev.yml
+++ b/server/example_configurations/registry_standalone/compose.dev.yml
@@ -1,3 +1,4 @@
+name: basyx-python-registry
services:
app:
build:
diff --git a/server/example_configurations/registry_standalone/compose.yml b/server/example_configurations/registry_standalone/compose.yml
index ea49877e..b5327c55 100644
--- a/server/example_configurations/registry_standalone/compose.yml
+++ b/server/example_configurations/registry_standalone/compose.yml
@@ -1,3 +1,4 @@
+name: basyx-python-registry
services:
app:
image: eclipsebasyx/basyx-python-registry:latest
diff --git a/server/example_configurations/repository_standalone/compose.dev.yml b/server/example_configurations/repository_standalone/compose.dev.yml
index a81e5991..cfedaf99 100644
--- a/server/example_configurations/repository_standalone/compose.dev.yml
+++ b/server/example_configurations/repository_standalone/compose.dev.yml
@@ -1,4 +1,4 @@
-name: basyx-python-server
+name: basyx-python-repository
services:
app:
build:
diff --git a/server/example_configurations/repository_standalone/compose.yml b/server/example_configurations/repository_standalone/compose.yml
index 2d4c002a..2810f7ac 100644
--- a/server/example_configurations/repository_standalone/compose.yml
+++ b/server/example_configurations/repository_standalone/compose.yml
@@ -1,4 +1,4 @@
-name: basyx-python-server
+name: basyx-python-repository
services:
app:
image: eclipsebasyx/basyx-python-repository:latest
From 057ac27e20e1da8cf25998df688c9d2effe46dfa Mon Sep 17 00:00:00 2001
From: s-heppner
Date: Fri, 13 Nov 2026 13:49:51 +0100
Subject: [PATCH 4/7] Align example configuration READMEs
Previously, the header and separator rows of the AAS Registry table in
the registry README were still padded for the old `/api/v3.1.1/` URLs,
and the repository README named its image without the `:latest` tag,
unlike the registry and discovery READMEs.
This realigns the table and adds the missing tag.
---
server/example_configurations/registry_standalone/README.md | 4 ++--
server/example_configurations/repository_standalone/README.md | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/server/example_configurations/registry_standalone/README.md b/server/example_configurations/registry_standalone/README.md
index 1358d9e2..b88eb46d 100644
--- a/server/example_configurations/registry_standalone/README.md
+++ b/server/example_configurations/registry_standalone/README.md
@@ -11,8 +11,8 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su
## Features
# AAS Registry:
-| Function | Description | Example URL |
-|--------------------------------------------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| Function | Description | Example URL |
+|--------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors` |
| **GetAssetAdministrationShellDescriptorById** | Return a specific AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
| **PostAssetAdministrationShellDescriptor** | Register/create a new AAS descriptor | `POST http://localhost:8083/api/v3.1/shell-descriptors` |
diff --git a/server/example_configurations/repository_standalone/README.md b/server/example_configurations/repository_standalone/README.md
index d415cc8a..7f10ac77 100644
--- a/server/example_configurations/repository_standalone/README.md
+++ b/server/example_configurations/repository_standalone/README.md
@@ -1,6 +1,6 @@
# Repository Standalone
This example Docker compose configuration runs a repository server using the pre-built
-`eclipsebasyx/basyx-python-repository` image from [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-repository):
+`eclipsebasyx/basyx-python-repository:latest` image from [DockerHub](https://hub.docker.com/r/eclipsebasyx/basyx-python-repository):
```
$ docker compose up
```
From aad822929530f1eed1d544729120a4e95946d3f2 Mon Sep 17 00:00:00 2001
From: s-heppner
Date: Fri, 13 Nov 2026 13:49:52 +0100
Subject: [PATCH 5/7] server: Add `combined` example configuration
Previously, the example configurations only ran a single service each.
Users who wanted the repository, registry and discovery servers
together had to start three separate compose projects.
This adds `example_configurations/combined`, which runs all three
services from one `compose.yml` using the pre-built DockerHub images,
and from one `compose.dev.yml` that builds them locally. Each service
stores its data in its own directory, which is added to `.gitignore`.
The server `README.md` now lists the new example and explains the
difference between `compose.yml` and `compose.dev.yml`.
Fixes #640
---
.gitignore | 5 +++
server/README.md | 3 ++
.../example_configurations/combined/README.md | 35 +++++++++++++++
.../combined/compose.dev.yml | 43 +++++++++++++++++++
.../combined/compose.yml | 28 ++++++++++++
5 files changed, 114 insertions(+)
create mode 100644 server/example_configurations/combined/README.md
create mode 100644 server/example_configurations/combined/compose.dev.yml
create mode 100644 server/example_configurations/combined/compose.yml
diff --git a/.gitignore b/.gitignore
index 1efa31ac..de9dc165 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,8 @@ server/example_configurations/repository_standalone/storage/
server/example_configurations/registry_standalone/input/
server/example_configurations/registry_standalone/storage/
server/example_configurations/discovery_standalone/storage/
+server/example_configurations/combined/repository/input/
+server/example_configurations/combined/repository/storage/
+server/example_configurations/combined/registry/input/
+server/example_configurations/combined/registry/storage/
+server/example_configurations/combined/discovery/storage/
diff --git a/server/README.md b/server/README.md
index 9915971e..5d6b98ef 100644
--- a/server/README.md
+++ b/server/README.md
@@ -81,9 +81,12 @@ This implies the following start-up behaviour:
## Building and Running the Image with Docker Compose
Example configurations can be found in the `./example_configurations` directory.
+Each example has a `compose.yml` that pulls the pre-built images from DockerHub (`docker compose up`)
+and a `compose.dev.yml` that builds the images locally from source (`docker compose -f compose.dev.yml up`).
Currently, we offer:
+- [combined](example_configurations/combined/README.md): Repository, registry and discovery server together
- [repository_standalone](example_configurations/repository_standalone/README.md): Standalone repository server
- [registry_standalone](example_configurations/registry_standalone/README.md): Standalone registry server
- [discovery_standalone](example_configurations/discovery_standalone/README.md): Standalone discovery server
diff --git a/server/example_configurations/combined/README.md b/server/example_configurations/combined/README.md
new file mode 100644
index 00000000..6ed83b18
--- /dev/null
+++ b/server/example_configurations/combined/README.md
@@ -0,0 +1,35 @@
+# Combined
+This example Docker compose configuration runs the repository, registry and discovery servers together, using the
+pre-built images from DockerHub:
+
+- [`eclipsebasyx/basyx-python-repository:latest`](https://hub.docker.com/r/eclipsebasyx/basyx-python-repository)
+- [`eclipsebasyx/basyx-python-registry:latest`](https://hub.docker.com/r/eclipsebasyx/basyx-python-registry)
+- [`eclipsebasyx/basyx-python-discovery:latest`](https://hub.docker.com/r/eclipsebasyx/basyx-python-discovery)
+
+```
+$ docker compose up
+```
+
+To build the images locally from source instead, use `compose.dev.yml`. This is usually only necessary for development:
+```
+$ docker compose -f compose.dev.yml up
+```
+
+The servers can be accessed from your host system at:
+
+| Service | URL | Input | Storage |
+|------------|--------------------------------|----------------------|------------------------|
+| Repository | http://localhost:8080/api/v3.1 | `./repository/input` | `./repository/storage` |
+| Registry | http://localhost:8083/api/v3.1 | `./registry/input` | `./registry/storage` |
+| Discovery | http://localhost:8084/api/v3.1 | - | `./discovery/storage` |
+
+Each service stores its data persistently in its own directory on your host system.
+For the available endpoints of each service, see the
+[repository](../repository_standalone/README.md), [registry](../registry_standalone/README.md) and
+[discovery](../discovery_standalone/README.md) examples.
+To get a different setup, the `compose.yml` (or `compose.dev.yml`) file can be adapted using the options described in
+the main server [README.md](../../README.md#options).
+
+Note that `compose.dev.yml` builds the images from the `server` directory. The local `sdk` directory is passed in as an
+additional build context named `sdk`. To include the package license, a second additional build context `license`
+passes in the repository root.
diff --git a/server/example_configurations/combined/compose.dev.yml b/server/example_configurations/combined/compose.dev.yml
new file mode 100644
index 00000000..7b7a29f6
--- /dev/null
+++ b/server/example_configurations/combined/compose.dev.yml
@@ -0,0 +1,43 @@
+name: basyx-python-server
+services:
+ repository:
+ build:
+ context: ../..
+ additional_contexts:
+ - sdk=../../../sdk
+ - license=../../..
+ dockerfile: ./docker/repository/Dockerfile
+ ports:
+ - "8080:80"
+ volumes:
+ - ./repository/input:/input
+ - ./repository/storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
+ registry:
+ build:
+ context: ../..
+ additional_contexts:
+ - sdk=../../../sdk
+ - license=../../..
+ dockerfile: ./docker/registry/Dockerfile
+ ports:
+ - "8083:80"
+ volumes:
+ - ./registry/input:/input
+ - ./registry/storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
+ discovery:
+ build:
+ context: ../..
+ additional_contexts:
+ - sdk=../../../sdk
+ - license=../../..
+ dockerfile: ./docker/discovery/Dockerfile
+ ports:
+ - "8084:80"
+ environment:
+ storage_path: /storage/discovery_store.json
+ volumes:
+ - ./discovery/storage:/storage
diff --git a/server/example_configurations/combined/compose.yml b/server/example_configurations/combined/compose.yml
new file mode 100644
index 00000000..d09d848c
--- /dev/null
+++ b/server/example_configurations/combined/compose.yml
@@ -0,0 +1,28 @@
+name: basyx-python-server
+services:
+ repository:
+ image: eclipsebasyx/basyx-python-repository:latest
+ ports:
+ - "8080:80"
+ volumes:
+ - ./repository/input:/input
+ - ./repository/storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
+ registry:
+ image: eclipsebasyx/basyx-python-registry:latest
+ ports:
+ - "8083:80"
+ volumes:
+ - ./registry/input:/input
+ - ./registry/storage:/storage
+ environment:
+ STORAGE_PERSISTENCY: True
+ discovery:
+ image: eclipsebasyx/basyx-python-discovery:latest
+ ports:
+ - "8084:80"
+ environment:
+ storage_path: /storage/discovery_store.json
+ volumes:
+ - ./discovery/storage:/storage
From 613e54e1c71a13eb22e33848db349dd0a084f6dd Mon Sep 17 00:00:00 2001
From: s-heppner
Date: Fri, 13 Nov 2026 13:49:52 +0100
Subject: [PATCH 6/7] CI: Add `server-compose-check` job
Previously, no CI job looked at the compose files in
`server/example_configurations`, so broken or outdated example
configurations went unnoticed.
The new job runs `docker compose config --quiet` on every
`compose*.yml` file in that directory, which catches both invalid YAML
and invalid compose keys. It fails if no compose files are found, so
moving the directory cannot silently disable the check.
---
.github/workflows/pr.yml | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 7287c29a..fd029aba 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -371,6 +371,26 @@ jobs:
run: |
python -m ruff check
+ server-compose-check:
+ # This job checks that all Docker compose files in the server's example configurations are valid
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: ./server/example_configurations
+ steps:
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 #v5.1.0
+ - name: Validate compose files
+ run: |
+ mapfile -t files < <(find . -name 'compose*.yml' | sort)
+ if [[ ${#files[@]} -eq 0 ]]; then
+ echo "::error::No compose files found"
+ exit 1
+ fi
+ for file in "${files[@]}"; do
+ echo "Checking $file"
+ docker compose -f "$file" config --quiet
+ done
+
server-docker:
# This job tests for all three server profiles, if the docker image is built successfully, a container
# can be started and the server sends a `200 OK` response on the mandatory /description endpoint
From 3b3b277a78f491b6d71d3ad979e279e11663019c Mon Sep 17 00:00:00 2001
From: s-heppner
Date: Wed, 18 Nov 2026 11:06:35 +0100
Subject: [PATCH 7/7] server: Fix headings and wording in registry README
Previously, the `AAS Registry` and `Submodel Registry` headings in the
registry README were H1 headings with a trailing colon, although they
belong to the `Features` section. One table row also said "Return all
AAS descriptor".
This change turns them into H3 headings without the colon and fixes the
plural.
---
server/example_configurations/registry_standalone/README.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/server/example_configurations/registry_standalone/README.md b/server/example_configurations/registry_standalone/README.md
index b88eb46d..ac2a7ba5 100644
--- a/server/example_configurations/registry_standalone/README.md
+++ b/server/example_configurations/registry_standalone/README.md
@@ -10,10 +10,10 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su
## Features
-# AAS Registry:
+### AAS Registry
| Function | Description | Example URL |
|--------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
-| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors` |
+| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptors | `GET http://localhost:8083/api/v3.1/shell-descriptors` |
| **GetAssetAdministrationShellDescriptorById** | Return a specific AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
| **PostAssetAdministrationShellDescriptor** | Register/create a new AAS descriptor | `POST http://localhost:8083/api/v3.1/shell-descriptors` |
| **PutAssetAdministrationShellDescriptorById** | Create or update an existing AAS descriptor | `PUT http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}` |
@@ -25,7 +25,7 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su
| **DeleteSubmodelDescriptorThroughSuperPath** | Delete a specific submodel descriptor under AAS descriptor | `DELETE http://localhost:8083/api/v3.1/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}` |
| **GetDescription** | Return the self‑description of the AAS registry service | `GET http://localhost:8083/api/v3.1/description` |
-# Submodel Registry:
+### Submodel Registry
| Function | Description | Example URL |
|----------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------|
| **GetAllSubmodelDescriptors** | Return all submodel descriptors | `GET http://localhost:8083/api/v3.1/submodel-descriptors` |