chirpstack-tutorial/doc/0-chirpstack/1-chirpstack.md

ChirpStack Server Install

If you prefer, you can use the official guide as a cross-reference. Differences between the official guide and this one:

• This guide does not cover ChirpStack Gateway Bridge setup; it is covered later in the series.
• This guide uses a newer method to install the ChirpStack GPG key.
• This guide secures the ChirpStack installation with TLS via the Caddy web server.

Prerequisite Services

ChirpStack requires PostgreSQL, Redis, and an MQTT broker (we will use Mosquitto). Install these prerequisites:

sudo apt install \
  mosquitto \
  mosquitto-clients \
  redis-server \
  redis-tools \
  postgresql

Next, run this command to set up PostgreSQL (use a different password for security):

sudo -iu postgres psql <<EOF
create role chirpstack with login password 'CHANGE_ME_PLEASE';
create database chirpstack with owner chirpstack;
\c chirpstack
create extension pg_trgm;
EOF

ChirpStack

Install the ChirpStack GPG key:

# https://superuser.com/a/1773782
gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00 && \
gpg --export 1CE2AFD36DBCCA00 | sudo tee /etc/apt/trusted.gpg.d/chirpstack.gpg >/dev/null && \
gpg --batch --yes --delete-keys 1CE2AFD36DBCCA00

This may take several seconds to finish.

Install ChirpStack:

sudo apt update && sudo apt install -y chirpstack

Edit /etc/chirpstack/chirpstack.toml as needed to add the PostgreSQL config, US regions, and API secret. Also, change the API bind address to only listen locally. The relevant lines are included here:

[postgresql]
  dsn="postgres://chirpstack:YOUR_PG_PASSWORD@localhost/chirpstack?sslmode=disable"

[network]
  enabled_regions=[
    "us915_0",
    "us915_1",
    "us915_2",
    "us915_3",
    "us915_4",
    "us915_5",
    "us915_6",
    "us915_7"
  ]

[api]
  bind="127.0.0.1:8080"
  secret="SOME_SECRET_VALUE_DONT_OVERTHINK_IT_BUT_ALSO_DONT_UNDERTHINK_IT"

Replace YOUR_PG_PASSWORD with whatever password you chose in the PostgreSQL step.

The API binding is changed from 0.0.0.0:8080 to 127.0.0.1:8080 to prevent the API from being exposed on port 8080 on the public IP address assigned to your instance. You will use a secure reverse proxy to reach it from the outside world instead.

The API secret just needs to be some random value; you won't use it anywhere else.

Finally, enable the ChirpStack service ("enable" means it will start at boot time), and ensure it is started right now with --now. Then verify that is it active:

sudo systemctl enable --now chirpstack
sudo systemctl status chirpstack # you should see "active (running)"

Chirpstack is installed, and its web interface is running locally on port 8080. You should not be able to reach it from your web browser at http://your.site.name:8080 (test to make sure).

Caddy

You need to make the ChirpStack web interface accessible over the internet. To do that, you will install the Caddy web server, set it to listen on ports 80 and 443, and proxy incoming traffic to the ChirpStack API (which is only listening on the local machine at port 8080).

First, you may need to allow traffic to ports 80 and 443 if your cloud provider's image includes Uncomplicated Firewall (ufw) by default:

sudo ufw allow http
sudo ufw allow https

Next, add the Caddy repository and install Caddy (cross-reference the official instructions):

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Caddy is now running. Modify /etc/caddy/Caddyfile to have the following:

your.site.name {
    reverse_proxy :8080
}

Reload Caddy:

sudo systemctl reload caddy

Wait a few minutes, then go to https://your.site.name/ in your browser. Notice that you are connected securely and that a certificate from ZeroSSL or Let's Encrypt was issued; Caddy automatically handles TLS certificate issuance and renewals for you.

(Optional) Run testssl.sh to verify security: clone, then ./testssl.sh your.site.name