# ChirpStack LoRaWAN Server

> Open-source LoRaWAN network server with device management and MQTT integration.

- Category: Home Lab & Self-Hosting
- Difficulty: advanced
- Components: chirpstack, chirpstack-gateway-bridge, postgresql, redis, mosquitto
- Tags: chirpstack, lorawan, iot, mqtt, network-server
- Source: https://docker.recipes/homelab/chirpstack-lorawan

## Overview

ChirpStack is an open-source LoRaWAN network server that provides complete infrastructure for managing LoRa gateways and end-devices. Originally forked from LoRa Server in 2018, ChirpStack has evolved into the most widely adopted LoRaWAN network server solution, offering device provisioning, data routing, and application integration capabilities. The platform handles the complex LoRaWAN protocol stack, including MAC commands, ADR (Adaptive Data Rate), and device session management, making it essential for IoT deployments requiring long-range, low-power connectivity.

This stack combines ChirpStack's core network server with chirpstack-gateway-bridge for protocol translation, creating a complete LoRaWAN infrastructure. PostgreSQL stores device configurations, frame logs, and network topology data, while Redis provides high-speed caching for device sessions and downlink queue management. Eclipse Mosquitto handles MQTT messaging between components and external applications, enabling real-time data flow from LoRa devices to backend systems. The gateway bridge converts Semtech UDP protocol packets from LoRa gateways into MQTT messages that ChirpStack can process.

This configuration targets IoT system integrators, smart city developers, and industrial automation teams who need enterprise-grade LoRaWAN infrastructure without vendor lock-in. Agricultural monitoring companies, smart building operators, and research institutions particularly benefit from ChirpStack's flexibility in handling diverse device types and custom application integrations. The stack's modular architecture allows scaling from single-gateway deployments to multi-tenant networks supporting thousands of devices across multiple regions.

## Features

- Multi-tenant LoRaWAN network server supporting multiple organizations and applications with role-based access control
- Real-time device management with ADR, MAC command handling, and over-the-air device configuration
- Semtech UDP to MQTT protocol bridge enabling integration with various LoRa gateway manufacturers
- PostgreSQL-backed device registry with comprehensive frame logging and network analytics
- Redis-powered device session caching for sub-second downlink message delivery
- MQTT integration layer supporting custom payload codecs and third-party application connections
- Web-based management interface with device provisioning, gateway monitoring, and network visualization
- RESTful and gRPC APIs for programmatic device management and data integration

## Use cases

- Smart agriculture deployments monitoring soil sensors, weather stations, and livestock tracking across large farm operations
- Industrial IoT networks connecting factory sensors, asset trackers, and environmental monitoring equipment
- Smart city infrastructure managing parking sensors, air quality monitors, and waste management systems
- Research institutions studying LoRaWAN performance, device behavior, and network optimization
- Private LoRaWAN networks for enterprises requiring data sovereignty and custom security policies
- Multi-tenant service providers offering LoRaWAN connectivity to multiple customers and applications
- Homelab enthusiasts experimenting with LoRa devices, gateway configurations, and IoT data processing

## Prerequisites

- Minimum 2GB RAM for PostgreSQL database operations and ChirpStack device session management
- LoRa gateway supporting Semtech UDP protocol forwarder (packet_forwarder) pointed to port 1700
- Understanding of LoRaWAN concepts including device classes, join procedures, and frame counters
- Network access for MQTT clients connecting to port 1883 for application data integration
- Basic knowledge of device EUIs, application keys, and LoRaWAN security mechanisms
- Port 8080 available for ChirpStack web interface access and API endpoints

## docker-compose.yml

```yaml
services:
  chirpstack:
    image: chirpstack/chirpstack:latest
    ports:
      - "8080:8080"
    environment:
      POSTGRESQL__DSN: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/chirpstack?sslmode=disable
      REDIS__URL: redis://redis:6379
      MQTT__SERVER: tcp://mosquitto:1883
    depends_on:
      - postgres
      - redis
      - mosquitto
    networks:
      - chirpstack-net
    restart: unless-stopped

  chirpstack-gateway-bridge:
    image: chirpstack/chirpstack-gateway-bridge:latest
    ports:
      - "1700:1700/udp"
    environment:
      MQTT__SERVER: tcp://mosquitto:1883
    depends_on:
      - mosquitto
    networks:
      - chirpstack-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: chirpstack
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - chirpstack-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - chirpstack-net
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:latest
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mosquitto_data:/mosquitto/data
    networks:
      - chirpstack-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  mosquitto_data:

networks:
  chirpstack-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=chirpstack
POSTGRES_PASSWORD=secure_postgres_password
```

## Usage notes

- ChirpStack at http://localhost:8080
- Default login: admin / admin
- Gateway Bridge UDP at port 1700
- MQTT broker at port 1883

## Troubleshooting

- ChirpStack web interface shows 'Database connection failed': Verify PostgreSQL container is running and POSTGRES_USER/POSTGRES_PASSWORD environment variables match between services
- Gateway appears offline in ChirpStack dashboard: Check that gateway's packet forwarder is configured to send UDP packets to Docker host IP on port 1700, not localhost
- Device join requests failing with 'MIC mismatch': Ensure device AppEUI, DevEUI, and AppKey are correctly entered in ChirpStack web interface and match device firmware configuration
- Redis connection errors in ChirpStack logs: Verify Redis container is healthy and accessible on port 6379 within the chirpstack-net Docker network
- MQTT messages not reaching external applications: Check that mosquitto.conf allows external connections and clients are connecting to correct Docker host IP on port 1883
- High memory usage in PostgreSQL container: Tune PostgreSQL shared_buffers and work_mem parameters based on expected device count and frame logging requirements

