|
| 1 | +## Option 2: Container network and using Cumulocity Basic Auth |
| 2 | + |
| 3 | +**When to use it?** |
| 4 | + |
| 5 | +* Familiar with containers |
| 6 | +* Basic understanding of container networking |
| 7 | +* You can't use certificate based auth for reason |
| 8 | + |
| 9 | +## Getting Started |
| 10 | + |
| 11 | + |
| 12 | +### Option 1: Using docker run |
| 13 | + |
| 14 | +1. Pull the latest image |
| 15 | + |
| 16 | + ```sh |
| 17 | + docker pull ghcr.io/thin-edge/tedge-container-bundle |
| 18 | + ``` |
| 19 | + |
| 20 | +1. Create Cumulocity basic auth credentials for your new device. For convenience, you can use go-c8y-cli to do this |
| 21 | + |
| 22 | + ```sh |
| 23 | + c8y deviceregistration register-basic --id tedge_abcdef |
| 24 | + ``` |
| 25 | + |
| 26 | +1. Set some environment variable based on the Cumulocity instance you wish to connect to, and the device id |
| 27 | + |
| 28 | + ```sh |
| 29 | + export TEDGE_C8Y_URL="example-demo.eu-latest.cumulocity.com" |
| 30 | + export DEVICE_ID="tedge_abcdef" |
| 31 | + export C8Y_DEVICE_USER="t12345/device_${DEVICE_ID}" |
| 32 | + export C8Y_DEVICE_PASSWORD="<<code_max_32_chars>>" |
| 33 | + ``` |
| 34 | + |
| 35 | + **Note** The username must be in the form of `{tenant}/device_{name}`. |
| 36 | + |
| 37 | +1. Create a docker volume which will be used to store the device credentials, and a volume for the tedge and mosquitto data |
| 38 | + |
| 39 | + ```sh |
| 40 | + docker network create tedge |
| 41 | + docker volume create device-creds |
| 42 | + docker volume create tedge |
| 43 | + ``` |
| 44 | + |
| 45 | +3. Create a new device credentials |
| 46 | + |
| 47 | + ```sh |
| 48 | + docker run --rm -it \ |
| 49 | + -v "device-creds:/etc/tedge/credentials" \ |
| 50 | + -e "TEDGE_C8Y_CREDENTIALS_PATH=/etc/tedge/credentials/credentials.toml" \ |
| 51 | + ghcr.io/thin-edge/tedge-container-bundle:latest \ |
| 52 | + /usr/bin/set-c8y-basic-auth.sh "$C8Y_DEVICE_USER" "$C8Y_DEVICE_PASSWORD" |
| 53 | + ``` |
| 54 | + |
| 55 | + Alternatively, you can set the Cumulocity device username and password using environment variables, however be aware that they could then be read by anyone with access to the container engine. |
| 56 | + |
| 57 | + ```sh |
| 58 | + -e "C8Y_DEVICE_USER=$C8Y_DEVICE_USER" \ |
| 59 | + -e "C8Y_DEVICE_PASSWORD=$C8Y_DEVICE_PASSWORD" \ |
| 60 | + ``` |
| 61 | + |
| 62 | +1. Start the container |
| 63 | + |
| 64 | + ```sh |
| 65 | + docker run -d \ |
| 66 | + --name tedge \ |
| 67 | + --restart always \ |
| 68 | + --add-host host.docker.internal:host-gateway \ |
| 69 | + --network tedge \ |
| 70 | + -p "127.0.0.1:1883:1883" \ |
| 71 | + -p "127.0.0.1:8000:8000" \ |
| 72 | + -p "127.0.0.1:8001:8001" \ |
| 73 | + -v device-creds:/etc/tedge/credentials \ |
| 74 | + -v tedge:/data/tedge \ |
| 75 | + -v /var/run/docker.sock:/var/run/docker.sock:rw \ |
| 76 | + -e TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always \ |
| 77 | + -e "DEVICE_ID=${DEVICE_ID}" \ |
| 78 | + -e "TEDGE_C8Y_URL=${TEDGE_C8Y_URL}" \ |
| 79 | + -e "TEDGE_C8Y_AUTH_METHOD=auto" \ |
| 80 | + -e "TEDGE_C8Y_CREDENTIALS_PATH=/etc/tedge/credentials/credentials.toml" \ |
| 81 | + ghcr.io/thin-edge/tedge-container-bundle:latest |
| 82 | + ``` |
| 83 | + |
| 84 | + 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. |
| 85 | + |
| 86 | + ```sh |
| 87 | + docker run -d \ |
| 88 | + --name tedge \ |
| 89 | + --restart always \ |
| 90 | + --add-host host.docker.internal:host-gateway \ |
| 91 | + --network tedge \ |
| 92 | + -p "127.0.0.1:1884:1883" \ |
| 93 | + -p "127.0.0.1:9000:8000" \ |
| 94 | + -p "127.0.0.1:9001:8001" \ |
| 95 | + -v device-creds:/etc/tedge/credentials \ |
| 96 | + -v tedge:/data/tedge \ |
| 97 | + -v /var/run/docker.sock:/var/run/docker.sock:rw \ |
| 98 | + -e TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always \ |
| 99 | + -e "DEVICE_ID=${DEVICE_ID}" \ |
| 100 | + -e "TEDGE_C8Y_URL=${TEDGE_C8Y_URL}" \ |
| 101 | + -e "TEDGE_C8Y_AUTH_METHOD=auto" \ |
| 102 | + -e "TEDGE_C8Y_CREDENTIALS_PATH=/etc/tedge/credentials/credentials.toml" \ |
| 103 | + ghcr.io/thin-edge/tedge-container-bundle:latest |
| 104 | + ``` |
| 105 | + |
| 106 | + |
| 107 | +### Option 2: Using docker compose |
| 108 | + |
| 109 | +Note: This docker compose example uses environment variable to set the basic auth. Ideally you would not set the credentials this ways as it makes them readable to anyone whom has access to the container engine. |
| 110 | + |
| 111 | +1. In a shell, create a new folder and change directory into it. The name of the folder will be your docker compose project name |
| 112 | + |
| 113 | +1. Create a `.env` file with the following contents |
| 114 | + |
| 115 | + ```sh |
| 116 | + TEDGE_C8Y_URL="example-demo.eu-latest.cumulocity.com" |
| 117 | + export DEVICE_ID="tedge_abcdef" |
| 118 | + export C8Y_DEVICE_USER="t12345/device_${DEVICE_ID}" |
| 119 | + export C8Y_DEVICE_PASSWORD="<<code_max_32_chars>>" |
| 120 | +
|
| 121 | + # any other custom thin-edge.io configuration that you want |
| 122 | + TEDGE_C8Y_OPERATIONS_AUTO_LOG_UPLOAD=always |
| 123 | + ``` |
| 124 | + |
| 125 | +1. Create a `docker-compose.yaml` file with the following contents |
| 126 | + |
| 127 | + ```yaml |
| 128 | + services: |
| 129 | + tedge: |
| 130 | + image: ghcr.io/thin-edge/tedge-container-bundle |
| 131 | + restart: always |
| 132 | + environment: |
| 133 | + - TEDGE_C8Y_AUTH_METHOD=auto |
| 134 | + - TEDGE_C8Y_CREDENTIALS_PATH=/etc/tedge/credentials/credentials.toml |
| 135 | + env_file: |
| 136 | + - .env |
| 137 | + ports: |
| 138 | + - 127.0.0.1:1883:1883 |
| 139 | + - 127.0.0.1:8000:8000 |
| 140 | + - 127.0.0.1:8001:8001 |
| 141 | + # When using docker, add access to the host |
| 142 | + # if you want to be able to ssh into the host from the container |
| 143 | + extra_hosts: |
| 144 | + - host.docker.internal:host-gateway |
| 145 | + tmpfs: |
| 146 | + - /tmp |
| 147 | + volumes: |
| 148 | + - device-creds:/etc/tedge/credentials |
| 149 | + - tedge:/data/tedge |
| 150 | + # Enable docker from docker |
| 151 | + - /var/run/docker.sock:/var/run/docker.sock:rw |
| 152 | +
|
| 153 | + volumes: |
| 154 | + device-creds: |
| 155 | + tedge: |
| 156 | + ``` |
| 157 | + |
| 158 | +1. Start the container using docker compose |
| 159 | + |
| 160 | + ```sh |
| 161 | + docker compose up -d |
| 162 | + ``` |
| 163 | + |
| 164 | +## Using the tedge-container-bundle |
| 165 | + |
| 166 | +### Subscribing to the MQTT broker |
| 167 | + |
| 168 | +Assuming the container network is called `tedge`, then you can subscribe to the MQTT broker using the following command: |
| 169 | + |
| 170 | +```sh |
| 171 | +docker run --rm -it \ |
| 172 | + --network tedge \ |
| 173 | + -e TEDGE_MQTT_CLIENT_HOST=tedge \ |
| 174 | + ghcr.io/thin-edge/tedge-container-bundle \ |
| 175 | + tedge mqtt sub '#' |
| 176 | +``` |
| 177 | + |
| 178 | +Or you can access the MQTT broker directly from the host using the port mappings: |
| 179 | + |
| 180 | +```sh |
| 181 | +mosquitto_sub -h 127.0.0.1 -p 1883 -t '#' |
| 182 | +
|
| 183 | +# or if you used another port |
| 184 | +mosquitto_sub -h 127.0.0.1 -p 1884 -t '#' |
| 185 | +``` |
0 commit comments