From d51a36be0c5bdd3ef9c5aa0d5e7b98bbc8650806 Mon Sep 17 00:00:00 2001
From: gadgethd <111318106+gadgethd@users.noreply.github.com>
Date: Sun, 11 Oct 2026 05:21:19 +0000
Subject: [PATCH] docs(ingest): document
 MQTT_INGEST_CONNECTIONS/SHARE_GROUP/FLUSH_MS; make queue default 1000

---
 .env.example       | 13 ++++++++++++-
 docker-compose.yml |  6 ++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index a74aaad..28c6b87 100644
--- a/.env.example
+++ b/.env.example
@@ -36,7 +36,18 @@ MQTT_PASSWORD=change_me_strong_password
 # publications after a reconnect; the packet batch writer also retries transient
 # database failures.
 MQTT_MAX_PAYLOAD_BYTES=65536
-MQTT_INGEST_CONCURRENCY=8
+# Number of durable ingest connections (1-16). Each connection processes one
+# message at a time and acknowledges only after its database commit; values
+# above 1 distribute messages across the connections with a shared
+# subscription. 1 keeps single-connection behaviour exactly.
+MQTT_INGEST_CONNECTIONS=1
+# Shared-subscription group used when MQTT_INGEST_CONNECTIONS > 1.
+MQTT_INGEST_SHARE_GROUP=meshcore-ingest
+# How long a packet batch may wait for more packets before flushing (ms;
+# 0 flushes immediately).
+MQTT_INGEST_FLUSH_MS=10
+# Upper bound on queued-but-uncommitted packets; overflow leaves messages
+# unacknowledged so the broker redelivers them instead of growing memory.
 MQTT_INGEST_QUEUE_MAX=1000
 
 # Archive and remove repeater visibility after its own observer MQTT feed has
diff --git a/docker-compose.yml b/docker-compose.yml
index 999fb78..48ea680 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -116,9 +116,11 @@ services:
       WS_INITIAL_STATE_DB_TIMEOUT_MS: ${WS_INITIAL_STATE_DB_TIMEOUT_MS:-30000}
       WS_INITIAL_STATE_MAX_BYTES: ${WS_INITIAL_STATE_MAX_BYTES:-16777216}
       MQTT_MAX_PAYLOAD_BYTES: ${MQTT_MAX_PAYLOAD_BYTES:-65536}
-      MQTT_INGEST_CONCURRENCY: ${MQTT_INGEST_CONCURRENCY:-8}
+      MQTT_INGEST_CONNECTIONS: ${MQTT_INGEST_CONNECTIONS:-1}
+      MQTT_INGEST_SHARE_GROUP: ${MQTT_INGEST_SHARE_GROUP:-meshcore-ingest}
+      MQTT_INGEST_FLUSH_MS: ${MQTT_INGEST_FLUSH_MS:-10}
       # The 30s lifecycle deadline reserves 25s for MQTT disconnect and queue drain.
-      MQTT_INGEST_QUEUE_MAX: ${MQTT_INGEST_QUEUE_MAX:-20000}
+      MQTT_INGEST_QUEUE_MAX: ${MQTT_INGEST_QUEUE_MAX:-1000}
       PATH_RESOLVE_WORKERS: ${PATH_RESOLVE_WORKERS:-2}
       PATH_RESOLVE_BACKGROUND_QUEUE_MAX: ${PATH_RESOLVE_BACKGROUND_QUEUE_MAX:-128}
       PATH_RESOLVE_INTERACTIVE_QUEUE_MAX: ${PATH_RESOLVE_INTERACTIVE_QUEUE_MAX:-32}