docker.recipes

ChirpStack LoRaWAN Server

advanced

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

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.

Key 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

Common Use Cases

  • 1Smart agriculture deployments monitoring soil sensors, weather stations, and livestock tracking across large farm operations
  • 2Industrial IoT networks connecting factory sensors, asset trackers, and environmental monitoring equipment
  • 3Smart city infrastructure managing parking sensors, air quality monitors, and waste management systems
  • 4Research institutions studying LoRaWAN performance, device behavior, and network optimization
  • 5Private LoRaWAN networks for enterprises requiring data sovereignty and custom security policies
  • 6Multi-tenant service providers offering LoRaWAN connectivity to multiple customers and applications
  • 7Homelab 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  chirpstack: 
3    image: chirpstack/chirpstack:latest
4    ports: 
5      - "8080:8080"
6    environment: 
7      POSTGRESQL__DSN: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/chirpstack?sslmode=disable
8      REDIS__URL: redis://redis:6379
9      MQTT__SERVER: tcp://mosquitto:1883
10    depends_on: 
11      - postgres
12      - redis
13      - mosquitto
14    networks: 
15      - chirpstack-net
16    restart: unless-stopped
17
18  chirpstack-gateway-bridge: 
19    image: chirpstack/chirpstack-gateway-bridge:latest
20    ports: 
21      - "1700:1700/udp"
22    environment: 
23      MQTT__SERVER: tcp://mosquitto:1883
24    depends_on: 
25      - mosquitto
26    networks: 
27      - chirpstack-net
28    restart: unless-stopped
29
30  postgres: 
31    image: postgres:16-alpine
32    environment: 
33      POSTGRES_USER: ${POSTGRES_USER}
34      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
35      POSTGRES_DB: chirpstack
36    volumes: 
37      - postgres_data:/var/lib/postgresql/data
38    networks: 
39      - chirpstack-net
40    restart: unless-stopped
41
42  redis: 
43    image: redis:7-alpine
44    volumes: 
45      - redis_data:/data
46    networks: 
47      - chirpstack-net
48    restart: unless-stopped
49
50  mosquitto: 
51    image: eclipse-mosquitto:latest
52    ports: 
53      - "1883:1883"
54    volumes: 
55      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
56      - mosquitto_data:/mosquitto/data
57    networks: 
58      - chirpstack-net
59    restart: unless-stopped
60
61volumes: 
62  postgres_data: 
63  redis_data: 
64  mosquitto_data: 
65
66networks: 
67  chirpstack-net: 
68    driver: bridge

.env Template

.env
1# PostgreSQL
2POSTGRES_USER=chirpstack
3POSTGRES_PASSWORD=secure_postgres_password

Usage Notes

  1. 1ChirpStack at http://localhost:8080
  2. 2Default login: admin / admin
  3. 3Gateway Bridge UDP at port 1700
  4. 4MQTT broker at port 1883

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

chirpstack
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
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
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
redis:
  image: redis:7-alpine
  volumes:
    - redis_data:/data
  networks:
    - chirpstack-net
  restart: unless-stopped
mosquitto
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

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  chirpstack:
5    image: chirpstack/chirpstack:latest
6    ports:
7      - "8080:8080"
8    environment:
9      POSTGRESQL__DSN: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/chirpstack?sslmode=disable
10      REDIS__URL: redis://redis:6379
11      MQTT__SERVER: tcp://mosquitto:1883
12    depends_on:
13      - postgres
14      - redis
15      - mosquitto
16    networks:
17      - chirpstack-net
18    restart: unless-stopped
19
20  chirpstack-gateway-bridge:
21    image: chirpstack/chirpstack-gateway-bridge:latest
22    ports:
23      - "1700:1700/udp"
24    environment:
25      MQTT__SERVER: tcp://mosquitto:1883
26    depends_on:
27      - mosquitto
28    networks:
29      - chirpstack-net
30    restart: unless-stopped
31
32  postgres:
33    image: postgres:16-alpine
34    environment:
35      POSTGRES_USER: ${POSTGRES_USER}
36      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
37      POSTGRES_DB: chirpstack
38    volumes:
39      - postgres_data:/var/lib/postgresql/data
40    networks:
41      - chirpstack-net
42    restart: unless-stopped
43
44  redis:
45    image: redis:7-alpine
46    volumes:
47      - redis_data:/data
48    networks:
49      - chirpstack-net
50    restart: unless-stopped
51
52  mosquitto:
53    image: eclipse-mosquitto:latest
54    ports:
55      - "1883:1883"
56    volumes:
57      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
58      - mosquitto_data:/mosquitto/data
59    networks:
60      - chirpstack-net
61    restart: unless-stopped
62
63volumes:
64  postgres_data:
65  redis_data:
66  mosquitto_data:
67
68networks:
69  chirpstack-net:
70    driver: bridge
71EOF
72
73# 2. Create the .env file
74cat > .env << 'EOF'
75# PostgreSQL
76POSTGRES_USER=chirpstack
77POSTGRES_PASSWORD=secure_postgres_password
78EOF
79
80# 3. Start the services
81docker compose up -d
82
83# 4. View logs
84docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/chirpstack-lorawan/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

chirpstackchirpstack-gateway-bridgepostgresqlredismosquitto

Tags

#chirpstack#lorawan#iot#mqtt#network-server

Category

Home Lab & Self-Hosting

Related Recipes

Ad Space