Stage 2: Install and Configure the ChirpStack Network Server

Install ChirpStack in the Cloud

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. Create a directory to work inside, and then use the change directory command to open it.

    mkdir chirpstack_lns_aws

cd chirpstack_lns_aws

  7. Create a security group using the following command:

    aws ec2 create-security-group --group-name chirpstacklnssg --description "security group for ChirpStackLNS"

  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 chirpstacklnssg --protocol tcp --port 22 --cidr 0.0.0.0/0

    Note

    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 8080, 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 chirpstacklnssg --protocol tcp --port 8080 --cidr 0.0.0.0/0

  10. Enter the following command to open port 1883, so that you can connect your gateway bridge to the MQTT broker of your ChirpStack instance:

    aws ec2 authorize-security-group-ingress --group-name chirpstacklnssg --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 chirpstack-key --key-format pem --query "KeyMaterial" --output text > chirpstack-key.pem

chmod 400 chirpstack-key.pem

    For Windows:

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

  12. To start the server on launch of the EC2 instance, copy the following script and save it to a local file named user_data.txt on your machine in your current working directory, chirpstack_lns_aws. Take care to copy it exactly as it is here, with the same line spacing, because the script is space-sensitive:

    Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"

#cloud-config
cloud_final_modules:
- [scripts-user, always]

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"

#!/bin/bash
cd /home/ec2-user/chirpstack-docker && docker-compose up -d 2> log.txt
--//

  13. Enter the following command to create an EC2 instance 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 chirpstacklnssg  --instance-type t2.micro --key-name chirpstack-key --user-data file://user_data.txt

    Warning

    If you see an error about the user_data.txt file, verify that you are running this command from inside the chirpstack_lns_aws folder. You can view your current working directory by entering pwd.

  14. You will see some logs appear. Press Enter until you see the field labelled InstanceId. Copy the InstanceId value, which we refer to later as EC2_INSTANCE_ID.

  15. Wait a few minutes to allow the EC2 instance time to start up.

  16. Open a new Terminal or PowerShell instance and change to the chirpstack_lns_aws directory.

    cd chirpstack_lns_aws

  17. Follow the instructions for your operating system to query the public IP address of the EC2 instance.

    If you are using Linux or macOS, enter the following command, replacing {EC2_INSTANCE_ID} with the value you found earlier:

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

    For example:

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

    Note down the IP address which displays. Do not copy the surrounding quotation marks (“). We will refer to this in the next step as CHIRPSTACK_IP_ADDRESS.

  18. Enter the following command, replacing CHIRPSTACK_IP_ADDRESS with the value you just found:

    ssh -i chirpstack-key.pem ec2-user@CHIRPSTACK_IP_ADDRESS

    For example:

    ssh -i chirpstack-key.pem ec2-user@44.211.139.76

    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.

  19. 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.

  20. Start the Docker service by running:

    sudo service docker start

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

    sudo systemctl enable docker

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

    sudo usermod -a -G docker ec2-user

  23. Close the Terminal window to log out. Open a new window and log in again:

    cd chirpstack_lns_aws
ssh -i chirpstack-key.pem ec2-user@CHIRPSTACK_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. Enter the following command to clone the official ChirpStack Docker Compose example:

    git clone https://github.com/chirpstack/chirpstack-docker.git

  26. Change to the chirpstack-docker directory and start ChirpStack:

    cd chirpstack-docker

  27. Start the Docker container:

    docker-compose up

  28. Wait a few minutes while the container starts up.

  29. Open a browser and visit http://CHIRPSTACK_IP_ADDRESS:8080/ where CHIRPSTACK_IP_ADDRESS is the IP address of your ChirpStack installation.

    You should see the ChirpStack login screen.

  30. Sign in with the default username admin and password admin.

Warning

The EC2 instance is not completely secure. For a production environment you should configure an SSL certificate, force connections over HTTPS, and follow other security best practices.


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 simply use centralus; however, if you would like to select a data center near you, view 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.

    /uploads/documents/images/NS02B01A-azure-names.png

    Figure 1: Output from az account list-location with the displayName and name Fields

  6. Create a directory to work inside, and then use the change directory command to open it.

    $ mkdir chirpstack_lns_azure

$ cd chirpstack_lns_azure

  7. 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 chirpstack_lns_rg \
--location {DATA_CENTER_LOCATION}

    For example:

    $ az group create \
--name chirpstack_lns_rg \
--location centralus

  8. Create a file named boot.sh in your working directory chirpstack_lns_azure.

    Paste the following content into the file. This file will be run on boot so that the services are restarted each time:

    Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"

#cloud-config
cloud_final_modules:
- [scripts-user, always]

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"

#!/bin/bash
cd /home/adminuser/chirpstack-docker && sudo docker compose up -d 2> log.txt
--//

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

    $ az vm create --resource-group chirpstack_lns_rg \
--name chirpstack_lns_vm \
--image UbuntuLTS \
--admin-username adminuser \
--custom-data boot.sh \
--generate-ssh-keys

  10. Copy the value of the key publicIpAddress logged to your console. This is the public IP address you will use to connect to ChirpStack, referred to later as CHIRPSTACK_IP_ADDRESS.

  11. Create a network security group using the following command:

    $ az network nsg create \
--name chirpstackSecurityGroup \
--resource-group chirpstack_lns_rg

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

    $ az network nsg rule create \
--resource-group chirpstack_lns_rg \
--nsg-name chirpstackSecurityGroup \
--name ruleForPort22 \
--protocol tcp \
--priority 1002 \
--destination-port-range 22

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

    $ az network nsg rule create \
--resource-group chirpstack_lns_rg \
--nsg-name chirpstackSecurityGroup \
--name ruleForPort8080 \
--protocol tcp \
--priority 1000 \
--destination-port-range 8080

  14. Enter the following command to open port 1883 so that you can connect your gateway bridge to the MQTT broker of your ChirpStack instance:

    $ az network nsg rule create \
--resource-group chirpstack_lns_rg \
--nsg-name chirpstackSecurityGroup \
--name ruleForPort1883 \
--protocol tcp \
--priority 1001 \
--destination-port-range 1883

  15. Update the network interface of the VM to use the new security group:

    $ az network nic update \
--resource-group chirpstack_lns_rg \
--name chirpstack_lns_vmVMNic \
--network-security-group chirpstackSecurityGroup

  16. Connect to the VM by entering the following command, replacing {CHIRPSTACK_IP_ADDRESS} with the IP address you found earlier.

    $ ssh adminuser@{CHIRPSTACK_IP_ADDRESS}

    For example:

    $ ssh adminuser@44.211.139.76

    Warning

    If you are using Windows and do not have ssh installed, you will need to use PuTTY to connect to the VM.

  17. Run the following commands to install Docker Engine, Docker Compose, and Make:

    $ 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

  18. Add the current user to the Docker group:

    $ sudo usermod -a -G docker $USER

  19. Log out and back in, replacing {CHIRPSTACK_IP_ADDRESS} with the IP address you found earlier.

    $ exit
$ ssh adminuser@{CHIRPSTACK_IP_ADDRESS}

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

    $ sudo systemctl enable docker

  21. Enter the following command to clone the official ChirpStack Docker Compose example:

    $ git clone https://github.com/chirpstack/chirpstack-docker.git

  22. Change to the chirpstack-docker directory and start ChirpStack:

    $ cd chirpstack-docker

  23. Start the Docker container:

    $ docker compose up

  24. Wait a few minutes while the container starts up.

  25. Open a browser and visit http://CHIRPSTACK_IP_ADDRESS:8080 where CHIRPSTACK_IP_ADDRESS is the IP address you found earlier.

    You should see the ChirpStack login screen.

  26. Sign in with the default username admin and password admin.

Warning

The Azure VM is not completely secure. For a production environment you should configure an SSL certificate, force connections over HTTPS, and follow other security best practices.