Adds documentation for creating and using virtual machine images of B…

…aSyx 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

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.
 

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.
 

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
 

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.
 

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.
 

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
 

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.
 

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: \<port>
+- Guest IP: 10.0.2.15
+- Guest Port: \<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 <base image command> && /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 *\<component>_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.

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 <https://alpinelinux.org/downloads/>. 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: <https://adoptium.net/installation/linux/>
+
+
+### 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.

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: \<port>
+- Guest IP: 10.0.2.15
+- Guest Port: \<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_<component>
+
+
+### Place the Setup and Startup Scripts on the Virtual Machine
+Place *basyx_\<component>\_setup.sh* and *basyx_\<component>_startup.sh* in the shared folder on the host system and execute:
+
+    mv /mnt/shared/basyx_<component>_setup.sh /home/basyx_<component>
+    mv /mnt/shared/basyx_<component>_startup.sh /home/basyx_<component>
+
+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 <base image command> && /bin/sh /home/basyx_<component>/basyx_<component>_setup.sh ; /bin/sh /home/basyx_<component>/basyx_<component>_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/<component>.jar /home/basyx_<component>
+
+
+### 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.

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
+```

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