{"id":29693824,"url":"https://github.com/komed3/serverdesk","last_synced_at":"2026-05-18T15:34:53.330Z","repository":{"id":303946102,"uuid":"1015983430","full_name":"komed3/serverdesk","owner":"komed3","description":"Minimal touchscreen control interface for Linux servers using the framebuffer console","archived":false,"fork":false,"pushed_at":"2026-04-27T13:51:11.000Z","size":1208,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-27T15:31:31.699Z","etag":null,"topics":["framebuffer","linux","monitoring","server","systemd-service","touchscreen"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/komed3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-08T10:11:57.000Z","updated_at":"2026-04-27T13:51:09.000Z","dependencies_parsed_at":"2025-07-10T17:07:37.353Z","dependency_job_id":"81216cd3-465b-4530-b15d-df83e520948f","html_url":"https://github.com/komed3/serverdesk","commit_stats":null,"previous_names":["komed3/serverdesk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/komed3/serverdesk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komed3%2Fserverdesk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komed3%2Fserverdesk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komed3%2Fserverdesk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komed3%2Fserverdesk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/komed3","download_url":"https://codeload.github.com/komed3/serverdesk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komed3%2Fserverdesk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33182990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framebuffer","linux","monitoring","server","systemd-service","touchscreen"],"created_at":"2025-07-23T08:09:27.502Z","updated_at":"2026-05-18T15:34:53.290Z","avatar_url":"https://github.com/komed3.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ServerDesk\n\n**ServerDesk** is a lightweight, framebuffer-based touchscreen menu for Linux servers – purpose-built for direct control and monitoring without the need for a graphical desktop environment.\n\nDesigned for environments with direct physical access, **ServerDesk** provides quick access to essential system commands such as process monitoring, log inspection, shutdown/reboot actions, and more – all through a clean, responsive overlay interface operated via touch input.\n\n![Overlay](./assets/menu.png)\n\n## Key Features\n\n- **Framebuffer rendering** – no X11, Wayland or window manager required\n- **Touchscreen-friendly UI** – designed for small screens (e.g., 1024×600)\n- **Command-driven logic** – easily extensible via a simple JSON configuration\n- **Secure and local** – no remote access, no internet exposure\n- **Failsafe execution** – subprocesses run in isolated sessions, auto-recovery supported\n- **Modular structure** – clean separation of scripts, assets and logic\n\n**ServerDesk** is ideal for embedded or dedicated maintenance terminals, homelab servers, or rack-mounted systems with integrated display hardware.\n\n## Requirements\n\n### Hardware\n\n- Linux-capable device with framebuffer support (e.g. `/dev/fb0`)\n- Touchscreen input device (e.g. `/dev/input/eventX`)\n\n### Software\n\n- Any Linux distribution with:\n  - Python 3.10+\n  - Systemd\n  - Framebuffer device enabled (no X11 or Wayland needed)\n  - Write access to `/dev/fb0` and `/dev/input/eventX`\n- Some packages to run **ServerDesk** commands:\n  - `htop`, `iftop` and `iotop`: monitoring tools\n  - `lm-sensors`: hardware monitoring\n- Python packages: `evdev` and `Pillow`\n\nYou can install them via:\n\n```bash\nsudo apt install \\\n  htop iftop iotop lm-sensors \\\n  python3 python3-evdev python3-pillow\n```\n\n----\n\n## Installation\n\n### Step 1 — Create User\n\nIt is recommended to run **ServerDesk** under a dedicated system user. This enhances separation and allows fine-tuned sudo permissions. Name this user whatever you want, but bear in mind to change all the commands listed below to match your choice.\n\nHere, the username `watchdog` will be used:\n\n```bash\n# Create the user account\nsudo useradd -r -m -d /home/watchdog -s /usr/sbin/nologin watchdog\n\n# Grant the user necessary rights (framebuffer and tty)\nsudo usermod -aG video,tty watchdog\n\n# You may check those with\ngroups watchdog\n```\n\nTo allow **ServerDesk** to run commands without password prompts, edit the sudoers file:\n\n```bash\nsudo nano /etc/sudoers.d/serverdesk\n```\n\nAnd add the list of commands needed to run **ServerDesk**:\n\n```bash\nwatchdog ALL=(ALL) NOPASSWD: \\\n  /usr/bin/apt, \\\n  /usr/bin/apt-get, \\\n  /usr/bin/chvt, \\\n  /usr/bin/df, \\\n  /usr/bin/dmesg, \\\n  /usr/bin/dpkg, \\\n  /usr/bin/htop, \\\n  /usr/bin/journalctl, \\\n  /usr/bin/systemctl, \\\n  /usr/bin/w, \\\n  /usr/sbin/iftop, \\\n  /usr/sbin/iotop, \\\n  /usr/sbin/mdadm\n```\n\n### Step 2 — Cloning Repository\n\nClone the **ServerDesk** repository to the appropriate location:\n\n```bash\ngit clone https://github.com/komed3/serverdesk /home/watchdog/serverdesk\n```\n\nYou can clone this repository with any user, but ownership must be transferred to your designated service user afterward, so the service can run the program without disruptions.\n\n```bash\nsudo chown -R watchdog:watchdog /home/watchdog/serverdesk\n```\n\nIf the program, parts of it or individual commands cannot be executed, the following may help:\n\n```bash\n# Convert shell scripts to Unix format\nsudo apt install dos2unix\nfind /home/watchdog/serverdesk/bin -type f -name \"*.sh\" -exec dos2unix {} +\n\n# Ensure that all shell scripts are executable\nsudo chmod +x /home/watchdog/serverdesk/bin/*.sh\nsudo chmod +x /home/watchdog/serverdesk/menu.py\n```\n\n**ServerDesk** will automatically update itself via the service. If you do not want this behavior, add an exception for the directory so that any other user can upgrade it via `git pull`.\n\n```bash\ngit config --global --add safe.directory /home/watchdog/serverdesk\n```\n\nOnce the repository has been cloned and all its dependencies installed, the program can be tested locally:\n\n```bash\nsudo -u watchdog /home/watchdog/serverdesk/menu.py\n```\n\n### Step 3 — Set Up systemd Service\n\nTo ensure **ServerDesk** starts automatically on boot and controls the primary console (`tty1`), create a custom systemd service file:\n\n```bash\nsudo nano /etc/systemd/system/serverdesk.service\n```\n\nAnd put those lines there:\n\n```bash\n[Unit]\nDescription=ServerDesk\nAfter=multi-user.target\nWants=graphical.target\nConditionPathExists=/home/watchdog/serverdesk/menu.py\nConflicts=getty@tty1.service\n\n[Service]\nType=simple\nUser=watchdog\nGroup=tty\nWorkingDirectory=/home/watchdog/serverdesk\nExecStartPre=/usr/bin/git -C /home/watchdog/serverdesk pull --quiet\nExecStart=/usr/bin/python3 /home/watchdog/serverdesk/menu.py\nStandardInput=tty\nStandardOutput=tty\nStandardError=journal\nRestart=always\nRestartSec=2\nTTYPath=/dev/tty1\nTTYReset=yes\nTTYVHangup=yes\nRemainAfterExit=no\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThe `serverdesk.service` is tailored to run **ServerDesk** directly on virtual terminal `tty1`, ensuring smooth startup and reliable behavior:\n\n- `User=watchdog` runs the process under a restricted service user without login privileges, improving security and preventing unintended interactions.\n- `Group=tty` ensures access to `/dev/tty1`, which is required to read and write to the console framebuffer and control terminal sessions.\n- `WorkingDirectory=/home/watchdog/serverdesk` sets the base path for relative commands and asset resolution.\n- `ExecStartPre=...git pull` optionally updates the local repository before launch, allowing for unattended upgrades if no modifications are made.\n- `ExecStart=...menu.py` is the main Python script that launches the **ServerDesk** menu overlay.\n- `StandardInput/Output=tty` binds the service explicitly to the virtual console, enabling full interaction via touch and system commands.\n- `TTYPath=/dev/tty1` defines the target terminal device for this service; this line ensures all in- and output is tied to the correct display.\n- `Restart=always` and `RestartSec=2` provide resilience: if **ServerDesk** crashes or exits unexpectedly, it will be restarted automatically after a short delay.\n- `Conflicts=getty@tty1.service` disables the standard login prompt on `tty1`, avoiding interference with **ServerDesk**’s console usage.\n- `ConditionPathExists=...menu.py` ensures the service won’t start unless the main script is present — useful as a safety check during setup or updates.\n\nYou may need to adjust some of them, especially if a different user name has been chosen or the files are located in a separate directory.\n\n----\n\nTo prevent login prompts from interfering with **ServerDesk**, disable the default getty on `tty1`:\n\n```bash\nsudo systemctl disable getty@tty1.service\n```\n\nReload systemd and activate the new service:\n\n```bash\nsudo systemctl daemon-reexec\nsudo systemctl daemon-reload\nsudo systemctl enable serverdesk.service\nsudo systemctl start serverdesk.service\n```\n\nNow reboot the system to complete the setup:\n\n```bash\nsudo reboot\n```\n\nAfter rebooting the machine, the **ServerDesk** service should start and run its standard command (`htop`). When interacting with the touch screen, the overlay appears, allowing the user to execute further commands. System buttons on the bottom edge will allow to switch to TTY3 to log in, reboot the system, and shut it down completely.\n\n\u003e [!WARNING]\n\u003e **Important Note on Access**\n\u003e\n\u003e Once **ServerDesk** is active on `tty1`, the system will no longer provide a login prompt on that terminal.\n\u003e\n\u003e Ensure SSH access is available before proceeding — especially on headless systems.\n\u003e\n\u003e Alternatively, you can use `Ctrl + Alt + F2` (or F3–F6) to switch to another virtual terminal and log in there.\n\n----\n\n## Configuration\n\nAll settings and commands correspond to [komed3](https://github.com/komed3)’s server setup. They must be adapted to your own system (RAID, network, etc.). All essential files are listed and explained below in order to configure **ServerDesk** for your own server.\n\n### `cfg/actions.json`\n\nThe heart of **ServerDesk**’s interaction model lies in the `/cfg/actions.json` file. Each touch-sensitive area on the screen is defined here, linking user input to system commands.\n\n```json\n{\n  \"name\": \"htop\",\n  \"cmd\": \"sudo htop\",\n  \"x1\": 40, \"y1\": 40,\n  \"x2\": 340, \"y2\": 120\n}\n```\n\n**Fields:**\n\n- `name`: A short, descriptive label (not shown visually, but helpful for reference).\n- `cmd`: The shell command to execute when this region is tapped. Paths like `%DIR%` or `%TTY%` can be used as placeholders and are automatically replaced at runtime.\n- `x1`, `y1`, `x2`, `y2`: Define a rectangular region (in pixels) on the display. Touches inside this area will trigger the action.\n- `default`: If true, it marks the command to run automatically when **ServerDesk** starts.\n\n### `cfg/iftop`\n\nThe `iftop` action is a special case: it requires specifying the correct network interface in a separate configuration file. You can find your active interface by running:\n\n```bash\nip route | grep default\n```\n\nReplace `enp4s0` with your actual device name, such as `eth0`, `enp3s0` or `wlan0`.\n\nTo apply changes to `iftop`, ensure the following in your `actions.json`:\n\n```json\n{\n  \"name\": \"network\",\n  \"cmd\": \"sudo iftop -c %DIR%/cfg/iftop\"\n}\n```\n\n### `assets/menu.png`\n\nThe visual layout of **ServerDesk** is defined by the `assets/menu.png` image, which is displayed fullscreen. When updating this image, be sure the touch regions in `actions.json` still align visually with the corresponding buttons or labels.\n\nYou can edit or export your layout from any image editing tool (e.g., GIMP or Photoshop) and overwrite the `menu.png` with your own design. It should correspond precisely with the resolution of the touch panel.\n\n----\n\n## Updating ServerDesk via Git\n\nIf you wish to customize **ServerDesk** further — for example by adding your own actions, modifying the menu layout, or integrating new monitoring tools — you are encouraged to fork the [official repository](https://github.com/komed3/serverdesk).\n\nBy creating a fork, you retain full control over your version and can push changes to GitHub at any time.\n\nWhen the service is configured with the following line:\n\n```bash\nExecStartPre=/usr/bin/git -C /home/watchdog/serverdesk pull --quiet\n```\n\n**ServerDesk** will automatically attempt a `git pull` every time the service is (re)started. This means you can apply updates or test new functionality simply by running:\n\n```bash\nsudo systemctl restart serverdesk\n```\n\nNo reboot is necessary to apply most changes — editing `actions.json`, updating the menu image, or changing scripts in `bin/` can all be tested immediately after restarting the service.\n\nIf you encounter a git error like “dubious ownership”, make sure the repository is marked as a safe directory:\n\n```bash\ngit config --global --add safe.directory /home/watchdog/serverdesk\n```\n\nAnd ensure correct file permissions with:\n\n```bash\nsudo chown -R watchdog:watchdog /home/watchdog/serverdesk\n```\n\n---\n\n**© 2025 komed3 (Paul Köhler) / MIT license**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomed3%2Fserverdesk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkomed3%2Fserverdesk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomed3%2Fserverdesk/lists"}