ChirpStack Proxmox Community Script

Community-Scripts-style LXC installer for ChirpStack v4.

• ct/chirpstack.sh – Proxmox LXC creation wrapper and update routine.
• install/chirpstack-install.sh – installs ChirpStack plus PostgreSQL, Redis, Mosquitto.
• json/chirpstack.json – ProxmoxVED metadata.

The installer uses Debian 13, an unprivileged LXC, 2 CPU cores, 2 GB RAM and a 10 GB disk by default. Advanced setup in the Community Scripts framework can override these values.

The ChirpStack APT repository is configured exactly as documented upstream. A random PostgreSQL password and ChirpStack API secret are generated during initial installation and stored in /root/chirpstack.creds (mode 600). The package-provided /etc/chirpstack/chirpstack.toml is preserved and only its PostgreSQL DSN and API secret are changed.

PostgreSQL, Redis and Mosquitto are installed and configured inside the container by default.

Set environment variables before running the installer to use existing PostgreSQL and/or MQTT infrastructure at install time instead of installing them locally.

Examples:

# Default – everything local
bash install/chirpstack-install.sh

# External PostgreSQL only, MQTT stays local
EXTERNAL_POSTGRES_HOST=192.168.1.10 \
  EXTERNAL_POSTGRES_PASSWORD=secret \
  bash install/chirpstack-install.sh

# External PostgreSQL AND external MQTT
EXTERNAL_POSTGRES_HOST=192.168.1.10 \
  EXTERNAL_POSTGRES_PASSWORD=secret \
  EXTERNAL_MQTT_HOST=192.168.1.11 \
  EXTERNAL_MQTT_USERNAME=chirpstack \
  EXTERNAL_MQTT_PASSWORD=mqttsecret \
  bash install/chirpstack-install.sh

After installation you can switch between local and external services at any time by editing the ChirpStack configuration directly and restarting:

# Edit PostgreSQL DSN and/or MQTT server address
nano /etc/chirpstack/chirpstack.toml

# Restart to apply changes
systemctl restart chirpstack

The configuration relevant for external services is:

• PostgreSQL DSN: Look for dsn = "postgres://..." – change host, port, user, password and database name as needed.
• MQTT broker: Look for server = "tcp://localhost:1883" (appears in both [chirpstack.mqtt] and [integration.mqtt.mqtt] sections).

Running the Community Scripts update path:

1. Checks the installed and candidate chirpstack package versions.
2. Creates /root/chirpstack-backups/<timestamp>/.
3. Copies /etc/chirpstack into the backup.
4. Creates a custom-format PostgreSQL dump (chirpstack.pgdump).
   • Local DB: Uses runuser -u postgres -- pg_dump (Unix socket).
   • External DB: Reads connection parameters from /root/chirpstack.creds and uses pg_dump -h <host>.
   • Neither found: Warning is shown, backup continues without DB dump.
5. Upgrades only the chirpstack APT package.
6. Restarts ChirpStack and verifies that the service is active.

Existing configuration, database credentials and application data are not regenerated during updates.

Place the files at their matching repository paths (ct/, install/, json/) and change the two ProxmoxVED/main raw URLs in ct/chirpstack.sh to your fork / branch while testing.

Then run on the Proxmox host:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR-USER/ProxmoxVED/YOUR-BRANCH/ct/chirpstack.sh)"

After installation:

• UI: http://<LXC-IP>:8080
• Initial login: admin / admin
• Generated secrets: /root/chirpstack.creds
• Post-install switching: nano /etc/chirpstack/external-services.env && chirpstack-reconfigure

ChirpStack's Debian quickstart requires PostgreSQL, Redis and an MQTT broker. Redis is always installed locally (lightweight, no external operation needed). PostgreSQL and Mosquitto can optionally use external infrastructure either at install time or post-install via the config file.

Gateways must publish into the MQTT topics expected by the enabled ChirpStack region configuration; gateways using a UDP packet-forwarder normally also require ChirpStack Gateway Bridge (often installed on the gateway itself).