ChirpStack einrichten – Schritt für Schritt

Diese Anleitung führt Sie durch eine vollständige ChirpStack-v4-Installation, von der Installation bis zum ersten Sensor, der Daten liefert. Wir zeigen beide offiziell unterstützten Wege, Docker Compose und die native Installation über APT, und ergänzen sie um die Stolperfallen, die im Produktivbetrieb am häufigsten Probleme machen. Am Ende läuft ein funktionierender LoRaWAN Network Server, an den Sie Gateways und Geräte anbinden können.

Praxis-Hinweis: Die Befehle beziehen sich auf ChirpStack v4 (Stand dieses Artikels: v4.18.0, Mai 2026). Die offiziellen Repositories liefern immer die aktuelle v4-Version. Prüfen Sie vor einem produktiven Setup die offizielle Dokumentation und ersetzen Sie alle Beispiel-Passwörter durch eigene.

Zwei Wege zur Installation

Es gibt zwei gängige Wege, ChirpStack v4 aufzusetzen, und sie zielen auf unterschiedliche Situationen:

• Docker Compose (Variante A): am schnellsten zum Ausprobieren, reproduzierbar und sauber gekapselt. Alle Komponenten laufen in Containern, nichts wird fest aufs System installiert. Ideal für Tests, Demos und Edge-Geräte.
• Native Installation über APT (Variante B): der klassische Weg für einen dedizierten Server. Volle Kontrolle über jede Komponente, einfacher zu überwachen und abzusichern. Die richtige Wahl für den langfristigen Produktivbetrieb.

Wenn Sie nur schnell sehen wollen, ob ChirpStack zu Ihnen passt, nehmen Sie Docker. Für einen Server, den Sie dauerhaft betreiben, lohnt sich der native Weg. Die Schritte danach (Gateway und Gerät anbinden) sind für beide Wege identisch.

Voraussetzungen

Für beide Wege brauchen Sie:

• einen Server mit aktuellem Debian oder Ubuntu (root- bzw. sudo-Zugriff)
• ein LoRaWAN-Gateway, das Semtech UDP oder Basics Station spricht (z. B. Milesight, Kerlink, Dragino, RAK)
• Grundkenntnisse im Umgang mit der Linux-Kommandozeile
• die richtige Frequenz-Region für Ihr Land, im DACH-Raum und der restlichen EU ist das EU868

Für Docker (Variante A) brauchen Sie zusätzlich nur Docker selbst, PostgreSQL, Redis und Mosquitto bringt das Compose-Setup als Container mit. Für die native Installation (Variante B) installieren Sie diese Komponenten selbst; ChirpStack v4 setzt PostgreSQL 13+, Redis 6.2+ und einen MQTT-v5-fähigen Broker voraus.

Variante A: ChirpStack mit Docker Compose

Docker Compose orchestriert alle nötigen Container (ChirpStack, Gateway Bridge, PostgreSQL, Redis, Mosquitto) aus einer einzigen Datei. ChirpStack stellt dafür ein offizielles Beispiel-Repository bereit, das Sie als Ausgangspunkt nehmen.

Wichtig vorab: Das offizielle Compose-Setup ist ausdrücklich als Test- und Einstiegs-Skeleton gedacht. Für den Produktivbetrieb (TLS, abgesicherte Ports, eigene Passwörter, Backups) müssen Sie es anpassen. Mehr dazu am Ende dieser Variante.

A1 – Docker installieren

Sie brauchen Docker inklusive des Compose-Plugins (Compose v2, also der Befehl docker compose mit Leerzeichen, nicht das veraltete docker-compose). Die maßgebliche und stets aktuelle Anleitung steht unter docs.docker.com/engine/install/. Auf einem aktuellen Debian/Ubuntu installieren Sie Docker über das offizielle Docker-Repository:

# Vollständige, aktuelle Anleitung: https://docs.docker.com/engine/install/
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") 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-buildx-plugin docker-compose-plugin

Schreibweise: Verwenden Sie docker compose (mit Leerzeichen, das aktuelle v2-Plugin), nicht das veraltete docker-compose mit Bindestrich. Ältere Anleitungen im Netz zeigen oft noch die alte Schreibweise.

A2 – Repository klonen

ChirpStack pflegt ein fertiges Compose-Skeleton unter github.com/chirpstack/chirpstack-docker. Klonen Sie es und wechseln Sie hinein:

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

Im Repository finden Sie die docker-compose.yml sowie ein configuration/-Verzeichnis mit den Konfigurationsdateien für ChirpStack, die Gateway Bridge, Mosquitto und die PostgreSQL-Initialisierung. Die mitgelieferten Hilfs-Images sind PostgreSQL 14, Redis 7 und Mosquitto 2; PostgreSQL- und Redis-Daten landen in den Docker-Volumes postgresqldata und redisdata und überleben damit einen Neustart.

A3 – Region und Topic-Präfix prüfen

⚠️ Häufige Stolperfalle, auch im Docker-Weg: Das Compose-Setup ist für alle Regionen vorbereitet, die Gateway-Bridge-Instanz ist aber standardmäßig auf das eu868-Präfix konfiguriert. Weicht Ihre Region davon ab, müssen Sie in der docker-compose.yml beim Dienst chirpstack-gateway-bridge das eu868-Präfix in den Topic-Templates durch das Präfix Ihrer Region ersetzen (z. B. us915_0, au915_0, in865). Stimmt das Präfix nicht mit der aktiven Region überein, verbindet sich das Gateway zwar, aber ChirpStack sieht seine Daten nie. Das ist im Docker-Weg die exakt gleiche Fehlerquelle wie bei der nativen Installation.

Konkret betrifft das diese Zeilen im environment-Block des Dienstes chirpstack-gateway-bridge:

- INTEGRATION__MQTT__EVENT_TOPIC_TEMPLATE=eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}
- INTEGRATION__MQTT__STATE_TOPIC_TEMPLATE=eu868/gateway/{{ .GatewayID }}/state/{{ .StateType }}
- INTEGRATION__MQTT__COMMAND_TOPIC_TEMPLATE=eu868/gateway/{{ .GatewayID }}/command/#

Für den DACH-Raum bleibt es bei eu868, hier müssen Sie nichts ändern. Die Liste der aktiven Regionen steht in configuration/chirpstack/chirpstack.toml unter enabled_regions, das passende topic_prefix je Region in der jeweiligen region_XXX.toml.

A4 – Container starten

Starten Sie den gesamten Stack. Im Vordergrund (so zeigt es die offizielle Anleitung, gut zum Mitlesen):

docker compose up

Für den Dauerbetrieb starten Sie ihn losgelöst im Hintergrund:

docker compose up -d

Beim ersten Start lädt Docker alle Images und initialisiert die Datenbank, das dauert einen Moment. Logs und eventuelle Fehler sehen Sie mit docker compose logs -f, herunterfahren mit docker compose down (die Daten bleiben in den Volumes erhalten).

A5 – Weboberfläche öffnen

Sobald alle Container laufen, erreichen Sie:

• die Weboberfläche unter http://SERVER-IP:8080/
• die REST-API unter http://SERVER-IP:8090/

Melden Sie sich mit den Standard-Zugangsdaten an: Benutzer admin, Passwort admin.

⚠️ Sofort ändern: Ändern Sie das Standardpasswort unmittelbar nach dem ersten Login. Ein erreichbarer Network Server mit admin/admin ist eine offene Tür.

Vom Test zum Betrieb: Das Compose-Skeleton bringt Sie schnell zum Laufen, ist aber kein Produktiv-Setup. Für den Dauerbetrieb fehlen TLS, ein Reverse Proxy, abgesicherte Ports, eigene Passwörter und eine Backup-Strategie. Genau diese Härtung nehmen wir Ihnen ab, als Managed ChirpStack auf europäischer Infrastruktur oder vorinstalliert auf dem merkaio edge pro.

Wenn Ihr Stack läuft, springen Sie weiter zu Gateway und erstes Gerät anbinden.

Variante B: Native Installation über APT

Dieser Weg installiert ChirpStack und alle Komponenten direkt auf einem Debian/Ubuntu-Server. Er gibt Ihnen die volle Kontrolle über jede Komponente und ist der empfohlene Weg für einen Server, den Sie langfristig produktiv betreiben.

Schritt 1 – Abhängigkeiten installieren

ChirpStack v4 braucht drei Bausteine im Hintergrund: PostgreSQL als Datenbank, Redis für Geräte- und Sitzungszustände und einen MQTT-Broker (in der Praxis Mosquitto). Die offizielle Anleitung installiert alle zusammen:

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

Danach legen Sie in PostgreSQL die ChirpStack-Datenbank, einen Datenbanknutzer und die benötigte Extension an. ChirpStack v4 setzt pg_trgm voraus (und nur diese, das frühere hstore aus v3 brauchen Sie nicht).

sudo -u postgres psql

-- Rolle für die Anmeldung anlegen
create role chirpstack with login password 'chirpstack';

-- Datenbank anlegen
create database chirpstack with owner chirpstack;

-- in die chirpstack-Datenbank wechseln
\c chirpstack

-- benötigte Extension aktivieren
create extension pg_trgm;

-- psql verlassen
\q

Sicherheit: Ändern Sie 'chirpstack' als Passwort in einen eigenen, starken Wert. Den passen Sie dann in Schritt 3 in der dsn entsprechend an.

Schritt 2 – ChirpStack installieren

ChirpStack wird über das offizielle APT-Repository installiert. Zuerst hinterlegen Sie den Signaturschlüssel und die Paketquelle:

sudo apt install gpg
sudo mkdir -p /etc/apt/keyrings/
sudo sh -c 'wget -q -O - https://artifacts.chirpstack.io/packages/chirpstack.key | gpg --dearmor > /etc/apt/keyrings/chirpstack.gpg'
echo "deb [signed-by=/etc/apt/keyrings/chirpstack.gpg] https://artifacts.chirpstack.io/packages/4.x/deb stable main" | sudo tee /etc/apt/sources.list.d/chirpstack.list
sudo apt update

Dann installieren Sie ChirpStack selbst und die Gateway Bridge, die das Gateway-Protokoll in MQTT übersetzt:

sudo apt install chirpstack-gateway-bridge
sudo apt install chirpstack

Hinweis zur Gateway Bridge: Sie kann auf dem Server laufen (einfacher Start) oder direkt auf dem Gateway (sauberer bei vielen Standorten). Läuft sie auf dem Gateway, können Sie den chirpstack-gateway-bridge auf dem Server weglassen.

Schritt 3 – ChirpStack konfigurieren

Die Konfiguration liegt in /etc/chirpstack/, mit einer globalen chirpstack.toml und je Region einer eigenen Datei. In der chirpstack.toml setzen Sie Datenbank, Redis, MQTT, die aktiven Regionen und das API-Secret:

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

[redis]
  servers = ["redis://localhost/"]

[network]
  # nur die Region(en) aktivieren, die Sie wirklich brauchen
  enabled_regions = ["eu868"]

[api]
  # mit: openssl rand -base64 32 erzeugen
  secret = "HIER-EIGENES-SECRET-EINSETZEN"

[integration]
  enabled = ["mqtt"]

  [integration.mqtt]
    server = "tcp://localhost:1883/"
    json = true

Das API-Secret erzeugen Sie mit openssl rand -base64 32.

Schritt 4 – Gateway Bridge konfigurieren

Das ist der Schritt, an dem die meisten nativen Setups scheitern. Die Konfiguration der Gateway Bridge liegt in /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml.

⚠️ Häufige Stolperfalle (verifiziert): ChirpStack v4 erwartet serverseitig für EU868 ein Region-Präfix in den Gateway-MQTT-Topics (eu868/gateway/..., gesetzt in der region_eu868.toml über topic_prefix = "eu868"). Die Gateway Bridge wird aber ohne dieses Präfix ausgeliefert. Wenn beide Seiten nicht übereinstimmen, verbindet sich das Gateway zwar, aber ChirpStack sieht nie seine Daten. Passen Sie deshalb die Topics der Gateway Bridge an das Präfix an:

[integration.mqtt]
  event_topic_template="eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}"
  command_topic_template="eu868/gateway/{{ .GatewayID }}/command/#"

Wichtig zur Einordnung: Dieses Präfix betrifft nur die Gateway-Topics. Die Application-Event-Topics, über die Ihre Anwendung später die Sensordaten bekommt (application/.../event/up), tragen kein Präfix. Genau diese Unterscheidung ist beim Umstieg von v3 die häufigste Verwirrung.

Schritt 5 – Dienste starten

Jetzt starten Sie beide Dienste und aktivieren den Autostart:

sudo systemctl start chirpstack-gateway-bridge
sudo systemctl enable chirpstack-gateway-bridge

sudo systemctl start chirpstack
sudo systemctl enable chirpstack

Ob ChirpStack sauber hochkommt, sehen Sie im Log mit sudo journalctl -f -n 100 -u chirpstack.

Schritt 6 – Web-Oberfläche öffnen

ChirpStack stellt Weboberfläche und API auf Port 8080 bereit. Öffnen Sie http://SERVER-IP:8080/ und melden sich mit Benutzer admin und Passwort admin an.

⚠️ Sofort ändern: Ändern Sie das Standardpasswort direkt nach dem ersten Login.

Gateway und erstes Gerät anbinden (für beide Varianten)

Ab hier ist der Weg identisch, egal ob Sie ChirpStack per Docker oder nativ installiert haben.

Erstes Gateway anbinden

Damit Funkdaten ankommen, muss Ihr Gateway den Server erreichen und korrekt registriert sein. Auf dem Gateway konfigurieren Sie den Semtech UDP Packet Forwarder so, dass er seine Daten an die Gateway Bridge schickt, standardmäßig auf UDP-Port 1700 des Servers. Alternativ unterstützt die Gateway Bridge die LoRa Basics Station.

In ChirpStack legen Sie das Gateway anschließend mit seiner Gateway-EUI an. Die herstellerspezifischen Schritte (Server-Adresse, Port und Protokoll auf dem Gateway eintragen) unterscheiden sich je nach Modell. Welche Hardware sich sauber in ChirpStack integriert, finden Sie in unserer Übersicht zu Milesight-Gateways und -Sensoren.

Praxis-Tipp: Die häufigste Ursache für ein Gateway, das „nicht auftaucht", ist eine falsch eingetragene Gateway-EUI, ein nicht passendes Topic-Präfix oder eine Firewall, die UDP-Port 1700 blockiert. Prüfen Sie das in dieser Reihenfolge.

Erstes Gerät registrieren

Bevor ein Sensor Daten liefern kann, muss ChirpStack ihn kennen. Dazu legen Sie ein Device Profile an (Region, LoRaWAN-Version, Geräteklasse A/B/C) und registrieren das Gerät mit seiner DevEUI und dem AppKey.

Bei der Aktivierung gibt es zwei Verfahren:

• OTAA (Over-the-Air Activation): Das Gerät handelt seine Schlüssel beim Beitritt zum Netz aus. Sicherer und der Standard für die meisten Sensoren.
• ABP (Activation by Personalization): Die Schlüssel sind fest hinterlegt. Einfacher, aber weniger sicher und unflexibler.

Praxis-Tipp: Nehmen Sie im Zweifel OTAA. Fast alle modernen Sensoren unterstützen es, und Sie vermeiden die typischen ABP-Probleme mit Frame-Countern.

Welche Geräteklasse (A, B oder C) für Ihren Anwendungsfall passt, erklären wir ausführlich in unserem Beitrag zu den LoRaWAN-Geräteklassen A, B und C.

Daten empfangen und prüfen

Sobald Gateway und Gerät eingerichtet sind, sollte der erste Uplink eintreffen. ChirpStack veröffentlicht die Daten über MQTT in einer festen Topic-Struktur:

• Uplink (Daten vom Gerät): application/{APPLICATION_ID}/device/{DEV_EUI}/event/up
• Downlink (Befehl an das Gerät): application/{APPLICATION_ID}/device/{DEV_EUI}/command/down

Mitlesen können Sie zum Test direkt am Broker:

mosquitto_sub -h localhost -t "application/#" -v

Ein Downlink-Befehl wird als JSON gesendet und enthält unter anderem devEui, confirmed, den fPort (größer als 0) und das data-Feld (Base64-codiert). Geben Sie entweder data (rohe Bytes) oder object (decodiert) an, nicht beides.

Die decodierten Messwerte eines Uplinks finden Sie im Feld object.

⚠️ Wichtig bei Migration von v3: In ChirpStack v3 hieß dieses Feld objectJSON und war ein String. In v4 ist es object, echtes eingebettetes JSON. Diese Breaking Change wird beim Umstieg regelmäßig übersehen und führt dazu, dass nachgelagerte Systeme plötzlich keine Werte mehr finden. Ein Detail noch: Das object-Feld erscheint nur, wenn auf dem Device Profile ein Payload-Codec hinterlegt ist. Die rohen Bytes liegen immer im separaten Feld data (Base64).

Nächster Schritt – Rohdaten decodieren

An diesem Punkt empfängt ChirpStack Daten, aber es sind zunächst nur Bytes. Damit aus einem Uplink wie 0175640367AD00046873 echte Werte werden (Batterie 100 %, Temperatur 17,3 °C, Luftfeuchte 57,5 %, das ist das Format der Milesight-EM300-Serie), brauchen Sie einen Payload-Decoder auf dem Device Profile. Eine eigene Anleitung dazu, wie Sie einen Decoder für ChirpStack v4 aus der Byte-Spezifikation schreiben statt ihn blind zu kopieren, folgt in diesem Wissensbereich.