diff --git a/README.md b/README.md index 23bac18..4357c5d 100644 --- a/README.md +++ b/README.md @@ -24,111 +24,20 @@ The **tedge-container-bundle** provides the following features: The following are required in order to deploy the container * docker -* docker compose - -### Step 1: Create a device certificate inside a named volume - -Before you can start the containers, you need to create a device certificate inside a named volume, and also to persist the tedge and mosquitto data - -1. Create a docker network and volumes which will be used to store the device certificate and the tedge data - - ```sh - docker network create tedge - docker volume create device-certs - docker volume create tedge - ``` - -2. Set the Cumulocity IoT variable (to make it easier to copy/paste the remaining instructions) - - ```sh - TEDGE_C8Y_URL="$C8Y_DOMAIN" - - # Example - TEDGE_C8Y_URL=my.cumulocity.com - ``` - -3. Create a new device certificate - - ```sh - docker run --rm -it \ - -v "device-certs:/etc/tedge/device-certs" \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - ghcr.io/thin-edge/tedge-container-bundle:latest tedge cert create --device-id "" - ``` - Where you should replace the `` with the device's identity. +### Choose a setup -4. Upload the device certificate to Cumulocity IoT +[Option 1: On Host Network](./docs/CONTAINER_OPTION1.md) - ```sh - docker run --rm -it \ - -v "device-certs:/etc/tedge/device-certs" \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - ghcr.io/thin-edge/tedge-container-bundle:latest tedge cert upload c8y - ``` - - If you are having problems with the docker network, you can try to use the host network and explicitly set a DNS address: - - ```sh - docker run --rm -it --dns 8.8.8.8 --network host \ - -v "device-certs:/etc/tedge/device-certs" \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - ghcr.io/thin-edge/tedge-container-bundle:latest tedge cert upload c8y - ``` - - **Tip** - - If you don't want to be prompted for the Cumulocity IoT Username and Password (required to upload the certificate), then you can provide them via the following environment variables: - - ```sh - docker run --rm -it \ - -v "device-certs:/etc/tedge/device-certs" \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - -e "C8Y_USER=$C8Y_USER" \ - -e "C8Y_PASSWORD=$C8Y_PASSWORD" \ - ghcr.io/thin-edge/tedge-container-bundle:latest tedge cert upload c8y - ``` - -### Step 2: Start thin-edge.io - -Once the device certificate has been created inside the named volume, the same volume can be used when starting the container. - -```sh -docker run -d \ - --name tedge \ - --restart always \ - --network tedge \ - -p "127.0.0.1:1884:1883" \ - -p "127.0.0.1:9000:8000" \ - -p "127.0.0.1:9001:8001" \ - --add-host host.docker.internal:host-gateway \ - -v "device-certs:/etc/tedge/device-certs" \ - -v "tedge:/data/tedge" \ - -v /var/run/docker.sock:/var/run/docker.sock:rw \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - ghcr.io/thin-edge/tedge-container-bundle:latest -``` +[Option 2: Container network (Recommended)](./docs/CONTAINER_OPTION2.md) -The `TEDGE_C8Y_URL` env variable is used to set the target Cumulocity IoT so that thin-edge.io knows where to connect to. ### Settings -All of the thin-edge.io settings can be customized via environment variables, which can be useful if you want to change the port numbers like in the following example: +All of the thin-edge.io settings can be customized via environment variables which can be added via the `-e KEY=VALUE` to the `docker run` command: ```sh -docker run -d \ - --name tedge \ - --restart always \ - --add-host host.docker.internal:host-gateway \ - -p "127.0.0.1:1884:1883" \ - -p "127.0.0.1:9000:8000" \ - -p "127.0.0.1:9001:8001" \ - -v "device-certs:/etc/tedge/device-certs" \ - -v "tedge:/data/tedge" \ - -v /var/run/docker.sock:/var/run/docker.sock:rw \ - -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ - -e TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always \ - ghcr.io/thin-edge/tedge-container-bundle:latest +TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always ``` ### Development diff --git a/docs/CONTAINER_OPTION1.md b/docs/CONTAINER_OPTION1.md new file mode 100644 index 0000000..a449469 --- /dev/null +++ b/docs/CONTAINER_OPTION1.md @@ -0,0 +1,67 @@ +## Option 1: Running thin-edge.io to the the host network + +**When to use it?** + +* Unfamiliar with container environments +* Running on a device where docker isn't configured properly and the networking is broken +* Just want something working quickly to try things out (and just run it like a normal applications) + + +### Initial setup + +1. Pull the latest image + + ```sh + docker pull ghcr.io/thin-edge/tedge-container-bundle + ``` + +2. Create a docker volume which will be used to store the device certificate, and a volume for the tedge and mosquitto data + + ```sh + export TEDGE_C8Y_URL=example.c8y.cumulocity.com + + docker volume create device-certs + docker volume create tedge + ``` + +3. Create a new device certificate + + ```sh + docker run --rm -it \ + -v "device-certs:/etc/tedge/device-certs" \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle \ + tedge cert create --device-id "" + ``` + +4. Upload the device certificate to Cumulocity IoT + + ```sh + docker run --rm -it \ + -v "device-certs:/etc/tedge/device-certs" \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle \ + tedge cert upload c8y + ``` + +### Start the container + +```sh +docker run -d \ + --name tedge \ + --restart always \ + --network host \ + -v "device-certs:/etc/tedge/device-certs" \ + -v "tedge:/data/tedge" \ + -v /var/run/docker.sock:/var/run/docker.sock:rw \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle +``` + +### Subscribing to the MQTT broker + +```sh +docker run --rm -it --network host \ + ghcr.io/thin-edge/tedge-container-bundle \ + tedge mqtt sub '#' +``` diff --git a/docs/CONTAINER_OPTION2.md b/docs/CONTAINER_OPTION2.md new file mode 100644 index 0000000..02b6aac --- /dev/null +++ b/docs/CONTAINER_OPTION2.md @@ -0,0 +1,104 @@ +## Option 2: Container network + +**When to use it?** + +* Familiar with containers +* Basic understanding of container networking + + +### Initial setup + +1. Pull the latest image + + ```sh + docker pull ghcr.io/thin-edge/tedge-container-bundle + ``` + +2. Create a docker volume which will be used to store the device certificate, and a volume for the tedge and mosquitto data + + ```sh + export TEDGE_C8Y_URL=example.c8y.cumulocity.com + + docker network create tedge + docker volume create device-certs + docker volume create tedge + ``` + +3. Create a new device certificate + + ```sh + docker run --rm -it \ + -v "device-certs:/etc/tedge/device-certs" \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle:latest \ + tedge cert create --device-id "" + ``` + +4. Upload the device certificate to Cumulocity IoT + + ```sh + docker run --rm -it \ + -v "device-certs:/etc/tedge/device-certs" \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle:latest \ + tedge cert upload c8y + ``` + +### Start the container + +```sh +docker run -d \ + --name tedge \ + --restart always \ + --add-host host.docker.internal:host-gateway \ + --network tedge \ + -p "127.0.0.1:1883:1883" \ + -p "127.0.0.1:8000:8000" \ + -p "127.0.0.1:8001:8001" \ + -v "device-certs:/etc/tedge/device-certs" \ + -v "tedge:/data/tedge" \ + -v /var/run/docker.sock:/var/run/docker.sock:rw \ + -e TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle:latest +``` + +With this option, you can change the host port mapping in case it conflicts with any other services running on the host, e.g. other services which are already using the ports that thin-edge.io wants to use. + +```sh +docker run -d \ + --name tedge \ + --restart always \ + --add-host host.docker.internal:host-gateway \ + --network tedge \ + -p "127.0.0.1:1884:1883" \ + -p "127.0.0.1:9000:8000" \ + -p "127.0.0.1:9001:8001" \ + -v "device-certs:/etc/tedge/device-certs" \ + -v "tedge:/data/tedge" \ + -v /var/run/docker.sock:/var/run/docker.sock:rw \ + -e TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always \ + -e "TEDGE_C8Y_URL=$TEDGE_C8Y_URL" \ + ghcr.io/thin-edge/tedge-container-bundle:latest +``` + +### Subscribing to the MQTT broker + +Assuming the container network is called `tedge`, then you can subscribe to the MQTT broker using the following command: + +```sh +docker run --rm -it \ + --network tedge \ + -e TEDGE_MQTT_CLIENT_HOST=tedge \ + ghcr.io/thin-edge/tedge-container-bundle \ + tedge mqtt sub '#' +``` + +Or you can access the MQTT broker directly from the host using the port mappings: + +```sh +mosquitto_sub -h 127.0.0.1 -p 1883 -t '#' + +# or if you used another port +mosquitto_sub -h 127.0.0.1 -p 1884 -t '#' +``` diff --git a/docs/FEATURES.md b/docs/FEATURES.md new file mode 100644 index 0000000..c134462 --- /dev/null +++ b/docs/FEATURES.md @@ -0,0 +1,117 @@ +## Features + +### Self update + +1. Create a repository item + + ```sh + c8y software create \ + --name tedge \ + --softwareType self + ``` + +2. Add a new version + + ```sh + c8y software versions create \ + --software tedge \ + --url " " \ + --version "ghcr.io/thin-edge/tedge-container-bundle:20240929.1503" + ``` + + ```sh + c8y software versions create \ + --software tedge \ + --url " " \ + --version "ghcr.io/thin-edge/tedge-container-bundle:latest" + ``` + +3. Create an operation to install software + + ```sh + c8y software versions install \ + --action install \ + --software tedge \ + --version "ghcr.io/thin-edge/tedge-container-bundle:latest" + ``` + + ```sh + c8y software versions install \ + --device "subdevice01" \ + --action install \ + --software tedge \ + --data softwareType=self \ + --url " " \ + --version "ghcr.io/thin-edge/tedge-container-bundle:latest" + ``` + + +### SSH Access + +**When to use it?** + +* Need to maintain the host operating system + +**Pre-requisites** + +* container is attached to the bridge network +* container has an extra host configured for the docker network (e.g. `--add-host=host.docker.internal:host-gateway`) +* ssh daemon has a listener on the container bridge network (e.g. typically `172.17.0.1`) +* Either your ssh keys have been added to the device, or allows password authentication + +After the pre-requisites are met, you can easily access your device using the following steps: + +1. Create a Cloud Remote Access PASSTHROUGH configuration for the device + + ```sh + c8y remoteaccess configurations create-passthrough \ + --device device01 \ + --hostname host.docker.internal \ + --port 22 \ + --name device-host + ``` + +2. Connect to the device using ssh + + ```sh + c8y remoteaccess connect ssh \ + --device device01 \ + --user root \ + --configuration device-host + ``` + +**Limitations** + +If you create a "SSH" remote access configuration item, then you MUST use the docker's gateway IP address, e.g. `172.17.0.1` instead of the `host.docker.internal` address. If you don't use the IP address, then you will get the following error in the WebSSH client (in the UI): + +```sh +host.docker.internal: Name does not resolve +``` + + +### SSH daemon configuration + +The ssh daemon must be listening on the docker network adapter to enable an SSH connection. + +1. Edit the ssh daemon configuration add check if there is a listener configured for the default docker network + + ```sh + docker network inspect bridge + ``` + + **file: /etc/ssh/sshd_config** + + ``` + #Port 22 + #AddressFamily any + #ListenAddress 0.0.0.0 + ListenAddress 127.0.0.1 + ListenAddress 172.17.0.1 + #ListenAddress :: + ``` + +2. Reload the ssh service (if a change was made) + + ```sh + systemctl reload ssh + ``` diff --git a/docs/container-self-update.drawio.png b/docs/container-self-update.drawio.png new file mode 100644 index 0000000..c558340 Binary files /dev/null and b/docs/container-self-update.drawio.png differ