Skip to content

Instantly share code, notes, and snippets.

@kenorb
Last active September 5, 2026 16:59
Show Gist options
  • Select an option

  • Save kenorb/5d1c242ec9205d1bb7a5c8fc3f487aff to your computer and use it in GitHub Desktop.

Select an option

Save kenorb/5d1c242ec9205d1bb7a5c8fc3f487aff to your computer and use it in GitHub Desktop.
Makes `backlog browser` reachable from the Docker host
#!/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