Document headless Linux server setup (#6802)
* docs: add headless Linux server guide * docs: add ldd/appimage-extract tip for diagnosing missing libraries Salvaged from #6817 before closing it as a duplicate. Co-authored-by: Orca <help@stably.ai> --------- Co-authored-by: Jinwoo-H <jinwoo@stably.ai> Co-authored-by: Orca <help@stably.ai>
This commit is contained in:
Dhilip Subramanian
GitHub
parent
b44606f023
commit
9694830764
|
|
@ -213,6 +213,7 @@ Works with **any CLI agent** — if it runs in a terminal, it runs in Orca.
|
|||
|
||||
- **[Download from onOrca.dev](https://onorca.dev/download)**
|
||||
- Or grab a build directly: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [All builds](https://github.com/stablyai/orca/releases/latest)
|
||||
- Running `orca serve` on a headless Linux server? See the [headless Linux server guide](docs/reference/headless-linux-server.md).
|
||||
|
||||
_Or via a package manager:_
|
||||
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ Keep this folder for versioned reference docs that are meant to survive past a s
|
|||
- Public-facing docs that are not part of the root README.
|
||||
- Docs that other checked-in files link to.
|
||||
- Telemetry availability notes that dashboard authors need after the original design or implementation branch is gone. See [Telemetry Availability](./telemetry-availability.md).
|
||||
- Headless Linux server setup for remote `orca serve` hosts. See [Headless Linux Server](./headless-linux-server.md).
|
||||
- Feature education state, interaction tracking, and retention analytics notes that define how contextual tours are persisted and measured. See [Feature Education State](./feature-education-state.md), [Feature Discovery Interaction Tracking](./feature-discovery-interaction-tracking.md), and [Feature Education Retention Analytics](./feature-education-retention-analytics.md).
|
||||
- New-user parallel work telemetry notes that define how the parallel-work tour and setup guide should be measured against retention. See [New User Parallel Work Telemetry](./new-user-parallel-work-telemetry.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,183 @@
|
|||
# Headless Linux Server
|
||||
|
||||
Use this guide when you want to run `orca serve` on a Linux machine without a
|
||||
desktop session, such as an Ubuntu VPS or a remote build box.
|
||||
|
||||
`orca serve` starts the Orca runtime without opening the desktop window. On
|
||||
Linux, the packaged AppImage still needs the libraries that Electron expects at
|
||||
startup. Current Orca builds can start Xvfb automatically for `orca serve` when
|
||||
no `DISPLAY` is set, but Xvfb must be installed first. When `DISPLAY` is set,
|
||||
Orca uses that display instead of starting a competing Xvfb process.
|
||||
|
||||
## Ubuntu 22.04 Prerequisites
|
||||
|
||||
Install the AppImage runtime dependency and Xvfb:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y curl libfuse2 xvfb
|
||||
```
|
||||
|
||||
Download and make the AppImage executable:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/orca
|
||||
sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \
|
||||
-o /opt/orca/orca-linux.AppImage
|
||||
sudo chmod +x /opt/orca/orca-linux.AppImage
|
||||
```
|
||||
|
||||
If `Xvfb` was installed somewhere other than `/usr/bin`, confirm systemd can
|
||||
find it later:
|
||||
|
||||
```bash
|
||||
command -v Xvfb
|
||||
```
|
||||
|
||||
## Run In The Foreground
|
||||
|
||||
Start with a foreground run before creating a service:
|
||||
|
||||
```bash
|
||||
LIBGL_ALWAYS_SOFTWARE=1 /opt/orca/orca-linux.AppImage serve --port 6768
|
||||
```
|
||||
|
||||
For remote clients, pass the address they should use to reach this server. A
|
||||
Tailscale address is usually the safest option for private servers:
|
||||
|
||||
```bash
|
||||
LIBGL_ALWAYS_SOFTWARE=1 /opt/orca/orca-linux.AppImage serve \
|
||||
--port 6768 \
|
||||
--pairing-address 100.64.1.20
|
||||
```
|
||||
|
||||
The command prints the runtime endpoint and pairing URL. Stop it with `Ctrl+C`.
|
||||
|
||||
## Systemd Service
|
||||
|
||||
Create a dedicated service user and install directory. Run the service as this
|
||||
user instead of root so the AppImage can keep Chromium's sandbox enabled.
|
||||
|
||||
```bash
|
||||
sudo useradd --system --create-home --shell /usr/sbin/nologin orca
|
||||
sudo chown -R orca:orca /opt/orca
|
||||
```
|
||||
|
||||
For most hosts, one `orca serve` service is enough because Orca starts Xvfb on
|
||||
display `:99` when no display exists:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/orca-serve.service
|
||||
[Unit]
|
||||
Description=Orca runtime server
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=orca
|
||||
WorkingDirectory=/home/orca
|
||||
Environment=LIBGL_ALWAYS_SOFTWARE=1
|
||||
ExecStart=/opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Replace `100.64.1.20` with the LAN, Tailscale, tunnel, or public hostname that
|
||||
clients should use.
|
||||
|
||||
Enable the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now orca-serve.service
|
||||
sudo journalctl -u orca-serve.service -f
|
||||
```
|
||||
|
||||
## Managed Xvfb Service
|
||||
|
||||
If you prefer to own the virtual display lifecycle in systemd, run Xvfb as a
|
||||
separate service and set `DISPLAY=:99` for Orca.
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/orca-xvfb.service
|
||||
[Unit]
|
||||
Description=Virtual X display for Orca
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x1024x24 -nolisten tcp
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
If `command -v Xvfb` returned a different path, update `ExecStart` to that
|
||||
absolute path.
|
||||
|
||||
Then add the display dependency to the Orca service:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/orca-serve.service
|
||||
[Unit]
|
||||
Description=Orca runtime server
|
||||
After=network-online.target orca-xvfb.service
|
||||
Wants=network-online.target orca-xvfb.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=orca
|
||||
WorkingDirectory=/home/orca
|
||||
Environment=DISPLAY=:99
|
||||
Environment=LIBGL_ALWAYS_SOFTWARE=1
|
||||
ExecStart=/opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Enable both units:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now orca-xvfb.service orca-serve.service
|
||||
```
|
||||
|
||||
## CLI Install Note
|
||||
|
||||
On a headless host, you do not need to open the desktop UI just to run the
|
||||
server. Invoke the AppImage directly:
|
||||
|
||||
```bash
|
||||
/opt/orca/orca-linux.AppImage serve --help
|
||||
```
|
||||
|
||||
If you later install the desktop CLI from Orca settings, use that CLI for normal
|
||||
shell workflows. Keep the AppImage path in systemd so service restarts do not
|
||||
depend on an interactive shell profile.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- `dlopen(): error loading libfuse.so.2`: install `libfuse2`.
|
||||
- `Missing X server or $DISPLAY`: install `xvfb`, or start the managed Xvfb
|
||||
service and set `DISPLAY=:99`.
|
||||
- `Xvfb not found`: confirm `command -v Xvfb` and use that absolute path in the
|
||||
systemd unit.
|
||||
- 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.
|
||||
- Clients cannot connect: make sure `--pairing-address` is an address reachable
|
||||
from the client, and make sure firewalls allow the selected `--port`.
|
||||
- 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.
|
||||
Loading…
Reference in New Issue