Introduction
The Rexroth ROKIT Locator is packaged as a Docker image for easy installation on a variety of different environments. To run the ROKIT Locator on the ctrlX CORE X7, the image must be repackaged in a snap and installed alongside the Container Engine App. The Container Engine App will start the ROKIT Locator as a Docker container running on the ctrlX CORE X7.
This article covers what requirements must be satisfied, how to create the ROKIT Locator snap and how to install it on the ctrlX CORE X7.
Requirements
To run the ROKIT Locator on the ctrlX CORE X7, the following requirements must be satisfied:
- ctrlX CORE X7 with OS version 1.* or 2.*
- Container Engine app installed on ctrlX CORE X7
- Docker image of ROKIT Locator Client 1.8
- License file for Container Engine app
- License file for ROKIT Locator Client 1.8
- TPM Enabler files for ROKIT Locator (attached below this article)
- snapcraft (multipass not required)
Before installation
Read the documentation
Carefully read the provided documentation for:
- ROKIT Locator Client
- Container Engine App
A general understanding of command line, Docker and snaps is recommended.
Create all required files
Multiple files are required to repackage the ROKIT Locator Docker image as a snap. Create them according to the following structure under some folder (in this example we use ~/rokit-locator-client):
~/rokit-locator-client
├── docker-compose
│ ├── image.tar
│ ├── docker-compose.env
│ └── docker-compose.yml
├── snap
│ └── hooks
│ └── install
├── snapcraft.yml
└── tpm-files
├── Infineon-OPTIGA-RSA-Manufacturing-CA-035_Issued_by_RootCA.crt-C-v01_00-EN.crt.sha256
├── Infineon-TPM_RSA_Root_CA-C-v01_00-EN.cer.sha256
└── InfineonOPTIGA_TM_TPM2_0RSACA042.crt.sha256
image.tar
The image.tar file must contain the ROKIT Locator Client Docker image. This can be done with one of the following ways:
- copy and rename the received Docker image
cp folder-of-extracted-locator-zip/Build/corei7-64/ROKIT_Locator_client.docker ~/rokit-locator-client/docker-compose/image.tar
- save Docker image which is stored in local Docker daemon (replace x with patch version number)
docker save rokit_locator_client:lls-1.8.x-final -o ~/rokit-locator-client/docker-compose/image.tar
docker-compose.env
This file contains environment variables which can be used in the docker-compose.yml. It is automatically loaded by the Container Engine App after installation of the ROKIT Locator Snap. It specifies the Docker image name and tag. Make sure to correctly set the patch version number in the image tag. It must match the previously create image file! Further the docker-compose.yml specifies the TPM enabler file names.
IMAGE_NAME=rokit_locator_client
IMAGE_TAG=lls-1.8.x-final
TPM_FILE_1=Infineon-OPTIGA-RSA-Manufacturing-CA-035_Issued_by_RootCA.crt-C-v01_00-EN.crt.sha256
TPM_FILE_2=Infineon-TPM_RSA_Root_CA-C-v01_00-EN.cer.sha256
TPM_FILE_3=InfineonOPTIGA_TM_TPM2_0RSACA042.crt.sha256
docker-compose.yml
This file contains the Docker compose service for the ROKIT Locator. It is automatically loaded by the Container Engine App after installation of the ROKIT Locator Client App. The service will (re)start automatically on boot up or failures. Make sure to only specify the ports required (further information in ROKIT Locator documentation) and avoid port conflicts with other apps / services (e.g. the web interface on the ctrlX COREvirtual also runs on port 8443). The first two volumes are needed for data persistence on restarts of the service (e.g. on reboot of device). Please keep in mind that a reinstallation of the snap will cause recreation of volumes and therefore all data (configuration values, map, ...) will be lost. The last three volumes mount the TPM enabler files to the correct location, so that the inbuilt TPM in ctrlX CORE X7 can be used for licensing of the ROKIT Locator.
version: "3.7"
services:
rokit-locator-client:
image: ${IMAGE_NAME}:${IMAGE_TAG}
container_name: rokit-locator-client
restart: always
ports:
- 8080:8080
- 8084:8084
- 9002-9014:9002-9014
- 9016:9016
- 9019-9022:9019-9022
- 6060-6061:6060-6061/udp # laser ports
- 8443:8443 # this will conflict with ctrlX CORE virtual which is running the web ui on 8443
- 8447:8447
- 9442-9454:9442-9454
- 9456:9456
- 9459-9462:9459-9462
volumes:
- ${SNAP_DATA}/docker-volumes/rokit-locator-client/lls:/var/lls
- ${SNAP_DATA}/docker-volumes/rokit-locator-client/lls-recovery:/var/lls-recovery
- ${SNAP_DATA}/docker-volumes/rokit-locator-client/${TPM_FILE_1}:/var/lls/trusted-platform-module/${TPM_FILE_1}
- ${SNAP_DATA}/docker-volumes/rokit-locator-client/${TPM_FILE_2}:/var/lls/trusted-platform-module/${TPM_FILE_2}
- ${SNAP_DATA}/docker-volumes/rokit-locator-client/${TPM_FILE_3}:/var/lls/trusted-platform-module/${TPM_FILE_3}
devices:
- "/dev/tpmrm0:/dev/tpmrm0:rwm"
logging: # limit logging to keep required disk space bound
driver: "json-file"
options:
max-size: "500m"
max-file: "5"
install
The following install hook copies the TPM Enabler files to the correct location. It is automatically being executed right after installation of the snap.
#!/bin/sh -e
# copy tpm files to docker volumes
mkdir -p "$SNAP_DATA"/docker-volumes/rokit-locator-client/
cp "$SNAP"/tpm-files/*.sha256 "$SNAP_DATA"/docker-volumes/rokit-locator-client/
snapcraft.yml
The snapcraft.yml defines how to build the snap. It is recommended to set the version equal to the ROKIT Locator Docker image tag. Make sure that the base matches the OS version of the ctrlX CORE X7 on which the ROKIT Locator will be deployed. Two parts specify which files are being added to the snap:
- docker-compose: all files under ./docker-compose which are required to start the services specified
- tpm-files: all files under ./tpm-files which are required to use TPM as licensing method for the ROKIT Locator
Two slots provide access to these files:
- docker-compose: Make docker-compose files available to the Container Engine App
- docker-volumes: Make docker-volumes folders available to the Container Engine App
Further details can be found in the Container Engine App documentation.
name: rokit-locator-client
version: 'lls-1.8.x-final'
base: core20 # use core20 for OS 1.* and core22 for OS 2.*
summary: ROKIT Locator Docker image app
description: |
This snap contains the Docker image of the Rexroth ROKIT Locator Client.
grade: stable
confinement: strict
parts:
docker-compose:
plugin: dump
source: ./docker-compose
organize:
'*': docker-compose/${SNAPCRAFT_PROJECT_NAME}/
tpm-files:
plugin: dump
source: ./tpm-files
organize:
'*': tpm-files/
slots:
docker-compose:
interface: content
content: docker-compose
source:
read:
- $SNAP/docker-compose/${SNAPCRAFT_PROJECT_NAME}
docker-volumes:
interface: content
content: docker-volumes
source:
write:
- $SNAP_DATA/docker-volumes/${SNAPCRAFT_PROJECT_NAME}
*.sha256 files
The *.sha256 files are signed certificate files used to enable the inbuilt TPM for ROKIT Locator licensing.
Create ROKIT Locator image app
Change into the folder containing all previously created files and create the snap using snapcraft in destructive mode (this is not harmful, because only dump plugins are being used to copy files):
cd ~/rokit-locator-client
snapcraft --destructive-mode
This should generate a *.snap file which contains all required files for the ROKIT Locator Client image app.
Installation of ROKIT Locator Client image app
Some changes must be made, before the newly created snap file can be run.
Enable IP port forwarding
If IP port forwarding is not enabled the ports specified previously in the docker-compose.yml file will not be accessible from any other device. It is therefore required to enable it for network interfaces which are being used to access the ROKIT Locator (e.g. for setup phase using the ROKIT Locator aXessor). Please note that this will allow access to the internal Docker network from any device connected to the interface. A warning ("Insecure Network Device") will show up when enabling the option. It is therefore recommended to disable the option again for a productive use case. Enabling and disabling can be done via the ctrlX CORE web interface in the network settings section:
Allow installation of apps from unknown sources
The ROKIT Locator Client Docker image app was manually created and is not verified by Rexroth. Therefore, it is required to allow the installation of apps from unknown sources. This can be done in the settings menu of the web interface:
Install Container Engine App
The Container Engine App must be installed and licensed, to run Docker containers on the ctrlX CORE X7.
Install ROKIT Locator Client image app
After all the previously mentioned requirements are satisfied, the ROKIT Locator Client Image App can be installed using the "Install from file" button in the app overview of the web interface. Please note that the ctrlX CORE X7 must be in "Service" mode.
Setup of ROKIT Locator Client
After installation the ROKIT Locator Client Docker image should appear, after some seconds, in the Container Engine images overview page. Additionally, a container should be spawned automatically and appear in the Container Engine containers overview page:
Congratulations 🥳. You successfully installed the ROKIT Locator Client on the ctrlX CORE X7. You may now continue with setting up the ROKIT Locator Client (for example using the graphical interface of the ROKIT Locator called aXessor). It is recommended to use the TPM licensing method which was already enabled by adding the TPM enabler files. Refer to the ROKIT Locator user manual for further setup steps.
Troubleshooting
In case of problems that occur during the installation process (e.g. ROKIT Locator image is not showing up), this page may help diagnosing the problem.
Container does not show up
The ROKIT Locator Docker image should be loaded automatically and a container instance should be started, after installation of the app. If no container shows up in the containers overview page the most common reason is a wrong "IMAGE_NAME" or "IMAGE_TAG" in the docker-compose.env file. Check if these values match the corresponding "Tags" entry of the image in the image overview.
