Skip to content

README.md

Latest commit

 

History

History
132 lines (92 loc) · 8.34 KB

README.md

File metadata and controls

132 lines (92 loc) · 8.34 KB

Eclipse BaSyx Python SDK - HTTP Server

This package contains a Dockerfile to spin up an exemplary HTTP/REST server following the Specification of the AAS Part 2 API with ease. The server currently implements the following interfaces:

It uses the HTTP API and the AASX, JSON, and XML Adapters of the BaSyx Python SDK, to serve regarding files from a given directory. The files are only read, changes won't persist.

Alternatively, the container can also be told to use the Local-File Backend instead, which stores Asset Administration Shells (AAS) and Submodels as individual JSON files and allows for persistent changes (except supplementary files, i.e. files referenced by File SubmodelElements). See below on how to configure this.

Building

The container image can be built via:

$ docker build -t basyx-python-server -f Dockerfile ..

Note that when cloning this repository on Windows, Git may convert the line separators to CRLF. This breaks entrypoint.sh and stop-supervisor.sh. Ensure both files use LF line separators (\n) before building.

Running

Storage

The server makes use of two directories:

  • /input - start-up data: Directory from which the server loads AAS and Submodel files in AASX, JSON or XML format during start-up. The server will not modify these files.
  • /storage - persistent store: Directory where all AAS and Submodels are stored as individual JSON files if the server is configured for persistence. The server will modify these files.

The directories can be mapped via the -v option from another image or a local directory. To mount the host directories into the container, -v ./input:/input -v ./storage:/storage can be used. Both local directories ./input and ./storage will be created in the current working directory, if they don't already exist.

Port

The HTTP server inside the container listens on port 80 by default. To expose it on the host on port 8080, use the option -p 8080:80 when running it.

Options

The container can be configured via environment variables. The most important ones are summarised below:

Variable Description Default
API_BASE_PATH Base path under which the API is served. /api/v3.0/
INPUT Path inside the container pointing to the directory from which the server takes its start-up data (AASX, JSON, XML). /input
STORAGE Path inside the container pointing to the directory used by the server to persistently store data (JSON). /storage
STORAGE_PERSISTENCY Flag to enable data persistence via the LocalFileBackend. AAS/Submodels are stored as JSON files in the directory specified by STORAGE. Supplementary files, i.e. files referenced by File SubmodelElements, are not stored. If disabled, any changes made via the API are only stored in memory. False
STORAGE_OVERWRITE Flag to enable storage overwrite if STORAGE_PERSISTENCY is enabled. Any AAS/Submodel from the INPUT directory already present in the LocalFileBackend replaces its existing version. If disabled, the existing version is kept. False

This implies the following start-up behaviour:

  • Any AAS/Submodel found in INPUT is loaded during start-up.
  • If STORAGE_PERSISTENCY = True:
    • Any AAS/Submodel not present in the LocalFileBackend is added to it.
    • Any AAS/Submodel already present is skipped, unless STORAGE_OVERWRITE = True, in which case it is replaced.
  • Supplementary files (e.g., File SubmodelElements) are never persisted by the LocalFileBackend.

Building and Running the Image with Docker Compose

Example configurations can be found in the ./example_configurations directory.

Currently, we offer:

Running without Docker (Debugging Only)

The server can also be run directly on the host system without Docker, NGINX and supervisord. Although this is not suitable for production, it may be useful for debugging.

Warning

Not supported for production systems!

  1. Install the local SDK and the local server package.

    $ pip install ../sdk
$ pip install ./app

  2. Run the server by executing the main function in ./app/interfaces/repository.py.

    $ python -m app.interfaces.repository

The server can be accessed at http://localhost:8080/api/v3.0/ from your host system.

Currently Unimplemented

Several features and routes are currently not supported:

  1. Correlation ID: Not implemented because it was deemed unnecessary for this server.

  2. Extent Parameter (withBlobValue/withoutBlobValue): Not implemented due to the lack of support in JSON/XML serialization.

  3. Route /shells/{aasIdentifier}/asset-information/thumbnail: Not implemented because the specification lacks clarity.

  4. Serialization and Description Routes:

    • /serialization
    • /description These routes are not implemented at this time.

  5. Value, Path, and PATCH Routes:

    • All /…/value$, /…/path$, and PATCH routes are currently not implemented.

  6. Operation Invocation Routes: The following routes are not implemented because operation invocation is not yet supported by the basyx-python-sdk:

    • POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke
    • POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke/$value
    • POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke-async
    • POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke-async/$value
    • GET /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-status/{handleId}
    • GET /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-results/{handleId}
    • GET /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-results/{handleId}/$value

Acknowledgments

This Dockerfile is inspired by the tiangolo/uwsgi-nginx-docker repository.