This repository provides an Ansible playbook to setup the ChirpStack open-source LoRaWAN Network Server (v4). With the included Vagrant file, ChirpStack can also be setup locally inside a VM (e.g. using VirtualBox).
It will:
The included Vagrantfile
will setup a Debian Bullseye (11.x) virtual
machine with the latest ChirpStack components installed. It will also forward
the following ports to your host system:
4443
: ChirpStack UI and gRPC API (with TLS, e.g. https://localhost:4443/)1700
: ChirpStack Gateway Bridge UDP listener (configured for EU868 region by default)3001
: ChirpStack Gateway Bridge Basics Station listener (configured for EU868 region by default, with TLS, client-certificate files can be generated in the ChirpStack UI)8883
: Mosquitto MQTT (with TLS, client-certificate files can be generated in the ChirpStack UI)Note: when using Vagrant, there is no need to install Ansible (this will be automatically installed inside the Vagrant machine).
When setting up ChirpStack, make sure you have a recent version of Vagrant installed.
Also make sure you have a recent version of VirtualBox installed, including the VirtualBox Extension Pack.
Update host_vars/vagrant.yml
where needed.
Within the root of this repository execute the following command:
vagrant up
As this will import the Vagrant box, install all requirements etc... this is going to take a while.
Configure your LoRa Gateway so that it points to the IP address of your
computer (port 1700
).
Point your browser to https://localhost:4443/. As a self-signed certificate is used, your browser will prompt that the certificate can't be trusted. This is ok for testing.
For updating your Vagrant environment (e.g. updating the configuration or to upgrade installed packages, execute the following command:
vagrant provision
Other useful commands:
# stop the vagrant machine
vagrant halt
# restart the vagrant machine
vagrant reload
# ssh into the vagrant machine
vagrant ssh
# destroy the vagrant machine
vagrant destroy
This playbook has been tested on DigitalOcean.com but should also work on bare-metal, AWS, ...
Don't have a DigitalOcean account yet? Use this link and get $10 in credits for free :-)
443
: ChirpStack UI and gRPC API (with TLS, e.g. https://subdomain.example.com/)1700
: ChirpStack Gateway Bridge UDP listener (configured for EU868 region by default)3001
: ChirpStack Gateway Bridge Basics Station listener (configured for EU868 region by default, with TLS, client-certificate files can be generated in the ChirpStack UI)8883
: Mosquitto MQTT (with TLS, client-certificate files can be generated in the ChirpStack UI)On the machine from where you will execute this Ansible playbook (e.g. your own
computer), make sure you have Ansible 2.10+ installed. You can install Ansible with
pip (pip install ansible
) or using Homebrew (OS X) (brew install ansible
).
Refer to the Ansible installation guide
for more installation instructions.
The Ansible playbook has been tested on the following images:
Debian
Ubuntu
Create a new Debian Bullseye 11.x instance and make sure that from your own machine
on which Ansible is installed, you can ssh to this machine using public-key
authentication (e.g. ssh user@ip
).
Configure a DNS record for your target instance and wait until this record resolves to your IP address.
Copy the inventory.example
inside this repository to inventory
and
replace example.com
with the hostname created in step 2.
Copy the group_vars/chirpstack.example.yml
inside this repository to
group_vars/chirpstack.yml
and change the settings where needed.
For more information, see also:
Run the following command from your machine to deploy ChirpStack to your target instance, to upgrade to the latest versions or to update the configuration:
ansible-playbook -i inventory deploy.yml
After the playbook has been completed, ChirpStack should be accessible from the domain you configured as fqdn in the group_vars/chirpstack.yml
.