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 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 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.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 new file mode 100644 index 00000000..d1d337a8 --- /dev/null +++ b/server/example_configurations/discovery_standalone/compose.yml @@ -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 diff --git a/server/example_configurations/registry_standalone/README.md b/server/example_configurations/registry_standalone/README.md index b78ccae3..ac2a7ba5 100644 --- a/server/example_configurations/registry_standalone/README.md +++ b/server/example_configurations/registry_standalone/README.md @@ -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. 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 new file mode 100644 index 00000000..b5327c55 --- /dev/null +++ b/server/example_configurations/registry_standalone/compose.yml @@ -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 diff --git a/server/example_configurations/repository_standalone/README.md b/server/example_configurations/repository_standalone/README.md index 5413100b..7f10ac77 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:latest` 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). +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 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.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 new file mode 100644 index 00000000..2810f7ac --- /dev/null +++ b/server/example_configurations/repository_standalone/compose.yml @@ -0,0 +1,11 @@ +name: basyx-python-repository +services: + app: + image: eclipsebasyx/basyx-python-repository:latest + ports: + - "8080:80" + volumes: + - ./input:/input + - ./storage:/storage + environment: + STORAGE_PERSISTENCY: True