From 1ff1a181543626eab8d3890457eb5ff175c1aa3e Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Fri, 28 Aug 2026 02:11:11 -0700 Subject: [PATCH] docs(headless-server): fix package list, extraction perms, and ldd command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three fixes to the headless Linux server guide, each of which stops a first-time setup from working. The prerequisite list installed only CLI tools and Xvfb, none of the shared libraries Electron links against. On a minimal server or container image `orca serve` then fails before Electron starts. Adds the library set, plus the unsuffixed package names for releases that predate the 64-bit time_t transition. The guide tells you to run --appimage-extract and, separately, to run the service as a dedicated non-root user with the install directory root-owned. Those two halves combine badly: extraction leaves squashfs-root as drwx------, so the service user cannot traverse it, and chmod 755 /opt/orca does not reach inside. Adds the missing chmod to both places. The troubleshooting step said to run `ldd squashfs-root/orca`. The Electron binary is orca-ide, and ldd on a path that does not exist prints nothing and exits cleanly — a clean-looking result in exactly the situation where you are hunting a missing library. --- docs/reference/headless-linux-server.md | 49 +++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md index af47e452a82..ab03b246660 100644 --- a/docs/reference/headless-linux-server.md +++ b/docs/reference/headless-linux-server.md @@ -17,13 +17,37 @@ differ on other Debian-derived releases. ## Ubuntu and Debian prerequisites -Install the AppImage runtime dependency and Xvfb: +Install the CLI tools, Xvfb, and the shared libraries Electron links against. +A minimal server or container image ships none of the Electron libraries, and +`orca serve` then fails before Electron starts: ```bash sudo apt-get update -sudo apt-get install -y curl file jq xvfb zlib1g-dev +sudo apt-get install -y \ + curl file jq xvfb zlib1g-dev ca-certificates git \ + libgtk-3-0t64 libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64 libgbm1 libasound2t64 \ + libxtst6 libcups2t64 libdrm2 libxkbcommon0 libpango-1.0-0 libcairo2 libatspi2.0-0t64 \ + libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libxrender1 libx11-xcb1 \ + libxcb-dri3-0 libxss1 ``` +That command is for Ubuntu 24.04 and newer and Debian 13 and newer. Those +releases carried out the 64-bit `time_t` transition, which renamed six of the +packages with a `t64` suffix. On Ubuntu 20.04, Ubuntu 22.04, and Debian 12, +substitute the unsuffixed names: + +- `libgtk-3-0t64` becomes `libgtk-3-0` +- `libatk1.0-0t64` becomes `libatk1.0-0` +- `libatk-bridge2.0-0t64` becomes `libatk-bridge2.0-0` +- `libasound2t64` becomes `libasound2` +- `libcups2t64` becomes `libcups2` +- `libatspi2.0-0t64` becomes `libatspi2.0-0` + +The other names are identical on every supported release. The two sets are not +interchangeable: `apt-get install` fails outright on a name the release does not +carry, and on Ubuntu 24.04 `libasound2` survives only as a virtual package for an +unrelated library, so it installs without giving Electron what it needs. + On Ubuntu 22.04, install `libfuse2` to execute the AppImage through FUSE. On Ubuntu 24.04 and Debian, the equivalent package may be `libfuse2t64`. FUSE is optional: without it, use the AppImage's supported extraction path: @@ -31,9 +55,15 @@ optional: without it, use the AppImage's supported extraction path: ```bash cd /opt/orca ./orca-linux.AppImage --appimage-extract +sudo chmod -R a+rX /opt/orca/squashfs-root /opt/orca/squashfs-root/AppRun serve --port 6768 ``` +The `chmod` is required whenever the extraction runs as a different user than +the server: `--appimage-extract` creates `squashfs-root` as `drwx------` owned by +the extracting user, so anyone else — including a dedicated service user — cannot +even traverse it, and the run fails before Electron starts. + Docker commonly has no FUSE device. Use `--appimage-extract` once or `--appimage-extract-and-run`; neither requires a privileged container. The extract-and-run wrapper can print extracted paths before Orca starts, so @@ -144,8 +174,15 @@ AppImage, but must not be able to replace it or the rollback artifacts. sudo useradd --system --create-home --shell /usr/sbin/nologin orca sudo chown root:root /opt/orca /opt/orca/orca-linux.AppImage sudo chmod 755 /opt/orca /opt/orca/orca-linux.AppImage +# Only if you ran --appimage-extract: extraction leaves squashfs-root root-only. +sudo chmod -R a+rX /opt/orca/squashfs-root ``` +The last line matters because the two halves of this guide combine badly without +it. `--appimage-extract` writes `squashfs-root` as `drwx------ root root`, so the +`orca` service user cannot read or traverse the extracted tree and the unit fails +at startup. `chmod 755 /opt/orca` alone does not reach into it. + For most hosts, one `orca serve` service is enough because Orca starts Xvfb on display `:99` when no display exists: @@ -834,7 +871,8 @@ refuse to run there and print the command to run on the machine you want. - GPU or DRI warnings on a VPS: keep `LIBGL_ALWAYS_SOFTWARE=1` in the service environment. - Chromium sandbox errors: confirm the service is running as the non-root - `orca` user and that `/opt/orca` is readable by that user. + `orca` user and that `/opt/orca` is readable by that user, including + `/opt/orca/squashfs-root` if you extracted the AppImage. - Clients cannot connect: make sure `--pairing-address` is an address reachable from the client, and make sure firewalls allow the selected `--port`. - Journal shows `Another Orca instance is already running for this userData @@ -857,4 +895,7 @@ profile` and the unit exits `3`: another process already owns the profile, so `sudo systemctl reset-failed orca-serve.service` first. - Diagnosing other missing libraries: extract the AppImage without launching it with `./orca-linux.AppImage --appimage-extract`, then run - `ldd squashfs-root/orca` to list any shared libraries the host is missing. + `ldd squashfs-root/orca-ide` to list any shared libraries the host is missing. + The Electron binary is `orca-ide`, not `orca`; `ldd` on a path that does not + exist prints nothing and exits cleanly, which reads as a clean result in + exactly the situation where you are hunting a missing library.