ChirpStack and LoRaWAN Gateway Setup: Step by Step

You set up your own LoRaWAN network with ChirpStack in five steps: install ChirpStack with Docker Compose, connect the LoRaWAN gateway via the Semtech UDP Packet Forwarder or Basics Station, register the gateway in the web interface, create a device profile plus an application for OTAA, and read the decrypted payloads via MQTT. This guide walks you through a self-hosted setup on your own infrastructure step by step, with no cloud lock-in and no per-device licensing. It targets ChirpStack v4 (currently version 4.18, May 2026).

Prerequisites

Before you start, you need three things:

• A server or VM with Docker and Docker Compose, for example a small Linux VM on Proxmox, a Hetzner server or on-premises at the plant. For a pilot, 2 vCPU and 4 GB RAM are enough.
• A LoRaWAN gateway that speaks the Semtech UDP Packet Forwarder, the Semtech Basics Station or the ChirpStack MQTT Forwarder. That covers models from Multitech, Kerlink, Dragino, RAK Wireless or Milesight.
• At least one LoRaWAN sensor with a known DevEUI and AppKey that matches your radio region (EU868 in the DACH region).

What LoRaWAN does as a radio protocol and how the network server layer works is explained in the linked primers.

Step 1: Install ChirpStack with Docker Compose

ChirpStack ships a ready-made Compose skeleton that includes all required services. Clone the official repository and start the stack:

git clone https://github.com/chirpstack/chirpstack-docker.git
cd chirpstack-docker
docker compose up -d

This brings up the following containers: the ChirpStack server itself, the ChirpStack Gateway Bridge (one variant for Semtech UDP, one for Basics Station), the Mosquitto MQTT broker, PostgreSQL, Redis and an optional REST API. By default the EU868 region is configured; you change the region in chirpstack.toml inside the configuration/chirpstack/ directory.

Next open the web interface at http://SERVER-IP:8080 and log in with the default credentials admin / admin. Change the password immediately and create a dedicated user for production. The key ports at a glance:

The bundled docker-compose.yml is meant as a starting point for testing. For production you adjust passwords, TLS, volumes and backups.

Step 2: Connect the gateway (Semtech UDP or Basics Station)

ChirpStack does not receive the radio packets directly from the gateway but via the Gateway Bridge, which translates the packet forwarder protocol into MQTT. You have two common paths:

Semtech UDP Packet Forwarder (simple, maximum compatibility). In the gateway configuration (often global_conf.json or local_conf.json) set the ChirpStack host IP as the server and 1700 as both the up and down port:

"gateway_conf": {
  "server_address": "SERVER-IP",
  "serv_port_up": 1700,
  "serv_port_down": 1700
}

Semtech Basics Station (recommended for new production setups). The Basics Station connects via WebSocket and supports TLS. On the gateway you set the LNS URI to ws://SERVER-IP:3001 (or wss:// with certificates). Which path is available depends on your gateway firmware; many modern gateways support both.

Once the packet forwarder is running, the gateway already sends statistics and reception packets to the bridge, even if the gateway is not yet registered in ChirpStack.

Step 3: Register the gateway in ChirpStack

So that ChirpStack maps packets to a known gateway, register it in the web interface:

1. Switch to the relevant tenant (a default tenant exists in a standard install).
2. Open Gateways and click Add gateway.
3. Give it a name and enter the 64-bit gateway EUI. You read this from the gateway itself; it is often derived from the MAC address.
4. Save the gateway.

After a short while the status should switch to online and the LoRaWAN frames or Gateway statistics tab should show incoming data. If the gateway stays offline, check the firewall and port 1700/UDP between gateway and server, and verify the EUI.

Step 4: Create a device profile and application (OTAA)

Before a sensor can join, you need a device profile and an application.

Create a device profile. Under Device profiles create a profile that describes your device's capabilities:

• Region: for example EU868.
• LoRaWAN MAC version: such as 1.0.3 or 1.1, depending on the sensor.
• Regional Parameters revision: matching the MAC version.
• Activation: OTAA (over-the-air activation), the recommended, secure option over ABP.

Optionally add a payload codec that turns the raw bytes into readable fields.

Create the application and device. Under Applications create an application (for example "Temperature sensors plant 1"). Inside it click Add device and enter:

• the sensor's DevEUI (usually printed on the device or in the datasheet),
• the matching device profile.

After saving, open the Keys (OTAA) tab and enter the AppKey (for LoRaWAN 1.1 also the NwkKey). Now power on the sensor: in the LoRaWAN frames tab you first see a Join Request and shortly after a Join Accept. From now on the uplinks appear in the Events tab.

Step 5: Read sensor data via MQTT

As soon as the device joins, ChirpStack publishes every event to the internal MQTT broker. The topic scheme for uplinks is:

application/APPLICATION_ID/device/DEV_EUI/event/up

Alongside it there are further event types such as join, ack, txack, status and log. With the mosquitto_sub client you subscribe to all uplinks using wildcards:

mosquitto_sub -h SERVER-IP -t "application/+/device/+/event/up" -v

ChirpStack can emit payloads as Protobuf or JSON. For easy downstream processing, enable the JSON encoding via json=true in the [integration.mqtt] section of chirpstack.toml. The uplink event then contains, among other things, the decoded readings (object), metadata from the receiving gateways (RSSI, SNR), the frame counters and the spreading factor.

From here, MQTT is your universal integration point: you forward the values into a time-series database, into a Grafana IoT dashboard, into Node-RED or into a custom application, entirely on your own infrastructure and with no detour through a third-party cloud.

Common pitfalls

• Gateway stays offline: usually a firewall blocks port 1700/UDP, or the gateway EUI in ChirpStack does not match the real EUI.
• Join fails: wrong DevEUI/AppKey, wrong LoRaWAN version in the device profile, or a region that does not match the sensor.
• No MQTT data: the application ID or DevEUI in the topic is mistyped, or the sensor has not sent an uplink yet. Check the Events tab in the web interface first.
• Region mismatch: make sure the gateway, device profile and Gateway Bridge all use the same region (for example EU868).

Next steps

With these five steps you have a sovereign, self-hosted LoRaWAN network running on ChirpStack: open source under the MIT license, operated in the EU and free of per-device licensing. For production, topics such as TLS, high availability, backups, codecs and monitoring come on top. We handle that design, setup and operation entirely on your infrastructure on request. Learn more on our page about ChirpStack & LoRaWAN Network Server and in our overview of LoRaWAN solutions from WZ-IT. You can book a no-obligation initial consultation directly online.