Merge pull request #6 from ifm/sv_add_text

Addes small text to the READMEs

O3R/Docker/README.md

@@ -0,0 +1,10 @@
+# README - Docker on O3R
+
+| Table of content|
+|-|
+| [Getting started with Docker](../Docker/docker.md)|
+| [Deployment on board](../Docker/deployVPU.md)|
+| [Autostarting the container](../Docker/autostart.md)|
+| [Enabling GPU usage](../Docker/gpu.md)|
+
+This section explains the handling and deployment of customer specific containers for the O3R.

O3R/Docker/autostart.md

@@ -0,0 +1,60 @@
+# Autostart a container on the VPU
+
+Once the container(s) has(ve) been transferred to the VPU, you can set up an autostart service to automatically run the containers as start-up.
+For auto-starting a container, `Docker compose` is used. The VPU already provides a service `.config/systemd/user/[email protected]` which can be used for auto-starting a service: this is what we will use.
+
+## Docker compose
+
+Generate a sample directory and a `docker-compose.yml` file at following destination: `/usr/share/oem/docker/compose/`. E.g. `/usr/share/oem/docker/compose/jupyter/docker-compose.yml`
+
+This file should contain the information for starting the container you need.
+
+### Sample docker-compose.yml
+
+The following `docker-compose.yml` file would create a service called `jupyter`, based on the image `jupyter` and bind the container ports 8888 to the host port 8888 on start.
+
+```yml
+version: "3.3"
+services:
+    jupyter:
+        image: jupyter
+        ports:
+            - 8888:8888
+```
+
+> Note: The Docker version on the VPU expects the docker-compose.yml to be either version 2.2 or 3.3. Fur further information refer to [docker compose](<https://docs.docker.com/compose/gettingstarted/>).
+
+## Start the container(s)
+
+A `docker-compose.yml` can be started via `docker-compose up` within the `docker-compose.yml` directory.  
+**TODO: add example of `docker compose-up`**  
+It is also possible to start the service with `systemctl`:
+
+```Linux
+systemctl --user start oem-dc@jupyter
+```
+
+After a few seconds, the service should have started and it is possible to get the status of this service:
+
+```Linux
+systemctl --user status oem-dc@jupyter
+```
+**TODO: add the result of this cmd**
+
+Another way of seeing all running container is `docker ps`.
+
+## Auto start the container(s) after a reboot of the VPU
+
+To restart the container automatically, simply `enable` the service:
+
+```Linux
+systemctl --user enable oem-dc@jupyter
+```
+
+See [Start the container](#start-the-container(s)) on how to start the container with a `docker-compose.yml file`
+
+## Save data on consistently on the VPU with a container
+**TODO: move this section to a more appropriate chapter**
+*Coming soon*
+
+Data created and saved within a container is only available for the running instance of the container itself. Restarting the container leads to a loss of the previously saved data. Use `volumes` to avoid this scenario.

O3R/Docker/deployVPU.md

@@ -0,0 +1,154 @@
+# Deploying a container to the VPU
+
+There are several ways for deploying a container. This documentation focuses on the following two:
+
+- Using `scp`
+- Using a local docker registry
+
+Every VPU has two users:
+
+- root - ifm user with all rights
+- oem - customer user, this is the only one you have access to.
+
+The first step to access the VPU is to connect to it via SSH.
+## SSH connection
+
+To connect to the VPU via ssh, follow these steps:
+
+1. Generate an ssh key-pair
+2. Upload the public key to the VPU
+3. Connect to the VPU using the passphrase
+
+### 1. Generate ssh key-pair
+
+All user specific ssh keys are located at `~/.ssh`. This is the place where the private key for the connection to the VPU should be stored. 
+
+To generate an ssh key-pair, use `ssh-keygen`:
+
+```console
+$ cd ~/.ssh/
+~/.ssh$ ssh-keygen -t rsa -b 4096 -C "[email-address]"
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/devoegse/.ssh/id_rsa): id_o3r
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+...
+```
+
+A passphrase is also needed. After that command, two new keys are generated within the `~/.ssh` directory. With the example above it would be: `id_o3r` & `id_o3r.pub`.
+
+### 2. Upload the public key to the VPU
+
+Uploading the public (`.pub`) ssh key to the VPU is achieved via the ifm3d library.
+The device configuration includes a parameter for authorized keys: `authorized_keys`.
+
+```json
+"network": {
+      "authorized_keys": "",
+      "ipAddressConfig": 0,
+      "macEth0": "00:04:4B:EA:95:FB",
+      "macEth1": "00:02:01:23:33:36",
+      "networkSpeed": 1000,
+      "staticIPv4Address": "192.168.0.69",
+      "staticIPv4Gateway": "192.168.0.201",
+      "staticIPv4SubNetMask": "255.255.255.0",
+      "useDHCP": false
+    },
+```
+
+To add a new key, the VPU configuration needs to be changed. This can be done with several ways (see [configuring the camera](INSERTLINK)). The easiest way in this case is to use the `jq` command:
+
+```console
+$ ifm3d dump | jq --arg id "$(< ~/.ssh/id_o3r.pub)" '.device.network.authorized_keys=$id' | ifm3d config
+```
+
+- `ifm3d dump` - This command receives the current configuration from the VPU.
+- `jq --arg id "$(< ~/.ssh/id_o3r.pub)"` - This loads the public key into the variable `id` and provides it to the `jq` command
+- `'.device.network.authorized_keys=$id'` - Here the json value from `authorized_keys` is changed for the public key within the variable `id`
+- `ifm3d config` - The new json is now used to change the configuration of the VPU via `ifm3d config`
+
+### 3. Connect to the VPU using the passphrase
+
+After the key is uploaded, it is possible to connect with `ssh` and the username `oem` to the VPU:
+
+```console
+$ ssh [email protected]
+The authenticity of host '192.168.0.69 (192.168.0.69)' can't be established.
+ECDSA key fingerprint is SHA256:8gjC9za45TTRZNz5JCMwaNJ27BLfsPyDtjBaBQ2vyHw.
+Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
+Warning: Permanently added '192.168.0.69' (ECDSA) to the list of known hosts.
+o3r-vpu-c0:~$
+```
+
+There will be a prompt for the passphrase, configured during step 1.
+
+## SCP
+
+The first way to transfer a container to the VPU is to copy a saved container via scp.
+
+```bash
+path/to/container/folder$ scp ifm3d.tar [email protected]:/home/oem/
+[email protected]’s password:
+ifm3d.tar                                                                       100%  108MB  51.5MB/s   00:02
+```
+
+The system will ask for a password: `oem`
+
+To verify if the copy process worked, use the command `sync` on the VPU after the copying the container.
+
+> Note: Use ssh to connect to the VPU - see [SSH connection](#ssh-connection)
+
+> Note: The `oem` user has no write rights outside of his/her home directory. Therefore use `/home/oem/` for saving files etc. It is possible to create folders within the oem directory.
+
+Once you copied the container, you can load and start it (see [instructions](INSERTLINK))
+
+## Local docker registry
+
+Due to the fact that proxy servers are sometimes hard to deal with and that disk resources on the VPU is also limited, it might come handy to run a Docker registry in your local network.
+
+### Create a local Docker registry
+
+The local Docker registry is created by using the container images provided by Docker itself and host them.
+On the host system (not the VPU) activate a local Docker registry with following commands:
+
+```console
+$ docker pull registry:latest
+# Start the registry and bind the container ports to the host ports
+$ docker run -d -p 5000:5000 --name registry registry:latest
+```
+
+> Note: A local registry might seem complicated at first. For further information refer to the [official documentation](<https://docs.docker.com/registry/deploying/>).
+
+### Push a container to your local registry
+
+To push a container to the registry, it is recommended to first tag the image differently. E.g. if the registry is run on the localhost with port 5000, the image tag could be named:
+
+```Docker
+docker tag ifm3d localhost:5000/ifm3d
+```
+
+Use the normal push command for uploading to the local registry:
+
+```Docker
+docker push localhost:5000/ifm3d
+```
+
+### Pull a container from the local registry - host
+
+If a local Docker registry is running, use `docker pull` to pull the image:
+
+```console
+docker pull localhost:5000/ifm3d
+```
+
+### Pull a container from the local registry - VPU
+
+*Coming soon*
+
+### Stop the registry
+
+To stop the registry:
+
+```console
+docker container stop registry && docker container rm -v registry
+```