Skip to content

server: Add image:-based example compose files - #659

Merged
s-heppner merged 7 commits into
eclipse-basyx:developfrom
rwth-iat:improve/example-configs-use-published-images
Nov 18, 2026
Merged

s-heppner merged 7 commits into
eclipse-basyx:developfrom
rwth-iat:improve/example-configs-use-published-images

Conversation

@paul-gerber-svg

@paul-gerber-svg paul-gerber-svg commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Previously, the example configurations in example_configurations/ only had a compose.dev.yml, which builds the image from source. The READMEs named the pre-built DockerHub images, but no compose file used them. In addition:

  • The repository and registry READMEs used the outdated API base paths /api/v3.0/ and /api/v3.1.1/ instead of /api/v3.1.
  • The repository and discovery examples shared the compose project name basyx-python-server, so starting one replaced the container of the other.
  • To run all three services together, users had to start three separate compose projects.
  • No CI job checked the compose files.

This change:

  • Adds a compose.yml per standalone example that pulls the matching eclipsebasyx/basyx-python-*:latest image. docker compose up now uses the published image, and compose.dev.yml stays the way to build from source.
  • Gives each standalone example its own compose project name.
  • Adds a combined example that runs the repository, registry and discovery services from one compose project, with both a compose.yml and a compose.dev.yml.
  • Fixes the API base paths in the READMEs and aligns their tables, image tags, headings and wording.
  • Adds the server-compose-check CI job, which runs docker compose config --quiet on every compose*.yml file in server/example_configurations.

Fixes #640

paul-gerber-svg and others added 6 commits October 8, 2026 18:05
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 eclipse-basyx#640
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.
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.
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 eclipse-basyx#640
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.
@s-heppner
s-heppner requested a review from zrgt November 13, 2026 12:52
| **GetDescription** | Return the self‑description of the AAS registry service | `GET http://localhost:8083/api/v3.1.1/description` |
| Function | Description | Example URL |
|--------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| **GetAllAssetAdministrationShellDescriptors** | Return all AAS descriptor | `GET http://localhost:8083/api/v3.1/shell-descriptors` |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, pre-existing and optional since you are touching this table anyway: "Return all AAS descriptor" → "Return all AAS descriptors". Also, # AAS Registry: and # Submodel Registry: are H1 headings under the ## Features section; ### (without the colon) would fit the document structure.

@zrgt

zrgt commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Tested locally at 613e54e (Docker 29.8.2, Compose v5.6.0, macOS). Everything works as described.

Test Result
combined/compose.yml with the DockerHub images (latest = 2.2.0) All 3 services return 200 on /api/v3.1/description
/shells, /shell-descriptors, /submodel-descriptors 200
Old base path /api/v3.1.1/description 404, so the README path fix is correct
POST a shell (repository), a shell descriptor (registry) and an asset link (discovery), then docker compose restart All data still there
Same after docker compose down + up All data still there
Data files in combined/*/storage/ Written, and git status stays clean
Each standalone compose.yml 200
All three standalone examples at the same time Works, thanks to the distinct project names
combined/compose.dev.yml up --build All 3 images build and return 200; they read the data written by the published images

Not tested: the standalone compose.dev.yml files (same build settings as the combined one) and arm64.

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.
@s-heppner s-heppner changed the title server: Add image:-based compose files alongside compose.dev.yml server: Add image:-based example compose files Nov 18, 2026
@s-heppner
s-heppner merged commit 00e31b4 into eclipse-basyx:develop Nov 18, 2026
21 checks passed
@s-heppner
s-heppner deleted the improve/example-configs-use-published-images branch November 18, 2026 10:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants