Last active
September 5, 2026 16:59
-
-
Save kenorb/5d1c242ec9205d1bb7a5c8fc3f487aff to your computer and use it in GitHub Desktop.
Makes `backlog browser` reachable from the Docker host
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/usr/bin/env bash | |
| # | |
| # backlog-browser-host.sh — makes `backlog browser` reachable from the host | |
| # | |
| # Purpose | |
| # The upstream `backlog browser` (post PR #826 / BACK-560) binds **only** | |
| # to 127.0.0.1 with no `--host` flag. This wrapper runs it on an internal | |
| # port and places a socat relay on 0.0.0.0 so the host can reach it via the | |
| # container's bridge IP (172.17.0.2:6420 by default). | |
| # | |
| # Upstream context (see full details in scripts/AGENTS.md): | |
| # - #810: reported 0.0.0.0 binding with no auth | |
| # - #701: proposed --host + auth (closed unmerged) | |
| # - #826 (merged): enforced loopback-only, no LAN mode | |
| # Maintainer stance: GUI-only tool; use ssh -L tunnel or tailscale for remote. | |
| # This relay follows the exact recommended pattern. | |
| # | |
| # Usage | |
| # scripts/backlog-browser-host.sh start [PORT] # default 6420 | |
| # scripts/backlog-browser-host.sh status [PORT] | |
| # scripts/backlog-browser-host.sh restart [PORT] | |
| # scripts/backlog-browser-host.sh stop [PORT] | |
| # | |
| # State (per PORT): | |
| # /tmp/backlog-browser/PORT.backlog.pid | |
| # /tmp/backlog-browser/PORT.socat.pid | |
| # /tmp/backlog-browser/PORT.log (combined output) | |
| # | |
| # Note: /tmp is wiped on host reboot (see devcontainer/AGENTS.md). Pidfiles | |
| # do not survive reboots; use `scan-jobs.sh status` to discover live jobs. | |
| # | |
| # Integration | |
| # This is a long-running service. Use `scripts/scan-jobs.sh status` to see it | |
| # alongside other background jobs (it is detected via the command line — | |
| # the `backlog browser` binary appears in ps). `stop` here (or via | |
| # scan-jobs.sh) is the canonical way to shut it down cleanly. | |
| # | |
| # State now lives in /tmp/backlog-browser/ (wiped on reboot; matches | |
| # devcontainer behavior for background jobs). | |
| set -euo pipefail | |
| cd "$(dirname "$0")/.." | |
| CMD="${1:-start}" | |
| HOST_PORT="${2:-6420}" | |
| BACKLOG_PORT=$((HOST_PORT + 1)) | |
| STATE_DIR="/tmp/backlog-browser" | |
| LOG="$STATE_DIR/$HOST_PORT.log" | |
| BACKLOG_PIDF="$STATE_DIR/$HOST_PORT.backlog.pid" | |
| SOCAT_PIDF="$STATE_DIR/$HOST_PORT.socat.pid" | |
| container_ip() { | |
| # Prefer the bridge IP shown in the user's ifconfig (172.17.0.2) | |
| hostname -I 2>/dev/null | awk '{print $1}' | |
| } | |
| port_open() { | |
| # Test whether something is listening on 127.0.0.1:port | |
| (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null && return 0 | |
| return 1 | |
| } | |
| alive() { | |
| [[ -f "$1" ]] && kill -0 "$(cat "$1")" 2>/dev/null | |
| } | |
| kill_pidfile() { | |
| local name="$1" pidf="$2" | |
| [[ -f "$pidf" ]] || return 0 | |
| local pid; pid="$(cat "$pidf")" | |
| if kill -0 "$pid" 2>/dev/null; then | |
| echo "Stopping $name (pid $pid)..." | |
| kill "$pid" 2>/dev/null || true | |
| for _ in $(seq 1 20); do | |
| kill -0 "$pid" 2>/dev/null || break | |
| sleep 0.5 | |
| done | |
| if kill -0 "$pid" 2>/dev/null; then | |
| echo "Force-killing $name (pid $pid)" | |
| kill -9 "$pid" 2>/dev/null || true | |
| fi | |
| fi | |
| rm -f "$pidf" | |
| } | |
| check_health() { | |
| local port=$1 | |
| curl -fsS --max-time 3 "http://127.0.0.1:$port/" 2>/dev/null | grep -q 'Backlog.md' || return 1 | |
| return 0 | |
| } | |
| case "$CMD" in | |
| start|restart) | |
| if [[ "$CMD" = "restart" ]] || alive "$BACKLOG_PIDF" || alive "$SOCAT_PIDF"; then | |
| echo "Stopping existing instance first..." | |
| "$0" stop "$HOST_PORT" | |
| echo "Waiting for clean shutdown..." | |
| sleep 2 | |
| fi | |
| command -v socat >/dev/null || { | |
| echo "Error: socat not found. Run: apt install socat" >&2 | |
| exit 1 | |
| } | |
| mkdir -p "$STATE_DIR" | |
| if port_open "$HOST_PORT" || port_open "$BACKLOG_PORT"; then | |
| echo "Error: port $HOST_PORT (relay) or $BACKLOG_PORT (backlog) already in use." >&2 | |
| echo " Run: scripts/backlog-browser-host.sh stop $HOST_PORT" >&2 | |
| echo " (A manually started 'backlog browser' on 127.0.0.1:$HOST_PORT also conflicts.)" >&2 | |
| ss -ltn 2>/dev/null | grep -E "[:.]($HOST_PORT|$BACKLOG_PORT)\s" >&2 || true | |
| exit 1 | |
| fi | |
| : > "$LOG" | |
| echo "# Starting backlog browser on 127.0.0.1:$BACKLOG_PORT at $(date -u)" >> "$LOG" | |
| setsid backlog browser -p "$BACKLOG_PORT" --no-open --non-interactive \ | |
| >>"$LOG" 2>&1 </dev/null & | |
| echo $! > "$BACKLOG_PIDF" | |
| echo "Waiting for backlog browser to start..." | |
| for i in $(seq 1 30); do | |
| if port_open "$BACKLOG_PORT" && check_health "$BACKLOG_PORT"; then | |
| echo "Backlog browser ready on 127.0.0.1:$BACKLOG_PORT" | |
| break | |
| fi | |
| sleep 1 | |
| if ! alive "$BACKLOG_PIDF"; then | |
| echo "ERROR: backlog browser exited early. Last lines of log:" >&2 | |
| tail -n 15 "$LOG" >&2 | |
| exit 1 | |
| fi | |
| done | |
| if ! check_health "$BACKLOG_PORT"; then | |
| echo "ERROR: backlog browser not responding on $BACKLOG_PORT" >&2 | |
| tail -n 10 "$LOG" >&2 | |
| exit 1 | |
| fi | |
| echo "# Starting socat relay 0.0.0.0:$HOST_PORT -> 127.0.0.1:$BACKLOG_PORT at $(date -u)" >> "$LOG" | |
| setsid socat "TCP-LISTEN:$HOST_PORT,bind=0.0.0.0,reuseaddr,fork" \ | |
| "TCP:127.0.0.1:$BACKLOG_PORT" >>"$LOG" 2>&1 </dev/null & | |
| echo $! > "$SOCAT_PIDF" | |
| sleep 0.5 | |
| IP="$(container_ip)" | |
| echo "backlog browser (host-facing) is running" | |
| echo " Host URL : http://$IP:$HOST_PORT/ <- open this from the host" | |
| echo " Local URL: http://127.0.0.1:$HOST_PORT/ (inside container)" | |
| echo " PIDs : backlog $(cat "$BACKLOG_PIDF" 2>/dev/null || echo '?') (127.0.0.1:$BACKLOG_PORT)" | |
| echo " : socat $(cat "$SOCAT_PIDF" 2>/dev/null || echo '?') (0.0.0.0:$HOST_PORT)" | |
| echo " Log : $LOG" | |
| echo " Stop : scripts/backlog-browser-host.sh stop $HOST_PORT" | |
| echo " Status : scripts/backlog-browser-host.sh status $HOST_PORT" | |
| ;; | |
| status) | |
| IP="$(container_ip)" | |
| echo "Host URL: http://$IP:$HOST_PORT/" | |
| if alive "$BACKLOG_PIDF"; then | |
| echo "backlog browser: RUNNING (pid $(cat "$BACKLOG_PIDF"), 127.0.0.1:$BACKLOG_PORT)" | |
| else | |
| echo "backlog browser: not running (managed)" | |
| fi | |
| if alive "$SOCAT_PIDF"; then | |
| echo "socat relay: RUNNING (pid $(cat "$SOCAT_PIDF"), 0.0.0.0:$HOST_PORT)" | |
| else | |
| echo "socat relay: not running (managed)" | |
| fi | |
| echo "Listening sockets:" | |
| ss -ltn 2>/dev/null | grep -E "[:.]($HOST_PORT|$BACKLOG_PORT)\s" || true | |
| ;; | |
| stop) | |
| stopped=0 | |
| if alive "$SOCAT_PIDF"; then | |
| kill_pidfile "socat relay" "$SOCAT_PIDF" | |
| stopped=1 | |
| fi | |
| if alive "$BACKLOG_PIDF"; then | |
| kill_pidfile "backlog browser" "$BACKLOG_PIDF" | |
| stopped=1 | |
| fi | |
| if [[ $stopped -eq 0 ]]; then | |
| echo "Nothing managed for port $HOST_PORT." | |
| echo "Check for stray manual instance:" | |
| ss -ltnp 2>/dev/null | grep -E "[:.]($HOST_PORT|$BACKLOG_PORT)\s" || true | |
| pgrep -af "backlog browser" || true | |
| fi | |
| ;; | |
| *) | |
| echo "Usage: scripts/backlog-browser-host.sh {start|status|restart|stop} [HOST_PORT]" >&2 | |
| echo " (default HOST_PORT = 6420)" >&2 | |
| exit 2 | |
| ;; | |
| esac |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment