Fix #136: default to TigerVNC to fix noVNC connect-time crash + surface silent display-stack failures#137
Open
noiwid wants to merge 2 commits into
Open
Fix #136: default to TigerVNC to fix noVNC connect-time crash + surface silent display-stack failures#137noiwid wants to merge 2 commits into
noiwid wants to merge 2 commits into
Conversation
The auth container's display stack (Xvfb + fluxbox + x11vnc + websockify) was
started with all output sent to /dev/null and no real liveness check, so any
failure was invisible: the container stayed "healthy" on uvicorn/8099 while
noVNC hung on "Connecting..." forever. Two concrete failure modes are addressed:
- Logging & liveness (standalone): each display process now logs to
/var/log/familylink/<proc>.log instead of /dev/null, and its status is
re-checked after launch with the last log lines dumped on failure, so a crash
is diagnosable from `docker logs` / the log file. The add-on entrypoint
already logs to journald; it gains the same Xvfb/fluxbox liveness checks.
- Stale X99 cleanup (both entrypoints): a non-graceful stop (e.g.
`docker restart`) leaves /tmp/.X11-unix/X99 and /tmp/.X99-lock behind, which
makes `Xvfb :99` silently refuse to bind on the next start and takes the whole
display stack down invisibly. Both are now removed before Xvfb starts.
- VNC password (both entrypoints): x11vnc's -passwd uses DES and silently keeps
only the first 8 chars, so the 10-char default ("familylink") never matched.
The password is now truncated explicitly with a warning; the server stays
localhost-only behind websockify.
This does not yet fix the primary x11vnc-crashes-on-client-connect issue
(likely a 0.9.16-vs-bookworm incompatibility) tracked separately; it makes that
crash visible instead of silent and fixes the restart-kills-VNC secondary bug.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K9tyVdR6C29z9KYADvJXYq
The auth container's noVNC hung on "Connecting..." forever because x11vnc 0.9.16 (2019) tears down its own X connection the instant a VNC client connects (confirmed via strace by @wookash) — most likely an incompatibility with the bookworm X11 libraries. Rather than chase a compatible x11vnc, the container now prefers TigerVNC's Xvnc: an X server that speaks RFB/VNC natively, so there is no separate Xvfb and no x11vnc screen-scraper — the exact component that crashed is gone. Both entrypoints (standalone run-standalone.sh and the add-on rootfs run.sh) share the same structure: - start_tigervnc(): builds a VNC-auth password file with `vncpasswd -f` (filter mode, deterministic, no interactive prompts) or falls back to -SecurityTypes None, then starts Xvnc on :99/:5900 localhost-only. - start_xvfb_x11vnc(): the legacy stack, kept as an automatic fallback so no environment loses VNC if Xvnc is missing or fails. It clears stale :99 state first (a failed Xvnc attempt can leave the socket behind). - Dispatch: auto (TigerVNC then fallback) by default; FAMILYLINK_VNC_BACKEND=tigervnc|x11vnc forces a backend. tigervnc-standalone-server is added to both Dockerfiles (x11vnc kept for the fallback). The web UI's auto-connect URL now embeds the same 8-char-truncated password the server uses, so client and server agree. Add-on config.json bumped to 1.8.0 and the Dockerfile version labels synced to match. The backend-selection control flow, password truncation, and Xvnc/x11vnc argument construction were verified with stubbed binaries; the real container still needs validation on the reporter's NAS (no local Docker here), which is why this ships as a pre-release. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01K9tyVdR6C29z9KYADvJXYq
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #136.
The auth container's noVNC hung on "Connecting…" forever, 100% of the time. @wookash did an exceptional job diagnosing it with
strace:x11vnc0.9.16 (2019) tears down its own X connection the instant a VNC client connects, and because the whole display stack was launched with output to/dev/nulland no real liveness check, the failure was completely silent — the container stayed "healthy" on uvicorn/8099 while VNC was dead.This PR ships in two layers.
1. Make silent failures visible + fix the restart bug (low-risk)
/var/log/familylink/<proc>.loginstead of/dev/null, and re-checks it after launch, dumping the last log lines on failure. The add-on entrypoint (already on journald) gains the same Xvfb/fluxbox/x11vnc checks.docker restart) left/tmp/.X11-unix/X99+/tmp/.X99-lockbehind, which madeXvfb :99silently refuse to bind next start and took the display stack down — only uvicorn came back, so the container reported healthy. Both are now removed before Xvfb/Xvnc starts. This is the secondary bug @wookash also reported.-passwduses DES and silently keeps only the first 8 chars, so the 10-char default (familylink) never matched cleanly. It's now truncated explicitly with a warning, and the web UI's auto-connect URL embeds the same 8-char value so client and server agree.2. Replace x11vnc with TigerVNC as the default backend (the real fix)
Rather than chase an x11vnc build compatible with bookworm's X libs, the container now prefers TigerVNC's
Xvnc— an X server that speaks RFB/VNC natively, so there's no separate Xvfb and no x11vnc screen-scraper. The exact component that crashed is gone.start_tigervnc()builds a VNC-auth password file withvncpasswd -f(filter mode — deterministic, no interactive prompts) or-SecurityTypes None, then startsXvncon:99/ port5900, localhost-only.start_xvfb_x11vnc()is kept as an automatic fallback, so no environment loses VNC ifXvncis missing or fails.auto(TigerVNC → fallback) by default;FAMILYLINK_VNC_BACKEND=tigervnc|x11vncforces a backend.tigervnc-standalone-serveradded to both Dockerfiles (x11vnc kept for the fallback). Add-onconfig.json→1.8.0, Dockerfile version labels synced.Testing status⚠️
There is no Docker in my dev environment, so I could not build/run the container end-to-end. What I did verify:
bash -non both entrypoints, plus a stubbed-binary smoke test of the full control flow (backend selection, password truncation to 8,vncpasswd -fpath,Xvnc/x11vncargument construction, and the fallback path) — all branches produce well-formed commands.Xvncflags (-localhost,-rfbport,-SecurityTypes None|VncAuth,-rfbauth,-desktop,-geometry,-depth) confirmed against the TigerVNC man pages.The connect-time crash itself only reproduces on the reporter's real environment (NAS, x86_64 Debian), which is why this is proposed for a pre-release so @wookash can validate on the machine where the bug actually occurs before it goes to
latest.🤖 Generated with Claude Code