ChirpStack

Deploys ChirpStack — a LoRaWAN network server — as a Docker Compose stack. The stack consists of four services: ChirpStack, PostgreSQL (database), Valkey (Redis-compatible cache), and Mosquitto (MQTT broker for gateway communication).

Requirements

• Docker >= 24
• community.docker Ansible collection >= 5.2.0
• community.crypto Ansible collection >= 3.2.1

Variables

Variable	Default	Description
chirpstack_instance	chirpstack	Unique instance name. Used as Compose project name and container name prefix.
chirpstack_docker_path	/docker/chirpstack	Host path for the Compose file, config, and init scripts (mounted read-only into containers).
chirpstack_data_path	/data/chirpstack	Host path for persistent data (PostgreSQL, Valkey).
chirpstack_version	4	ChirpStack image tag to deploy.
chirpstack_mosquitto_version	2	Mosquitto image tag.
chirpstack_valkey_version	9.1	Valkey image tag.
chirpstack_pg_version	18-alpine	PostgreSQL image tag. Pin to a specific digest in production.
chirpstack_db_name	chirpstack	Database name. Changing after initial deploy requires manual migration.
chirpstack_db_user	chirpstack	Database user. Changing after initial deploy requires manual migration.
chirpstack_db_pass	~	Database user password. Required. See Secret Generation.
chirpstack_api_secret	~	Secret used to sign ChirpStack JWT tokens. Required. See Secret Generation.
chirpstack_mqtt_port	~	Host port bound to the Mosquitto MQTT broker (container port 1883). Unset means no port is exposed.
chirpstack_web_port	~	Host port bound to the ChirpStack web UI and API (container port 8080). Unset means no port is exposed.
chirpstack_hostname	~	Public hostname for the ChirpStack web UI. When set, enables Traefik integration for both the web UI and MQTT broker.
chirpstack_traefik_certresolver	default	Traefik certificate resolver name.
chirpstack_traefik_web_entrypoint	websecure	Traefik entrypoint name for the web UI HTTPS router.
chirpstack_traefik_mqtt_entrypoint	mqtt	Traefik entrypoint name for the MQTT TCP router.
chirpstack_uninstall	false	Stops and removes all containers and the compose directory.
chirpstack_purge	false	Also removes chirpstack_data_path. Requires chirpstack_uninstall: true. Irreversible.

Secret Generation

Both secrets must be set before the first deploy:

openssl rand -base64 32                                        # → chirpstack_api_secret
LC_ALL=C </dev/urandom tr -dc A-Za-z0-9 | head -c 28          # → chirpstack_db_pass

Copy the output values into your inventory:

chirpstack_api_secret: "..."
chirpstack_db_pass: "..."

Usage

Minimal setup:

chirpstack_api_secret: "{{ vault_chirpstack_api_secret }}"
chirpstack_db_pass: "{{ vault_chirpstack_db_pass }}"

Traefik

Setting chirpstack_hostname enables Traefik integration. The role attaches both ChirpStack and Mosquitto to the external traefik_web network and adds routing labels:

• Web UI / API — HTTPS router on the websecure entrypoint for chirpstack_hostname
• MQTT — TCP router on the chirpstack_traefik_mqtt_entrypoint entrypoint (default: mqtt) for the same hostname, with TLS via SNI

chirpstack_hostname: "chirpstack.example.com"
chirpstack_traefik_certresolver: default
chirpstack_traefik_web_entrypoint: websecure
chirpstack_traefik_mqtt_entrypoint: mqtt # must be defined in Traefik's static config on port 8883

Leave chirpstack_web_port and chirpstack_mqtt_port unset when using Traefik so ports are not also bound directly on the host.

Note: The MQTT TCP router uses HostSNI routing, which requires TLS — Traefik reads the hostname from the TLS ClientHello. MQTT clients must connect with TLS enabled (port 8883 on the Traefik side). Traefik terminates TLS and forwards plain TCP to Mosquitto on port 1883. Most modern MQTT clients (Paho, mosquitto_pub, ChirpStack gateway bridge) support TLS with SNI.

Uninstall

To stop and remove all containers and the compose directory:

chirpstack_uninstall: true

To also wipe all persistent data including the database and cache (irreversible):

chirpstack_uninstall: true
chirpstack_purge: true

Notes

• Both secret variables (chirpstack_api_secret, chirpstack_db_pass) should be stored in Ansible Vault.
• ChirpStack is configured for the EU868 region out of the box. The region config is at files/chirpstack/region_eu868.toml.
• The role generates a self-signed CA keypair (ca.pem, ca-key.pem) in chirpstack_docker_path/chirpstack/. ChirpStack uses this CA to issue client certificates to gateways for mTLS authentication.
• PostgreSQL is initialised with the pg_trgm and hstore extensions required by ChirpStack's schema migrations. The init script runs only on first start (empty data directory); if the data directory already exists without the extensions, re-initialise by removing chirpstack_data_path/db and restarting the db container.
• Mosquitto runs with anonymous access enabled on port 1883. Restrict access at the network level if the host is exposed.