feat: federation auto-bootstrap in container entrypoint

- Auto-generate stable BOJ_NODE_ID from hostname + random suffix,
  persist to data volume across restarts
- Background seed bootstrap: wait for REST health, then POST each
  seed node to /umoja/peers (BOJ_SEED_NODES env or built-in defaults)
- Quadlet updated with seed node and node ID documentation

One-click node setup now auto-joins the Umoja federation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hyperpolymath

container/boj-community-node.container

@@ -45,6 +45,11 @@ Environment=APP_DATA_DIR=/data
 Environment=APP_LOG_FORMAT=json
 Environment=BOJ_QUIC=1
 Environment=BOJ_FEDERATION_PORT=9999
+# Node auto-joins the Umoja federation on startup using these seed nodes.
+# Override with a comma-separated list if running a private network.
+# Environment=BOJ_SEED_NODES=eu.boj.hyperpolymath.dev:9999,us.boj.hyperpolymath.dev:9999
+# Node ID is auto-generated and persisted in the data volume.
+# Set explicitly to override: Environment=BOJ_NODE_ID=my-node-name
 
 # Security hardening
 ReadOnly=true

container/entrypoint.sh

@@ -47,17 +47,84 @@ if [ -d "${APP_DATA_DIR:-/data}" ]; then
     fi
 fi
 
+# ---------------------------------------------------------------------------
+# Node ID auto-generation
+# ---------------------------------------------------------------------------
+#
+# If BOJ_NODE_ID is not set, generate a stable one from the hostname.
+# Persist to DATA_DIR so identity survives restarts.
+
+DATA_DIR="${APP_DATA_DIR:-/data}"
+NODE_ID_FILE="${DATA_DIR}/.node-id"
+
+if [ -z "${BOJ_NODE_ID:-}" ]; then
+    if [ -f "$NODE_ID_FILE" ]; then
+        BOJ_NODE_ID=$(cat "$NODE_ID_FILE")
+    else
+        # Generate from hostname + random suffix
+        SUFFIX=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n')
+        BOJ_NODE_ID="node-$(hostname -s)-${SUFFIX}"
+        if [ -w "$DATA_DIR" ]; then
+            echo "$BOJ_NODE_ID" > "$NODE_ID_FILE"
+        fi
+    fi
+    export BOJ_NODE_ID
+fi
+echo "  Node: ${BOJ_NODE_ID}"
+
+# ---------------------------------------------------------------------------
+# Federation auto-seed (background)
+# ---------------------------------------------------------------------------
+#
+# After the main process starts, wait for the REST API to be healthy,
+# then POST each seed node to /umoja/peers. Uses BOJ_SEED_NODES env
+# (comma-separated host:port) or falls back to the built-in seeds.
+
+DEFAULT_SEEDS="eu.boj.hyperpolymath.dev:9999,de.boj.hyperpolymath.dev:9999,us.boj.hyperpolymath.dev:9999,ap.boj.hyperpolymath.dev:9999"
+SEEDS="${BOJ_SEED_NODES:-$DEFAULT_SEEDS}"
+REST_PORT="${APP_PORT:-7700}"
+
+bootstrap_federation() {
+    # Wait for the REST API to become available
+    TRIES=0
+    MAX_TRIES=20
+    while [ "$TRIES" -lt "$MAX_TRIES" ]; do
+        if curl -sf "http://localhost:${REST_PORT}/health" > /dev/null 2>&1; then
+            break
+        fi
+        TRIES=$((TRIES + 1))
+        sleep 1
+    done
+
+    if [ "$TRIES" -ge "$MAX_TRIES" ]; then
+        echo "WARNING: REST API did not become healthy — skipping federation bootstrap"
+        return
+    fi
+
+    # Add each seed node as a peer
+    echo "Bootstrapping federation with seed nodes..."
+    IFS=','
+    for seed in $SEEDS; do
+        host=$(echo "$seed" | cut -d: -f1)
+        port=$(echo "$seed" | cut -d: -f2)
+        curl -sf -X POST "http://localhost:${REST_PORT}/umoja/peers" \
+            -H "Content-Type: application/json" \
+            -d "{\"host\":\"${host}\",\"port\":${port}}" > /dev/null 2>&1 \
+            && echo "  Seeded: ${host}:${port}" \
+            || echo "  Seed unreachable: ${host}:${port} (will retry via gossip)"
+    done
+    unset IFS
+    echo "Federation bootstrap complete"
+}
+
+# Run bootstrap in background so exec happens immediately
+bootstrap_federation &
+
 # ---------------------------------------------------------------------------
 # Exec into main process
 # ---------------------------------------------------------------------------
 #
 # Replace the entrypoint shell with the application process so that
 # signals are delivered directly and PID 1 is the application.
-#
-# TODO: Replace the command below with your application binary.
-# Examples:
-#   exec /app/boj-server
-#   exec /app/release/bin/boj-server start
-#   exec /app/boj-server serve --host "${APP_HOST}" --port "${APP_PORT}"
 
-exec "$@"
+exec /app/boj-server serve --host "${APP_HOST:-[::]}" --port "${REST_PORT}"