How to Build & Deploy a Network Using the LoRaWAN® Protocol

Install on AWS

1. Set up an AWS account if you do not yet have one.

2. Install the latest AWS CLI for your platform.

3. Follow this quickstart guide to configure your AWS CLI.

4. If you are using Linux or macOS, open Terminal. If you are using Windows, open PowerShell.

5. If you are using Linux or macOS, proceed to the next step.

   If you are using Windows:

   1. Enable Script Execution

   2. Install the AWS Tools for PowerShell on Windows

6. Choose a working directory, and then use the change directory command to open it. Later, you will need to store two files in this directory:

   mkdir thingsboard_aws

   cd thingsboard_aws

7. Create a security group using the following command:

   aws ec2 create-security-group --group-name thingsboardsg --description security group for ThingsBoard

8. Enter the following command to open port 22 so that you can connect to the instance via SSH:

   aws ec2 authorize-security-group-ingress --group-name thingsboardsg --protocol tcp --port 22 --cidr 0.0.0.0/0

   This command allows access from any IP address. You can further restrict this in the future to limited IP ranges by supplying a different CIDR.

9. Enter the following command to open port 8081 so that you can connect to the instance in your web browser and access the web portal for your ChirpStack instance:

   aws ec2 authorize-security-group-ingress --group-name thingsboardsg --protocol tcp --port 8081 --cidr 0.0.0.0/0

10. Enter the following command to open port 1883 for MQTT access:

    aws ec2 authorize-security-group-ingress --group-name thingsboardsg --protocol tcp --port 1883 --cidr 0.0.0.0/0

11. Create a key pair to use for connecting to the EC2 instance. Follow the instructions for your operating system.

    For macOS or Linux:

    aws ec2 create-key-pair --key-name thingsboard-key --key-format pem --query "KeyMaterial" --output text > thingsboard-key.pem

    chmod 400 thingsboard-key.pem

    For Windows:

    (New-EC2KeyPair -KeyName "thingsboard-key" -KeyType "rsa" -KeyFormat "pem" ).KeyMaterial | Out-File -Encoding ascii -FilePath thingsboard-key.pem

12. Enter the following command to create an EC2 using the latest Amazon Linux 2 AMI in your default region:

    aws ec2 run-instances --image-id resolve:ssm:/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2 --security-groups thingsboardsg --instance-type t2.micro --key-name thingsboard-key

13. You will see some logs appear. Press Enter until you see the field labeled InstanceId and make a note of this InstanceId value, so you can refer to the instance later. We refer to this as THINGSBOARD_INSTANCE_ID
14. Wait a few minutes to allow the EC2 instance time to start up.
15. Open a new Terminal or Command Prompt instance.

16. If you are using a Linux or macOS Terminal or Windows Bash, enter the following command to query the public IP address using the THINGSBOARD_INSTANCE_ID:

    aws ec2 describe-instances --instance-ids THINGSBOARD_INSTANCE_ID --query 'Reservations[0].Instances[0].PublicIpAddress'

    For example:

    aws ec2 describe-instances --instance-ids i-06541cf9b8eeaf165 --query 'Reservations[0].Instances[0].PublicIpAddress'

    If you are using Windows Command Prompt, or prefer not to use the command line, you can view your new instance and IP address in your AWS EC2 console, following these instructions to determine your instance's public IPv4 address.

    Note down the public IP address, referred to later as THINGSBOARD_IP_ADDRESS.

17. Connect to your EC2 instance using SSH:

    For Linux Terminal, macOS Terminal or Windows Bash:

    ssh -i thingsboard-key.pem ec2-user@THINGSBOARD_IP_ADDRESS

    For example:

    ssh -i thingsboard-key.pem ec2-user@0.0.0.0

    Warning

    If you are using Windows and do not have ssh installed, you will need to use PuTTY to connect to the EC2 instance by following the instructions in the AWS document Connect to your Linux instance from Windows using PuTTY.

18. Run the following commands to update the packages and install Docker Engine:

    sudo yum update -y

    sudo amazon-linux-extras install docker

    Respond y to the prompts.

19. Start the Docker service by running:

    sudo service docker start

20. Force Docker to start on each reboot by running:

    sudo systemctl enable docker

21. Add the EC2 user to the Docker group by running:

    sudo usermod -a -G docker ec2-user

22. Enter the following to log out:

    exit

23. Log in again:

    ssh -i thingsboard-key.pem ec2-user@THINGSBOARD_IP_ADDRESS

24. Enter the following command to install Docker Compose and make it executable:

    sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

    sudo chmod +x /usr/local/bin/docker-compose

25. Create a working directory on the VM:

    mkdir thingsboard

    cd thingsboard

26. Use nano to create a file called docker-compose.yml by entering the following command:

    nano docker-compose.yml

27. Add the following code to the file:

    1. version: '2.2' services:   mytb:     restart: always     image: thingsboard/tb-postgres     ports:       - 8081:9090       - 1883:1883       - 5683:5683/udp     environment:       TB_QUEUE_TYPE: in-memory     volumes:       - ~/.mytb-data:/data       - ~/.mytb-logs:/var/log/thingsboard

28. Save and exit nano using CTRL+o, Enter, CTRL+x

29. Create directories for the data and logs by running the following commands:

    mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

    mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs

30. Start the server by running the command:

    docker-compose up

31. Wait while the container starts up – this could take five minutes or so.
32. When the logging in the console stops, browse to http://THINGSBOARD_IP_ADDRESS:8081/, replacing THINGSBOARD_IP_ADDRESS with the IP address of the server running ThingsBoard.
33. Sign in with the default login username tenant@thingsboard.org and password: tenant.

Install on Azure

1. Set up an Azure account if you do not yet have one.

2. Install the Azure CLI for your platform.

3. If you are using Linux or macOS, open Terminal. If you are using Windows, open PowerShell.

4. Enter the following to log into Azure:
   
   az login
    

5. You must select where you want to install the resources. You can use centralus, or choose from the range of Azure data center locations, based on your geographical requirements, here. Make a note of the data center region you have selected.

   Once you have identified the location you would like, you need to find its name. Enter the following command to view the locations available:

   az account list-locations

   Scroll down until you find the entry with the displayName key matching the name you located, and write down the corresponding name key. We refer to this later as DATA_CENTER_LOCATION.

6. Enter the following command to create a resource group in your chosen data center location, replacing DATA_CENTER_LOCATION with the location you've chosen:
   
   az group create --name thingsboard_rg --location DATA_CENTER_LOCATION
   
   e.g.
   az group create --name thingsboard_rg --location centralus

6. Enter the following command to create a virtual machine:

   az vm create --resource-group thingsboard_rg --name thingsboard_vm --image UbuntuLTS --admin-username adminuser --generate-ssh-keys

7. Note down the key publicIpAddress logged to your console. This is the IP address you use to connect to ChirpStack, referred to later as THINGSBOARD_IP_ADDRESS.

8. In order to open port 8081, which is required for HTTP access, and port 1883, which is required for the MQTT broker, you need to create a security group and add three rules. To create the security group, enter the following command:

   az network nsg create --resource-group thingsboard_rg --name thingsboardSecurityGroup

9. Add this rule to open port 8081:

   az network nsg rule create --resource-group thingsboard_rg --nsg-name thingsboardSecurityGroup --name ruleForPort8081 --protocol tcp --priority 1000 --destination-port-range 8081

10. Add this rule to open port 1883:

    az network nsg rule create --resource-group thingsboard_rg --nsg-name thingsboardSecurityGroup --name ruleForPort1883 --protocol tcp --priority 1001 --destination-port-range 1883

11. Add this rule to open port 22 so that you can log in via SSH:

    az network nsg rule create --resource-group thingsboard_rg --nsg-name thingsboardSecurityGroup --name ruleForPort22 --protocol tcp --priority 1002 --destination-port-range 22

12. Now assign the security group to the Network Interface Controller (NIC) of the VM:

    az network nic update --resource-group thingsboard_rg --name thingsboard_vmVMNic --network-security-group thingsboardSecurityGroup

13. Log in to your new VM using the following command, replacing THINGSBOARD_IP_ADDRESS with the IP address you noted down. If you are on an older version of Windows, you can use PuTTY, and follow these instructions to connect.
    
    ssh adminuser@THINGSBOARD_IP_ADDRESS
    
    e.g.
    
    ssh adminuser@0.0.0.0
     

14. We are using Ubuntu Linux so we will install the Docker Engine following the official documentation for Ubuntu. At the time of writing this guide, the commands to execute are:

    sudo apt-get update

    sudo apt-get install ca-certificates curl gnupg lsb-release

    sudo mkdir -p /etc/apt/keyrings

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

    sudo apt-get update

    sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

15. Enter the following command to allow the running of Docker without using sudo:

    sudo usermod -a -G docker adminuser

16. Exit, then log in again:

    exit

    ssh adminuser@THINGSBOARD_IP_ADDRESS

17. Force Docker to start on each boot of the VM:

    sudo systemctl enable docker

18. Create a working directory on the VM:

    mkdir thingsboard
    
    cd thingsboard

19. Use nano to create a file called docker-compose.yml:

    nano docker-compose.yml

20. Insert the following code:

    1. version: '2.2' services:   mytb:     restart: always     image: thingsboard/tb-postgres     ports:       - 8081:9090       - 1883:1883       - 5683:5683/udp     environment:       TB_QUEUE_TYPE: in-memory     volumes:       - ~/.mytb-data:/data       - ~/.mytb-logs:/var/log/thingsboard

21. Save and exit nano using CTRL+o, Enter, CTRL+x.

22. Create directories for the data and logs by running the following commands:

    mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

    mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs

23. Start the server by running the command:

    docker compose up

25. Wait while the container starts up – this could take five minutes or so.
26. When the logging in the console stops, browse to http://THINGSBOARD_IP_ADDRESS:8081, replacing THINGSBOARD_IP_ADDRESS with the IP address of the server running ThingsBoard.
27. Sign in with the default login username: tenant@thingsboard.org and password: tenant.