Document environment configuration variables (#400)

* Document environment configuration variables

* Escape sed replacements when updating .env values

DOCKER.md

@@ -36,17 +36,24 @@ INSTANCE_DOMAIN=mesh.example.org
 
 Additional environment variables are optional:
 
-- `CHANNEL`, `FREQUENCY`, `MAP_CENTER`, `MAX_DISTANCE`, and `CONTACT_LINK`
-  customise the UI.
-- `POTATOMESH_INSTANCE` (defaults to `http://web:41447`) lets the ingestor post
-  to a remote PotatoMesh instance if you do not run both services together.
-- `CONNECTION` overrides the default serial device or network endpoint used by
-  the ingestor.
-- `CHANNEL_INDEX` selects the LoRa channel when using serial or Bluetooth
-  connections.
-- `INSTANCE_DOMAIN` pins the public hostname advertised by the web UI and API
-  responses, bypassing reverse DNS detection when set.
-- `DEBUG` enables verbose logging across the stack.
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `API_TOKEN` | _required_ | Shared secret used by the ingestor and API clients for authenticated `POST` requests. |
+| `INSTANCE_DOMAIN` | _auto-detected_ | Public hostname (optionally with port) advertised by the web UI, metadata, and API responses. |
+| `SITE_NAME` | `"PotatoMesh Demo"` | Title and branding surfaced in the web UI. |
+| `CHANNEL` | `"#LongFast"` | Default LoRa channel label displayed on the dashboard. |
+| `FREQUENCY` | `"915MHz"` | Default LoRa frequency description shown in the UI. |
+| `CONTACT_LINK` | `"#potatomesh:dod.ngo"` | Chat link or Matrix room alias rendered in UI footers and overlays. |
+| `MAP_CENTER` | `38.761944,-27.090833` | Latitude and longitude that centre the map view. |
+| `MAX_DISTANCE` | `42` | Maximum relationship distance (km) before edges are hidden. |
+| `DEBUG` | `0` | Enables verbose logging across services when set to `1`. |
+| `FEDERATION` | `1` | Controls whether the instance announces itself and crawls peers (`1`) or stays isolated (`0`). |
+| `PRIVATE` | `0` | Restricts public visibility and disables chat/message endpoints when set to `1`. |
+| `CONNECTION` | `/dev/ttyACM0` | Serial device, TCP endpoint, or Bluetooth target used by the ingestor to reach the radio. |
+
+The ingestor also respects supporting variables such as `POTATOMESH_INSTANCE`
+(defaults to `http://web:41447`) for remote posting and `CHANNEL_INDEX` when
+selecting a LoRa channel on serial or Bluetooth connections.
 
 ## Docker Compose file
 

README.md

@@ -70,15 +70,20 @@ exec ruby app.rb -p 41447 -o 0.0.0.0
 
 The web app can be configured with environment variables (defaults shown):
 
-* `SITE_NAME` - title and header shown in the UI (default: "PotatoMesh Demo")
-* `CHANNEL` - default channel shown in the UI (default: "#LongFast")
-* `FREQUENCY` - default frequency shown in the UI (default: "915MHz")
-* `MAP_CENTER` - default map center coordinates (default: `38.761944,-27.090833`)
-* `MAX_DISTANCE` - hide nodes farther than this distance from the center (default: `42`)
-* `CONTACT_LINK` - chat link or Matrix alias for footer and overlay (default: `#potatomesh:dod.ngo`)
-* `PRIVATE` - set to `1` to hide the chat UI, disable message APIs, and exclude hidden clients (default: unset)
-* `INSTANCE_DOMAIN` - public hostname (optionally with port) used for metadata, federation, and API links (default: auto-detected)
-* `FEDERATION` - set to `1` to announce your instance and crawl peers, or `0` to disable federation (default: `1`)
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `API_TOKEN` | _required_ | Shared secret that authorizes ingestors and API clients making `POST` requests. |
+| `INSTANCE_DOMAIN` | _auto-detected_ | Public hostname (optionally with port) used for metadata, federation, and generated API links. |
+| `SITE_NAME` | `"PotatoMesh Demo"` | Title and header displayed in the UI. |
+| `CHANNEL` | `"#LongFast"` | Default channel name displayed in the UI. |
+| `FREQUENCY` | `"915MHz"` | Default frequency description displayed in the UI. |
+| `CONTACT_LINK` | `"#potatomesh:dod.ngo"` | Chat link or Matrix alias rendered in the footer and overlays. |
+| `MAP_CENTER` | `38.761944,-27.090833` | Latitude and longitude that centre the map on load. |
+| `MAX_DISTANCE` | `42` | Maximum distance (km) before node relationships are hidden on the map. |
+| `DEBUG` | `0` | Set to `1` for verbose logging in the web and ingestor services. |
+| `FEDERATION` | `1` | Set to `1` to announce your instance and crawl peers, or `0` to disable federation. Private mode overrides this. |
+| `PRIVATE` | `0` | Set to `1` to hide the chat UI, disable message APIs, and exclude hidden clients from public listings. |
+| `CONNECTION` | `/dev/ttyACM0` | Serial device, TCP endpoint, or Bluetooth target used by the ingestor to reach the Meshtastic radio. |
 
 The application derives SEO-friendly document titles, descriptions, and social
 preview tags from these existing configuration values and reuses the bundled

configure.sh

@@ -56,10 +56,14 @@ read_with_default() {
 update_env() {
     local key="$1"
     local value="$2"
-    
+    local escaped_value
+
+    # Escape characters that would break the sed replacement delimiter or introduce backreferences
+    escaped_value=$(printf '%s' "$value" | sed -e 's/[&|]/\\&/g')
+
     if grep -q "^$key=" .env; then
         # Update existing value
-        sed -i.bak "s/^$key=.*/$key=$value/" .env
+        sed -i.bak "s|^$key=.*|$key=$escaped_value|" .env
     else
         # Add new value
         echo "$key=$value" >> .env
@@ -78,6 +82,8 @@ CONTACT_LINK=$(grep "^CONTACT_LINK=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '
 API_TOKEN=$(grep "^API_TOKEN=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '"' || echo "")
 POTATOMESH_IMAGE_ARCH=$(grep "^POTATOMESH_IMAGE_ARCH=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '"' || echo "linux-amd64")
 INSTANCE_DOMAIN=$(grep "^INSTANCE_DOMAIN=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '"' || echo "")
+DEBUG=$(grep "^DEBUG=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '"' || echo "0")
+CONNECTION=$(grep "^CONNECTION=" .env 2>/dev/null | cut -d'=' -f2- | tr -d '"' || echo "/dev/ttyACM0")
 
 echo "📍 Location Settings"
 echo "-------------------"
@@ -95,6 +101,7 @@ echo ""
 echo "💬 Optional Settings"
 echo "-------------------"
 read_with_default "Chat link or Matrix room (optional)" "$CONTACT_LINK" CONTACT_LINK
+read_with_default "Debug logging (1=enabled, 0=disabled)" "$DEBUG" DEBUG
 
 echo ""
 echo "🤝 Federation Settings"
@@ -116,6 +123,14 @@ echo "------------------"
 echo "Specify the Docker image architecture for your host (linux-amd64, linux-arm64, linux-armv7)."
 read_with_default "Docker image architecture" "$POTATOMESH_IMAGE_ARCH" POTATOMESH_IMAGE_ARCH
 
+echo ""
+echo "🔌 Ingestor Connection"
+echo "----------------------"
+echo "Define how the mesh ingestor connects to your Meshtastic device."
+echo "Use serial devices like /dev/ttyACM0, TCP endpoints such as tcp://host:port,"
+echo "or Bluetooth addresses when supported."
+read_with_default "Connection target" "$CONNECTION" CONNECTION
+
 echo ""
 echo "🌐 Domain Settings"
 echo "------------------"
@@ -164,10 +179,12 @@ update_env "FREQUENCY" "\"$FREQUENCY\""
 update_env "MAP_CENTER" "\"$MAP_CENTER\""
 update_env "MAX_DISTANCE" "$MAX_DISTANCE"
 update_env "CONTACT_LINK" "\"$CONTACT_LINK\""
+update_env "DEBUG" "$DEBUG"
 update_env "API_TOKEN" "$API_TOKEN"
 update_env "POTATOMESH_IMAGE_ARCH" "$POTATOMESH_IMAGE_ARCH"
 update_env "FEDERATION" "$FEDERATION"
 update_env "PRIVATE" "$PRIVATE"
+update_env "CONNECTION" "$CONNECTION"
 if [ -n "$INSTANCE_DOMAIN" ]; then
     update_env "INSTANCE_DOMAIN" "$INSTANCE_DOMAIN"
 else
@@ -205,6 +222,8 @@ echo "   Max Distance: ${MAX_DISTANCE}km"
 echo "   Channel: $CHANNEL"
 echo "   Frequency: $FREQUENCY"
 echo "   Chat: ${CONTACT_LINK:-'Not set'}"
+echo "   Debug Logging: ${DEBUG}" 
+echo "   Connection: ${CONNECTION}"
 echo "   API Token: ${API_TOKEN:0:8}..."
 echo "   Docker Image Arch: $POTATOMESH_IMAGE_ARCH"
 echo "   Private Mode: ${PRIVATE}"

web/lib/potato_mesh/config.rb

@@ -38,6 +38,20 @@ module PotatoMesh
     DEFAULT_FEDERATION_MAX_DOMAINS_PER_CRAWL = 256
     DEFAULT_INITIAL_FEDERATION_DELAY_SECONDS = 2
 
+    # Retrieve the configured API token used for authenticated requests.
+    #
+    # @return [String, nil] API token when provided, otherwise nil.
+    def api_token
+      fetch_string("API_TOKEN", nil)
+    end
+
+    # Retrieve an explicit instance domain override when present.
+    #
+    # @return [String, nil] hostname or host:port pair supplied via ENV.
+    def instance_domain
+      fetch_string("INSTANCE_DOMAIN", nil)
+    end
+
     # Determine whether private mode should be activated.
     #
     # @return [Boolean] true when PRIVATE=1 in the environment.
@@ -447,6 +461,13 @@ module PotatoMesh
       fetch_string("CONTACT_LINK", DEFAULT_CONTACT_LINK)
     end
 
+    # Retrieve the configured connection target for the ingestor service.
+    #
+    # @return [String] serial device, TCP endpoint, or Bluetooth target.
+    def connection_target
+      fetch_string("CONNECTION", "/dev/ttyACM0")
+    end
+
     # Determine the best URL to represent the configured contact link.
     #
     # @return [String, nil] absolute URL when derivable, otherwise nil.