Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
3 changes: 3 additions & 0 deletions server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
35 changes: 35 additions & 0 deletions server/example_configurations/combined/README.md
Original file line number Diff line number Diff line change
@@ -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:
Comment thread
zrgt marked this conversation as resolved.
Resolved

| 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.
43 changes: 43 additions & 0 deletions server/example_configurations/combined/compose.dev.yml
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions server/example_configurations/combined/compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: basyx-python-server
services:
repository:
image: eclipsebasyx/basyx-python-repository:latest
Comment thread
zrgt marked this conversation as resolved.
Resolved
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
15 changes: 9 additions & 6 deletions server/example_configurations/discovery_standalone/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,24 @@ 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

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.

Expand All @@ -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.
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: basyx-python-server
name: basyx-python-discovery
services:
app:
build:
Expand Down
10 changes: 10 additions & 0 deletions server/example_configurations/discovery_standalone/compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
name: basyx-python-discovery
services:
app:
image: eclipsebasyx/basyx-python-discovery:latest
ports:
- "8084:80"
environment:
storage_path: /storage/discovery_store.json
volumes:
- ./storage:/storage
61 changes: 32 additions & 29 deletions server/example_configurations/registry_standalone/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,46 +10,49 @@ The Registry Service provides the endpoint for a given AAS-ID or Submodel-ID. Su


## Features
# 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` |

# Submodel Registry:
### AAS Registry
| Function | Description | Example URL |
|--------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| **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}` |
| **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` |



## 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).
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 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.
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
name: basyx-python-registry
services:
app:
build:
Expand Down
11 changes: 11 additions & 0 deletions server/example_configurations/registry_standalone/compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
name: basyx-python-registry
services:
app:
image: eclipsebasyx/basyx-python-registry:latest
ports:
- "8083:80"
volumes:
- ./input:/input
- ./storage:/storage
environment:
STORAGE_PERSISTENCY: True
Loading
Loading