Skip to content

INSTALL-linux.md

Latest commit

 

History

History
306 lines (208 loc) · 7.17 KB

INSTALL-linux.md

File metadata and controls

306 lines (208 loc) · 7.17 KB
Raw

Installing LemonTop on Linux

Step-by-step install for the machine running Lemonade Server.

LemonTop reads local CPU/RAM/GPU counters and the local systemd journal, so for a coherent picture install it on the Lemonade host itself and connect over SSH. Pointing it at a remote server works, but the system panel will describe whatever machine LemonTop is running on, not the server.

Quick install

One command. Installs prerequisites, clones to ~/LemonTop, builds a venv, and puts lemontop on your PATH:

curl -fsSL https://raw.githubusercontent.com/cbigeagle/LemonTop/main/install.sh | bash

Then:

source ~/.bashrc && lemontop --demo

If you'd rather read a script before piping it to a shell — a good habit — download it first:

curl -fsSL -o install.sh https://raw.githubusercontent.com/cbigeagle/LemonTop/main/install.sh && less install.sh && bash install.sh

Re-running install.sh updates an existing install in place. It asks for sudo only if git or python3-venv are missing, and installs nothing else system-wide.

To install somewhere other than ~/LemonTop:

LEMONTOP_DIR=/opt/lemontop curl -fsSL https://raw.githubusercontent.com/cbigeagle/LemonTop/main/install.sh | bash

The rest of this document covers the same steps manually, plus permissions and troubleshooting.

1. Prerequisites

  • Python 3.10 or newer (python3 --version)
  • git
  • The venv module (packaged separately on Debian/Ubuntu)

Optional, both degrade gracefully if missing:

  • journalctl — for the events panel
  • An AMD GPU exposing /sys/class/drm/card*/device — for the GPU/APU panel

Debian / Ubuntu

sudo apt update && sudo apt install -y python3 python3-venv python3-pip git

Fedora / RHEL

sudo dnf install -y python3 python3-pip git

Arch

sudo pacman -S --needed python python-pip git

Confirm the version is 3.10+:

python3 --version

If your distro ships something older, install a newer Python (pyenv, or deadsnakes on Ubuntu) and substitute it for python3 below.

2. Clone

git clone https://github.com/cbigeagle/LemonTop.git ~/LemonTop
cd ~/LemonTop

3. Install into a virtualenv

Keeping it in a venv avoids fighting your distro's package manager over psutil and textual.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip && python -m pip install -e .

-e installs in editable mode, so git pull updates the installed command with no reinstall step.

Alternative: pipx

If you'd rather have lemontop on your PATH without activating anything:

pipx install --editable ~/LemonTop

4. Verify

With the venv active:

python tests/test_smoke.py

Expected output: LemonTop demo smoke test passed

Then look at the full interface with synthetic data — no Lemonade server needed:

lemontop --demo

Press q to quit. If the panels render with borders and the numbers move, the install is good.

5. Run it against Lemonade

lemontop

The default endpoint is http://localhost:13305. To point somewhere else:

lemontop --server http://192.168.1.50:13305

Options

Flag Default Purpose
--server URL http://localhost:13305 Lemonade root URL
--refresh SECONDS 1.0 Poll interval, minimum 0.25
--timeout SECONDS 0.8 Per-request HTTP timeout
--service NAME lemond.service systemd unit to read logs from
--demo off Synthetic metrics, no server contact
--no-logs off Skip journalctl entirely

Each has an environment variable equivalent — LEMONTOP_SERVER, LEMONTOP_REFRESH, LEMONTOP_TIMEOUT, LEMONTOP_SERVICE — which is the easier way to set a permanent default:

echo 'export LEMONTOP_SERVER=http://localhost:13305' >> ~/.bashrc

Keys

Key Action
q Quit
p Pause / resume updates
r Refresh now
l Focus the event log (then arrows / PgUp to scroll)
t Focus the request table
? Key help

The focused panel is outlined in green.

6. Permissions

LemonTop makes no configuration changes and needs no elevated privileges. Two optional data sources have their own access rules.

Journal events

Reading another unit's journal usually requires group membership:

sudo usermod -aG systemd-journal "$USER"

Log out and back in for it to take effect. Without this the events panel simply stays empty — nothing else is affected. If your unit has a different name:

lemontop --service my-lemonade-unit

AMD GPU counters

Read from:

/sys/class/drm/card*/device/

These are world-readable on most distributions. amd-smi is not required. If the GPU panel shows — across the board, check that the amdgpu driver is loaded:

ls /sys/class/drm/card0/device/gpu_busy_percent

Only the first AMD card is read. On a system with an APU plus a discrete GPU, the second device is not shown.

7. Running over SSH

LemonTop is a full-screen terminal app, so it needs a TTY:

ssh -t user@lemonade-host '~/LemonTop/.venv/bin/lemontop'

For a session that survives a dropped connection:

ssh user@lemonade-host -t 'tmux new -A -s lemontop ~/LemonTop/.venv/bin/lemontop'

Use a terminal with a font that carries block-drawing glyphs (▁▂▃█░) — most Nerd Fonts, DejaVu Sans Mono, and JetBrains Mono do. Missing glyphs make the sparklines look broken when the data is fine.

8. Updating

cd ~/LemonTop && git pull

Because the install is editable, that's the whole update. Only re-run pip install -e . if the dependencies in pyproject.toml changed.

Troubleshooting

lemontop: command not found The venv isn't active. Run source ~/LemonTop/.venv/bin/activate, or call the binary directly at ~/LemonTop/.venv/bin/lemontop.

● OFFLINE in the top right LemonTop can't reach the server. Confirm it's up and the port is right:

curl -s http://localhost:13305/api/v1/health

If that 404s, try /v1/health — LemonTop probes both automatically and caches whichever answers.

Most inference fields show — Expected on some Lemonade versions and backends. Context size, KV-cache size, prompt throughput, and queue depth are only displayed when the server reports them. — means "not reported", never "zero".

The events panel is empty Either you're missing systemd-journal group membership (see §6), the unit name doesn't match --service, or journalctl isn't on PATH. On non-systemd distributions the panel stays empty by design.

The request table only ever shows one row Lemonade's stats endpoint reports the last request without a request id, so two identical back-to-back requests can't be told apart and collapse into one row. This is a server API limit, not a display bug.

ModuleNotFoundError: No module named 'textual' pip install -e . didn't complete, or you're running a different Python than the venv's. Check with which python.

Garbled bars or boxes A font problem, not a data problem. See §7.