ThingsBoard Server Installation

This guide provides step-by-step instructions to set up a ThingsBoard server for this project.

Prerequisites

• A server running Linux, e.g. Ubuntu 22.04 LTS

  • using a cloud hosting provider (e.g., DigitalOcean, AWS, Azure, GCP)

  • minimum specifications 1 vCPU (2 recommended), 2GB RAM

• Optional: A domain name pointing to the server’s IP address

  • e.g., subdomain.example.com

  • choose from a paid domain name provider (e.g. namecheap.com) or use a subdomain of an existing domain (e.g. from within your institution)

  • point the domain’s DNS A record to the server’s IP address (A <domain> <IP>)

  • optional: create a trusted certificate for the domain using Let’s Encrypt (e.g. using certbot certonly -d <domain>) and add an automatic renewal cron job (e.g. 0 0 * * * certbot renew --quiet)

• Optional: Familiarize yourself with the ThingsBoard documentation.

Installation

1. Optional: Update system packages and reboot

   sudo apt update
   sudo apt upgrade -y
   sudo apt auto-remove -y
   sudo reboot
   

2. Optional: Set up a swapfile if your server has less than 2GB of RAM

   sudo fallocate -l 4G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
   

3. Install dependencies (docker, git, jq, curl, ca-certificates, nginx-full, ufw)

   sudo apt install docker.io git jq curl ca-certificates nginx-full ufw
   

4. Install docker-compose (plugin)

   # Add Docker's official GPG key:
   sudo apt update
   sudo apt install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   # Add the repository to Apt sources:
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   # Install docker-compose
   sudo apt update
   sudo apt install docker-compose-plugin
   

5. Add your user to the docker group (log out/in afterwards)

   sudo groupadd docker || true
   sudo usermod -aG docker $USER
   

6. Create data folders for ThingsBoard

   mkdir -p ~/data/thingsboard_data/data
   mkdir -p ~/data/thingsboard_data/logs
   mkdir -p ~/data/kafka
   sudo chmod -R a+rw ~/data/
   

7. Generate a self-signed certificate for ThingsBoard SSL (skip if using a trusted certificate)

   • Run gen_certs.sh in a temporary directory on your local machine (script available in this repository under setup/ThingsBoard/gen_certs.sh).

8. Copy files to the server

   • docker-compose.yml → ~/docker-compose.yml

   • self_signed_cert.crt → /etc/ssl/certs/self_signed_cert.crt

   • self_signed_cert.key → /etc/ssl/certs/self_signed_cert.key

   • nginx_thingsboard.conf → /etc/nginx/sites-available/thingsboard.conf

   • nginx.conf → /etc/nginx/nginx.conf (overwrite existing file)

9. Remove default NGINX configuration

   sudo rm /etc/nginx/sites-enabled/default
   

10. Set up firewall using ufw

    sudo ufw default deny incoming
    sudo ufw default allow outgoing
    sudo ufw allow ssh
    sudo ufw allow http
    sudo ufw allow https
    sudo ufw allow 8843
    sudo ufw enable
    

11. Reload NGINX and start Docker containers

    sudo service nginx reload
    cd ~
    docker compose -f docker-compose.yml up -d
    

12. Watch live logs of ThingsBoard (initial startup takes several minutes)

    docker logs -f thingsboard
    

    Wait until the following message appears:

    [main] INFO  o.t.s.ThingsboardServerApplication - Started ThingsBoard in x seconds

13. Open the ThingsBoard web UI and log in with default credentials

    • Open <your-domain> in a web browser

    • Log in with: - username: sysadmin@thingsboard.org - password: sysadmin

14. Connect MQTT devices to ThingsBoard

    Use the following MQTT broker settings:

    • host: <your-domain>

    • port: 8843 (SSL)

    • username: <access-token> (see below)

    See the ThingsBoard MQTT API documentation for details.