From 418d7f565a8624f55b2392dfd37033786e05c7bc Mon Sep 17 00:00:00 2001 From: ChKoort <148854629+ChKoort@users.noreply.github.com> Date: Mon, 11 Nov 2024 13:36:55 +0100 Subject: [PATCH] Adds documentation for creating and using virtual machine images of BaSyx components (#24) * Add documentation for the creation and usage of virtual machine images of BaSyx components * Change links * Fix link * Fix links * Fix links * Change structure * Fix links * Fix typos * Fix typos * Add missing documentation --- .../v2/aas_discovery/index.md | 6 + .../v2/aas_environment/index.md | 5 + .../basyx_components/v2/aas_registry/index.md | 5 + .../v2/aas_repository/index.md | 5 + .../v2/cd_repository/index.md | 5 + .../v2/submodel_registry/index.md | 5 + .../v2/submodel_repository/index.md | 5 + ...ine_virtualmachine_setup_dev_all_in_one.md | 98 +++++++++++++++++ ...ine_virtualmachine_setup_dev_base_image.md | 103 ++++++++++++++++++ ...ualmachine_setup_dev_component_specific.md | 68 ++++++++++++ .../index.md | 11 ++ .../developer/basyx_java_v2/index.md | 8 +- .../user_tutorials/index.md | 2 + .../alpine_virtualmachine_setup_use.md | 70 ++++++++++++ 14 files changed, 394 insertions(+), 2 deletions(-) create mode 100644 docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_all_in_one.md create mode 100644 docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_base_image.md create mode 100644 docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_component_specific.md create mode 100644 docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/index.md create mode 100644 docs/source/content/user_documentation/user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md diff --git a/docs/source/content/user_documentation/basyx_components/v2/aas_discovery/index.md b/docs/source/content/user_documentation/basyx_components/v2/aas_discovery/index.md index dd9b620..52ce1fe 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/aas_discovery/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/aas_discovery/index.md @@ -91,6 +91,12 @@ In this example, configuration files are located in `C:/tmp` ```{warning} The binding of volume `C:/tmp/application.properties` to `/application/application.properties` is tested using Windows Powershell. Other terminals might run into an error. ``` + +## Virtual Machine +Eclipse BaSyx provides the AAS Discovery Service as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Swagger UI In the Swagger UI, you can find the API documentation for the AAS Discovery Service. diff --git a/docs/source/content/user_documentation/basyx_components/v2/aas_environment/index.md b/docs/source/content/user_documentation/basyx_components/v2/aas_environment/index.md index 9ecfb36..1a778f5 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/aas_environment/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/aas_environment/index.md @@ -148,6 +148,11 @@ Eclipse BaSyx provides the AAS Environment as off-the-shelf component via Docker docker run --name=aas-env -p:8081:8081 -v C:/path/to/application.properties:/application/application.properties eclipsebasyx/aas-environment:2.0.0-SNAPSHOT ``` +## Virtual Machine +Eclipse BaSyx provides the AAS Environment as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Swagger UI In the Swagger UI, you can find the API documentation for the AAS Environment. diff --git a/docs/source/content/user_documentation/basyx_components/v2/aas_registry/index.md b/docs/source/content/user_documentation/basyx_components/v2/aas_registry/index.md index c779b11..b473be8 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/aas_registry/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/aas_registry/index.md @@ -102,6 +102,11 @@ aas-registry: restart: always ``` +## Virtual Machine +Eclipse BaSyx provides the AAS Registry as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. At the moment, only the version that logs registry events and uses an in-memory storage is available as a virtual machine image. So, it is not possible to use Apache Kafka as event sink or MongoDB as storage. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Build Resources diff --git a/docs/source/content/user_documentation/basyx_components/v2/aas_repository/index.md b/docs/source/content/user_documentation/basyx_components/v2/aas_repository/index.md index d7e46ed..7711880 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/aas_repository/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/aas_repository/index.md @@ -119,6 +119,11 @@ Eclipse BaSyx provides the AAS Repository as off-the-shelf component via DockerH docker run --name=aas-repo -p:8081:8081 -v C:/path/to/application.properties:/application/application.properties eclipsebasyx/aas-repository:2.0.0-SNAPSHOT ``` +## Virtual Machine +Eclipse BaSyx provides the AAS Repository as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Swagger UI In the Swagger UI, you can find the API documentation for the AAS Repository. diff --git a/docs/source/content/user_documentation/basyx_components/v2/cd_repository/index.md b/docs/source/content/user_documentation/basyx_components/v2/cd_repository/index.md index d2bb692..f5c31cb 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/cd_repository/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/cd_repository/index.md @@ -96,6 +96,11 @@ Eclipse BaSyx provides the Concept Description Repository as off-the-shelf compo docker run --name=cd-repo -p:8081:8081 -v C:/path/to/application.properties:/application/application.properties eclipsebasyx/conceptdescription-repository:2.0.0-SNAPSHOT ``` +## Virtual Machine +Eclipse BaSyx provides the Concept Description Repository as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Swagger UI In the Swagger UI, you can find the API documentation for the Concept Description Repository. diff --git a/docs/source/content/user_documentation/basyx_components/v2/submodel_registry/index.md b/docs/source/content/user_documentation/basyx_components/v2/submodel_registry/index.md index 51a957f..899518b 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/submodel_registry/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/submodel_registry/index.md @@ -96,6 +96,11 @@ sm-registry: restart: always ``` +## Virtual Machine +Eclipse BaSyx provides the Submodel Registry as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. At the moment, only the version that logs registry events and uses an in-memory storage is available as a virtual machine image. So, it is not possible to use Apache Kafka as event sink or MongoDB as storage. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Build Resources diff --git a/docs/source/content/user_documentation/basyx_components/v2/submodel_repository/index.md b/docs/source/content/user_documentation/basyx_components/v2/submodel_repository/index.md index 7498eaa..d0dca89 100644 --- a/docs/source/content/user_documentation/basyx_components/v2/submodel_repository/index.md +++ b/docs/source/content/user_documentation/basyx_components/v2/submodel_repository/index.md @@ -106,6 +106,11 @@ Eclipse BaSyx provides the Submodel Repository as off-the-shelf component via Do docker run --name=sm-repo -p:8081:8081 -v C:/path/to/application.properties:/application/application.properties eclipsebasyx/submodel-repository:2.0.0-SNAPSHOT ``` +## Virtual Machine +Eclipse BaSyx provides the Submodel Repository as a virtual machine image for Oracle VirtualBox and VMware Workstation Player. + +The image can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu). How to use it is described [here](../../../user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md). + ## Swagger UI In the Swagger UI, you can find the API documentation for the Submodel Repository. diff --git a/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_all_in_one.md b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_all_in_one.md new file mode 100644 index 0000000..f70208d --- /dev/null +++ b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_all_in_one.md @@ -0,0 +1,98 @@ +# All Components +This tutorial explains how the virtual machine containing all of [these](../../../basyx_components/v2/index.md) components is created based on the base image described [here](./alpine_virtualmachine_setup_dev_base_image.md). + +## Virtual Box +### Import the Base Image +Import the machine (*File -> Import Appliance*) with the following settings: +- Tick only the network adapter checkbox. +- MAC Address Policy: Include only NAT network adapter MAC addresses. + + +### Create a Shared Folder +Create a shared folder called *SharedFolder* on the host system that has the following subfolders: +- aasdiscoveryservice +- aasenvironment +- aasregistry_service_release_log_mem +- aasrepository +- conceptdescriptionrepository +- submodelregistry_service_release_log_mem +- submodelrepository + +Add this folder as a shared folder under *Settings -> Shared Folders*. + + +### Enable Port Forwarding +Create for every component a new entry in the port forwarding list (*Settings -> Network -> Adapter 1 -> Advanced -> Port Forwarding*) with the following properties: +- Host IP: 127.0.0.1 +- Host Port: \ +- Guest IP: 10.0.2.15 +- Guest Port: \ + +For the registry components, the port number can be seen in the respective startup script. For the other components, the port number is set in the respective *application.properties* file. + + +## Alpine Linux +The scripts used in the following can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu?path=%2Fdevelopment%2FAllComponentsInOneVM%2FScripts). + + +### Place the General Shell Scripts on the Virtual Machine +Place *basyx_components_setup.sh* and *basyx_components_startup.sh* in the shared folder on the host system and execute: + + mv /mnt/shared/basyx_components_setup.sh /home/basyx_components_setup.sh + mv /mnt/shared/basyx_components_startup.sh /home/basyx_components_startup.sh + + +### Activate Automatic Execution of the General Scripts +Add the following lines to *crontab -e* to the already existing line from the base image setup: + + @reboot && /bin/sh /home/basyx_components_setup.sh ; /bin/sh /home/basyx_components_startup.sh + + +### Create for Each Component a Folder on the Virtual Machine +Execute: + + mkdir /home/basyx_aasdiscoveryservice + mkdir /home/basyx_aasenvironment + mkdir /home/basyx_aasregistry_service_release_log_mem + mkdir /home/basyx_aasrepository + mkdir /home/basyx_conceptdescriptionrepository + mkdir /home/basyx_submodelregistry_service_release_log_mem + mkdir /home/basyx_submodelrepository + + +### Place the Component Specific Shell Scripts on the Virtual Machine +Place *\_startup.sh* for each component in the shared folder on the host system and execute: + + mv /mnt/shared/basyx_aasdiscoveryservice_startup.sh /home/basyx_aasdiscoveryservice + mv /mnt/shared/basyx_aasenvironment_startup.sh /home/basyx_aasenvironment + mv /mnt/shared/basyx_aasregistry_service_release_log_mem_startup.sh /home/basyx_aasregistry_service_release_log_mem + mv /mnt/shared/basyx_aasrepository_startup.sh /home/basyx_aasrepository + mv /mnt/shared/basyx_conceptdescriptionrepository_startup.sh /home/basyx_conceptdescriptionrepository + mv /mnt/shared/basyx_submodelregistry_service_release_log_mem_startup.sh /home/basyx_submodelregistry_service_release_log_mem + mv /mnt/shared/basyx_submodelrepository_startup.sh /home/basyx_submodelrepository + + +### Place the Executables on the Virtual Machine +Place the *.jar* file of each component in the shared folder on the host system and execute: + + mv /mnt/shared/basyx.aasdiscoveryservice.component-2.0.0-SNAPSHOT-exec.jar /home/basyx_aasdiscoveryservice + mv /mnt/shared/basyx.aasenvironment.component-2.0.0-SNAPSHOT-exec /home/basyx_aasenvironment + mv /mnt/shared/basyx.aasregistry-service-release-log-mem-2.0.0-SNAPSHOT-exec /home/basyx_aasregistry_service_release_log_mem + mv /mnt/shared/basyx.aasrepository.component-2.0.0-SNAPSHOT-exec /home/basyx_aasrepository + mv /mnt/shared/basyx.conceptdescriptionrepository.component-2.0.0-SNAPSHOT-exec /home/basyx_conceptdescriptionrepository + mv /mnt/shared/basyx.submodelregistry-service-release-log-mem-2.0.0-SNAPSHOT-exec /home/basyx_submodelregistry_service_release_log_mem + mv /mnt/shared/basyx.submodelrepository.component-2.0.0-SNAPSHOT-exec /home/basyx_submodelrepository + + +### Place the Scripts for Printing Logs and Errors on the Virtual Machine (optional) +Place *show_errors.sh* and *show_logs.sh* in the shared folder on the host and execute: + + mv /mnt/shared/show_errors.sh /home/show_errors.sh + mv /mnt/shared/show_logs.sh /home/show_logs.sh + + +### Export the Virtual Machine +Export the machine as an *ova* file (*File -> Export Appliance*) with the following properties: +- Format: Open Virtualization Format 1.0 +- MAC Address Policy: Include only NAT network adapter MAC addresses. +- Appliance Settings: Tick only the network adapter checkbox. diff --git a/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_base_image.md b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_base_image.md new file mode 100644 index 0000000..20c0d44 --- /dev/null +++ b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_base_image.md @@ -0,0 +1,103 @@ +# Base Image +Based on this base image, the virtual machine images for [these](../../../basyx_components/v2/index.md) components can be created as described [here](./alpine_virtualmachine_setup_dev_component_specific.md) for the component specific images and [here](./alpine_virtualmachine_setup_dev_all_in_one.md) for an image containing all components. + +## VirtualBox +### Creation of the VM in VirtualBox +Download the .iso file from . Choose *x86_64* as architecture and *virtual* as image type. +Configuration steps in VirtualBox: +1. Create a new machine. +2. Choose the downloaded .iso file. +3. Choose as type *Linux* and as version *Other Linux (64-bit)*. +4. Choose 1024 MB of RAM and one core. +5. Choose *Do not add a hard disk*. +6. Finish the setup. +7. Create a virtual hard disk of type .vmdk of size 4 GB and attach it to the machine (*Settings -> Storage -> Controller: SATA*). Do **not** pre-allocate the the storage space. +8. Start the machine. + + +### Create a Shared Folder +Create a shared folder called *SharedFolder* on the host system and add this folder as a shared folder under *Settings -> Shared Folders*. + + +## Alpine Linux +### Alpine Linux Setup +When the system is started for the first time, different properties have to be set to finish system setup. +This can be done by executing `setup-alpine`. +- keymap: de +- hostname: localhost +- interface: eth0 +- ip address: dhcp +- manual network configuration: no +- root password: none +- timezone: Europe/Berlin +- proxy: none +- network time protocol: chrony +- mirror: fastest +- user: no +- ssh server: none +- disks: choose earlier created disk +- disk usage: sys +- erase disk: yes + +Then, shutdown the machine and deselect all options from the boot order except for the hard disk (*Settings -> System*). Now, restart the machine. + + +### Activate Community Repositories +To be able to install the VirtualBox Guest Additions and Eclipse Temurin, the community repositories have to be activated in */etc/apk/repositories*. Therefore, remove the *#* in front of them. + + +### Install Eclipse Temurin +Execute: + + wget -O /etc/apk/keys/adoptium.rsa.pub https://packages.adoptium.net/artifactory/api/security/keypair/public/repositories/apk + + echo 'https://packages.adoptium.net/artifactory/apk/alpine/main' >> /etc/apk/repositories + + apk update && apk upgrade + apk add temurin-17-jdk + +Source: + + +### Add a Shared Folder (VirtualBox) +Execute: + + mkdir -p /mnt/shared + apk add virtualbox-guest-additions linux-virt + modprobe -a vboxsf + mount -t vboxsf SharedFolder /mnt/shared + +Add to *crontab -e*: + + @reboot mount -t vboxsf SharedFolder /mnt/shared + + +### Add a Shared Folder (VMware player) +Execute: + + mkdir -p /mnt/shared + apk add open-vm-tools-hgfs + rc-service open-vm-tools start + rc-update add open-vm-tools boot + +Add to *crontab -e*: + + @reboot modprobe fuse && /usr/bin/vmhgfs-fuse .host:/SharedFolder /mnt/shared -o subtype=vmhgfs-fuse,allow_other + + +### Deactivate Login Request After Booting +Make the following changes to */etc/inittab*: +- Comment out: + + tty1::respawn:/sbin/getty 38400 tty1 + +- Add: + + tty1::respawn:/bin/sh + + +### Export the Virtual Machine +Export the machine as an *ova* file (*File -> Export Appliance*) with the following properties: +- Format: Open Virtualization Format 1.0 +- MAC Address Policy: Include only NAT network adapter MAC addresses. +- Appliance Settings: Tick only the network adapter checkbox. diff --git a/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_component_specific.md b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_component_specific.md new file mode 100644 index 0000000..c0e6c40 --- /dev/null +++ b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/alpine_virtualmachine_setup_dev_component_specific.md @@ -0,0 +1,68 @@ +# Single Component +This tutorial explains how a virtual machine for one of [these](../../../basyx_components/v2/index.md) components is created based on the base image described [here](./alpine_virtualmachine_setup_dev_base_image.md). + + +## VirtualBox +### Import the base image +Import the machine (*File -> Import Appliance*) with the following settings: +- Tick only the network adapter checkbox. +- MAC Address Policy: Include only NAT network adapter MAC addresses. + + +### Create a Component Specific Folder in the Shared Folder +Create a folder called *SharedFolder* on the host system and change the shared folder path under *Settings -> Shared Folders* to the new folder. In this new folder, create a component specific folder with one of the following names depending on the desired component: +- aasdiscoveryservice +- aasenvironment +- aasregistry_service_release_log_mem +- aasrepository +- conceptdescriptionrepository +- submodelregistry_service_release_log_mem +- submodelrepository + + +### Enable Port Forwarding (for VirtualBox) +Create a new entry in the port forwarding list (*Settings -> Network -> Adapter 1 -> Advanced -> Port Forwarding*) with the following properties: +- Host IP: 127.0.0.1 +- Host Port: \ +- Guest IP: 10.0.2.15 +- Guest Port: \ + + +## Alpine Linux +The scripts used in the following can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu?path=%2Fdevelopment%2FComponentSpecificVM%2FScripts). + + +### Create a Component Folder on the Virtual Machine +Execute: + + mkdir /home/basyx_ + + +### Place the Setup and Startup Scripts on the Virtual Machine +Place *basyx_\\_setup.sh* and *basyx_\_startup.sh* in the shared folder on the host system and execute: + + mv /mnt/shared/basyx__setup.sh /home/basyx_ + mv /mnt/shared/basyx__startup.sh /home/basyx_ + +Registry components have only a startup script. + + +### Activate Automatic Execution of the Setup and Startup Scripts +Add the following lines to *crontab -e* to the already existing line from the base image setup: + + @reboot && /bin/sh /home/basyx_/basyx__setup.sh ; /bin/sh /home/basyx_/basyx__startup.sh > /dev/tty1 + +Registry components have only a startup script. + + +### Place the Executable on the Virtual Machine +Place the *.jar* file of the respective component in the shared folder on the host system and execute: + + mv /mnt/shared/.jar /home/basyx_ + + +### Export the Virtual Machine +Export the machine as an *ova* file (*File -> Export Appliance*) with the following properties: +- Format: Open Virtualization Format 1.0 +- MAC Address Policy: Include only NAT network adapter MAC addresses. +- Appliance Settings: Tick only the network adapter checkbox. diff --git a/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/index.md b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/index.md new file mode 100644 index 0000000..d1adb50 --- /dev/null +++ b/docs/source/content/user_documentation/developer/basyx_java_v2/alpine_virtualmachine_setup_dev_tutorials/index.md @@ -0,0 +1,11 @@ +# BaSyx Virtual Machine Creation +This section explains how the virtual machine images for [these](../../../basyx_components/v2/index.md) components can be created. Based on a [base image](./alpine_virtualmachine_setup_dev_base_image.md), the [component specific images](./alpine_virtualmachine_setup_dev_component_specific.md) and the [image containing all components](./alpine_virtualmachine_setup_dev_all_in_one.md) are created. + +```{toctree} +:hidden: +:maxdepth: 1 + +alpine_virtualmachine_setup_dev_base_image +alpine_virtualmachine_setup_dev_component_specific +alpine_virtualmachine_setup_dev_all_in_one +``` \ No newline at end of file diff --git a/docs/source/content/user_documentation/developer/basyx_java_v2/index.md b/docs/source/content/user_documentation/developer/basyx_java_v2/index.md index 32c0a5a..dea330f 100644 --- a/docs/source/content/user_documentation/developer/basyx_java_v2/index.md +++ b/docs/source/content/user_documentation/developer/basyx_java_v2/index.md @@ -1,18 +1,22 @@ # BaSyx Java V2 Documentation -This section provides in-depth documentation inteded for developers. If your goal is using the off-the-shelf components as-is, please refer to the [Components Documentation](../../basyx_components/v2/index.md). +This section provides in-depth documentation intended for developers. If your goal is using the off-the-shelf components as-is, please refer to the [Components Documentation](../../basyx_components/v2/index.md). Please note that this documentation is work-in-progress and will be extended continuously. The following documentation is available: * [Component Documentation](./components.md) * [Roadmap](./roadmap.md) * [Building Docker Images](./docker.md) +* [Creating Virtual Machine Images](./alpine_virtualmachine_setup_dev_tutorials/index.md) + + ```{toctree} :hidden: -:maxdepth: 1 +:maxdepth: 2 components roadmap docker management_endpoint +alpine_virtualmachine_setup_dev_tutorials/index ``` \ No newline at end of file diff --git a/docs/source/content/user_documentation/user_tutorials/index.md b/docs/source/content/user_documentation/user_tutorials/index.md index 191cf9e..a3f9d72 100644 --- a/docs/source/content/user_documentation/user_tutorials/index.md +++ b/docs/source/content/user_documentation/user_tutorials/index.md @@ -4,6 +4,7 @@ * [Downloading and Setting up Basyx](./download/index.md) * [Related Downloads](./relatedDownload/index.md) * [Databridge Automation Protocol Integration](databridge-PLC4X.md) +* [Using BaSyx Components with Virtual Machines](./virtualmachines/alpine_virtualmachine_setup_use.md) ```{toctree} @@ -14,5 +15,6 @@ download/index relatedDownload/index databridge-PLC4X +virtualmachines/alpine_virtualmachine_setup_use.md ``` \ No newline at end of file diff --git a/docs/source/content/user_documentation/user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md b/docs/source/content/user_documentation/user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md new file mode 100644 index 0000000..407ce31 --- /dev/null +++ b/docs/source/content/user_documentation/user_tutorials/virtualmachines/alpine_virtualmachine_setup_use.md @@ -0,0 +1,70 @@ +# BaSyx Virtual Machine Setup +The virtual machine images for [these](../../basyx_components/v2/index.md) components can be found [here](https://oc.iese.de/index.php/s/9JyJAuOlhh9vMUu?path=%2F). In the following, it is explained how the images can be used with Oracle VirtualBox and VMware Workstation Player. + +## Oracle VirtualBox +### Import the Virtual Machine +Import the machine (*File -> Import Appliance*) with the following settings: +- Tick only the network adapter checkbox. +- MAC Address Policy: Include only NAT network adapter MAC addresses. + +### Change the Shared Folder Location +Create a folder called *SharedFolder* on the host system and change the shared folder path under *Settings -> Shared Folders* to the new folder. Depending on the BaSyx component, create one of the following folders in *SharedFolder*: + +- aasdiscoveryservice +- aasenvironment +- aasregistry_service_release_log_mem +- aasrepository +- conceptdescriptionrepository +- submodelregistry_service_release_log_mem +- submodelrepository + +For the virtual machine containing all components, create all of those. Place the *application.properties* files in the respective folders. + +### Enable Port Forwarding +Create for every component a new entry in the port forwarding list (*Settings -> Network -> Adapter 1 -> Advanced -> Port Forwarding*) with the following properties: +- Host IP: 127.0.0.1 +- Host Port: \ +- Guest IP: 10.0.2.15 +- Guest Port: \ + +For aasdiscoveryservice, aasenvironment, aasrepository, conceptdescriptionrepository and submodelrepository, the port can be specified in the respective *application.properties*. For aasregistry_service_release_log_mem and submodelregistry_service_release_log_mem, the port can be specified in the virtual machine in */home/basyx_aasregistry_service_release_log_mem/basyx_aasregistry_service_release_log_mem_startup.sh* (Default: 8086) and */home/basyx_submodelregistry_service_release_log_mem/basyx_submodelregistry_service_release_log_mem_startup.sh* (Default: 8087), respectively. + +### Make the Virtual Machine Load the Shared Folder +Execute in the virtual machine + + crontab -e + +and remove the # in front of the first *reboot* and comment out the subsequent line instead by placing a # in front of it. + + +## VMware Workstation Player +### Import the Virtual Machine +Import the machine (*Player -> File -> Open*). If the import fails, select *retry*. + +### Add a Shared Folder +Create a folder called *SharedFolder* on the host system and add it under *Edit virtual machine settings -> Options -> Shared Folders -> Add*. Tick *always enabled*. Depending on the Basyx component, create one of the following folders in *SharedFolder*: + +- aasdiscoveryservice +- aasenvironment +- aasregistry_service_release_log_mem +- aasrepository +- conceptdescriptionrepository +- submodelregistry_service_release_log_mem +- submodelrepository + +For the virtual machine containing all components, create all of those. Place the *application.properties* files in the respective folders. + +### Make the Virtual Machine Load the Shared Folder +This step is only necessary if changes have been made to this file before.
+Execute in the virtual machine + + crontab -e + +and remove the # in front of the second *reboot* and comment out the preceding line instead by placing a # in front of it. + +### Change Network Settings +Select *NAT* under *Edit virtual machine settings -> Hardware -> Network Adapter*. + +### IP Address and Port Number +The IP address of the virtual machine can be found out by executing *ifconfig* in the guest system, for instance.
+For aasdiscoveryservice, aasenvironment, aasrepository, conceptdescriptionrepository and submodelrepository, the port can be specified in the respective *application.properties*. For aasregistry_service_release_log_mem and submodelregistry_service_release_log_mem, the port can be specified in the virtual machine in */home/basyx_aasregistry_service_release_log_mem/basyx_aasregistry_service_release_log_mem_startup.sh* (Default: 8086) and */home/basyx_submodelregistry_service_release_log_mem/basyx_submodelregistry_service_release_log_mem_startup.sh* (Default: 8087), respectively.