- Prerequisites
- Step 1. Obtain the license key
- Step 2. Running Trendz service
- Detaching, stop and start commands
- Upgrade Trendz Service
- Standalone Python executor service
- Troubleshooting
- Next steps
This guide will help you to install and start Trendz Analytics using Docker on Linux or Mac OS.
Prerequisites
Step 1. Obtain the license key
We assume you have already chosen subscription plan for Trendz and have license key. If not, please get your Free Trial license before you proceed. See How-to get pay-as-you-go subscription for more details.
Note: We will reference the license key you have obtained during this step as PUT_YOUR_LICENSE_SECRET_HERE later in this guide.
Step 2. Running Trendz service
Docker Compose setup
Make sure your have logged in to docker hub using command line.
Create docker compose file for Trendz Analytics service:
1
sudo nano docker-compose.yml
Add the following line to the yml file. Don’t forget to replace “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
version: '3.0'
services:
mytrendz:
restart: always
image: "thingsboard/trendz:1.11.0"
ports:
- "8888:8888"
environment:
TB_API_URL: http://10.0.0.101:8080
TRENDZ_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
TRENDZ_LICENSE_INSTANCE_DATA_FILE: /data/license.data
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/trendz
SPRING_DATASOURCE_USERNAME: postgres
SPRING_DATASOURCE_PASSWORD: postgres
SCRIPT_ENGINE_PROVIDER: DOCKER_CONTAINER
SCRIPT_ENGINE_DOCKER_PROVIDER_URL: mypyexecutor:8181
SCRIPT_ENGINE_TIMEOUT: 30000
volumes:
- ~/.mytrendz-data:/data
- ~/.mytrendz-logs:/var/log/trendz
mypyexecutor:
restart: always
image: "thingsboard/trendz-python-executor:1.11.0"
ports:
- "8181:8181"
environment:
MAX_HEAP_SIZE: 750M
SCRIPT_ENGINE_RUNTIME_TIMEOUT: 30000
EXECUTOR_MANAGER: 1
EXECUTOR_SCRIPT_ENGINE: 6
THROTTLING_QUEUE_CAPACITY: 10
THROTTLING_THREAD_POOL_SIZE: 6
NETWORK_BUFFER_SIZE: 5242880
postgres:
restart: always
image: "postgres:15"
ports:
- "5432"
environment:
POSTGRES_DB: trendz
POSTGRES_PASSWORD: postgres
volumes:
- ~/.mytrendz-data/db:/var/lib/postgresql/data
Where:
TB_API_URL
- url for connecting to ThingsBoard Rest API (for example http://10.5.0.11:8080). Note that ThingsBoard IP address should be resolvable from Trendz docker containerPUT_YOUR_LICENSE_SECRET_HERE
- placeholder for your license secret obtained on the first step8888:8888
- connect local port 8888 to exposed internal HTTP port 8888~/.mytrendz-data:/data
- mounts the volume~/.mytrendz-data
to Trendz data directory~/.mytrendz-data/db:/var/lib/postgresql/datad
- mounts the volume~/.mytrendz-data/db
to Postgres data directory~/.mytrendz-logs:/var/log/thingsboard
- mounts the volume~/.mytrendz-logs
to Trendz logs directorymytrendz
- friendly local name of this machine--restart always
- automatically start Trendz in case of system reboot and restart in case of failure.thingsboard/trendz:1.11.0
- Trendz docker imagethingsboard/trendz-python-executor:1.11.0
- Trendz python script executor docker imageSCRIPT_ENGINE_RUNTIME_TIMEOUT
- Python script execution timeout
Run following commands, before starting docker container(s), to create folders for storing data and logs. These commands additionally will change owner of newly created folders to docker container user. To do this (to change user) chown command is used, and this command requires sudo permissions (command will request password for a sudo access):
1
2
mkdir -p ~/.mytrendz-data && sudo chown -R 799:799 ~/.mytrendz-data
mkdir -p ~/.mytrendz-logs && sudo chown -R 799:799 ~/.mytrendz-logs
NOTE: replace directory ~/.mytrendz-data and ~/.mytrendz-logs with directories you’re planning to used in docker-compose.yml.
Running service
Set the terminal in the directory which contains the docker-compose.yml
file and execute the following commands to up this docker compose directly:
1
2
docker compose up -d
docker compose logs -f mytrendz
After executing this command you can open http://{your-host-ip}:8888
in you browser (for ex. http://localhost:8888
).
You should see Trendz login page.
Authentication
For first authentication you need to use Tenant Administrator credentials from your ThingsBoard
Trendz uses ThingsBoard as an authentication service. During first sign in ThingsBoard service should be also available to validate credentials.
Detaching, stop and start commands
You can detach from session terminal using Ctrl-p
Ctrl-q
key sequence - the container will keep running in the background.
In case of any issues you can examine service logs for errors. For example to see Trendz container logs execute the following command:
1
docker compose logs -f mytrendz
To stop the container:
1
docker compose stop mytrendz
To start the container:
1
docker compose start mytrendz
Upgrade Trendz Service
Below is example on how to upgrade from 1.10.3 to 1.11.0
Note: starting from version 1.10.2 we add support of Python script execution. During an upgrade you need to add Python executor image into your docker compose file. Full content of docker compose file you can find at the beginning of this article. Here is an example of the python executor service
1
2
3
4
5
6
7
8
9
10
11
12
13
mypyexecutor:
restart: always
image: "thingsboard/trendz-python-executor:1.11.0"
ports:
- "8181:8181"
environment:
MAX_HEAP_SIZE: 750M
SCRIPT_ENGINE_RUNTIME_TIMEOUT: 30000
EXECUTOR_MANAGER: 1
EXECUTOR_SCRIPT_ENGINE: 6
THROTTLING_QUEUE_CAPACITY: 10
THROTTLING_THREAD_POOL_SIZE: 6
NETWORK_BUFFER_SIZE: 5242880
- Create a dump of your database:
1
docker compose exec postgres sh -c "pg_dump -U postgres trendz > /var/lib/postgresql/data/trendz_dump"
- Set upgradeversion variable to your previous Trendz version.
1
docker compose exec mytrendz sh -c "echo '1.10.3' > /data/.upgradeversion"
-
After this you need to update docker-compose.yml as in Step 3 but with 1.11.0 instead of 1.10.3:
-
Restart Trendz container
1
2
docker compose stop mytrendz
docker compose up -d
To upgrade Trendz to the latest version those steps should be done for each intermediate version.
Standalone Python executor service
You can use following docker compose file in case when you want to start Trendz python executor as a separate service. It is useful when your Trendz service is installed in monolith mode, and you want to logically separate Trendz from service that executes Python scripts for prediction models. Using same configuration you can scale Python executors independently of Trendz service.
Create docker compose file:
1
sudo nano docker-compose.yml
Add following configuration:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
version: '3.0'
services:
mypyexecutor:
restart: always
image: "thingsboard/trendz-python-executor:1.11.0"
ports:
- "8181:8181"
environment:
SCRIPT_ENGINE_RUNTIME_TIMEOUT: 30000
EXECUTOR_MANAGER: 1
EXECUTOR_SCRIPT_ENGINE: 6
THROTTLING_QUEUE_CAPACITY: 10
THROTTLING_THREAD_POOL_SIZE: 6
NETWORK_BUFFER_SIZE: 10485760
Where:
8080
- Python executor port for communication with Trendz service--restart always
- automatically start Trendz in case of system reboot and restart in case of failure.thingsboard/trendz-python-executor:1.11.0
- Trendz python script executor docker imageSCRIPT_ENGINE_RUNTIME_TIMEOUT
- Python script execution timeout
1
2
docker compose up -d
docker compose logs -f mypyexecutor
- Final step is to tell Trendz service how to communicate with Python executor service. You can do that by changing following environment variables in
/usr/share/trendz/conf/trendz.conf
file:
1
2
3
export SCRIPT_ENGINE_TIMEOUT=30000
export SCRIPT_ENGINE_PROVIDER=DOCKER_CONTAINER
export SCRIPT_ENGINE_DOCKER_PROVIDER_URL=PYTHON_EXECUTOR_HOST:PYTHON_EXECUTOR_PORT
Note: you need to replace PYTHON_EXECUTOR_HOST
and PYTHON_EXECUTOR_PORT
with actual values of your Python executor service and ensure that Trendz is able to send network traffic to that destination.
Troubleshooting
DNS issues
NOTE If you observe errors related to DNS issues, for example
1
127.0.1.1:53: cannot unmarshal DNS message
You may configure your system to use Google public DNS servers. See corresponding Linux and Mac OS instructions.
Next steps
-
Getting started guide - These guide provide quick overview of main Trendz features.
-
Calculated Fields - Learn about Calculated fields and how to use them.
-
States - Learn how to define and analyse states for assets based on raw telemetry.
-
Prediction - Learn how to make forecasts and predict telemetry behavior.
-
Filters - Learn how filter dataset during analysis.
-
Available Visualizations - Learn about visualization widgets available in Trendz and how to configure them.
-
Share and embed Visualizations - Learn how to add Trendz visualizations on ThingsBoard dashboard or 3rd party web pages.