{"id":51457069,"url":"https://github.com/hyprlab/homepage-gui","last_synced_at":"2026-07-06T01:03:44.133Z","repository":{"id":365503342,"uuid":"1272374743","full_name":"hyprlab/homepage-gui","owner":"hyprlab","description":"Drag-and-drop web GUI for editing gethomepage services.yaml — organize services, edit fields, pick or upload icons, with backups. Runs in Docker. Built with Claude Code.","archived":false,"fork":false,"pushed_at":"2026-07-04T14:40:02.000Z","size":1098,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T15:27:49.669Z","etag":null,"topics":["dashboard","docker","drag-and-drop","flask","gethomepage","homelab","homepage","self-hosted","selfhosted","services-yaml","yaml"],"latest_commit_sha":null,"homepage":"https://hyprlab.co","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyprlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2026-06-17T14:48:23.000Z","updated_at":"2026-07-04T14:44:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyprlab/homepage-gui","commit_stats":null,"previous_names":["viibeware/homepage-gui","hyprlab/homepage-gui"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hyprlab/homepage-gui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyprlab%2Fhomepage-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyprlab%2Fhomepage-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyprlab%2Fhomepage-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyprlab%2Fhomepage-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyprlab","download_url":"https://codeload.github.com/hyprlab/homepage-gui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyprlab%2Fhomepage-gui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dashboard","docker","drag-and-drop","flask","gethomepage","homelab","homepage","self-hosted","selfhosted","services-yaml","yaml"],"created_at":"2026-07-06T01:03:39.606Z","updated_at":"2026-07-06T01:03:44.076Z","avatar_url":"https://github.com/hyprlab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homepage GUI\n\n\u003e A self-hosted, drag-and-drop web editor for [gethomepage](https://gethomepage.dev)'s\n\u003e `services.yaml` — organize sections and services, edit every field, pick or upload icons,\n\u003e and apply changes to your live dashboard. No login, no database, runs in one container.\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)\n[![Docker Image](https://img.shields.io/docker/v/hyprlab/homepage-gui?label=docker%20hub\u0026sort=semver)](https://hub.docker.com/r/hyprlab/homepage-gui)\n[![Docker Pulls](https://img.shields.io/docker/pulls/hyprlab/homepage-gui)](https://hub.docker.com/r/hyprlab/homepage-gui)\n\n![Homepage GUI screenshot](https://raw.githubusercontent.com/hyprlab/homepage-gui/main/docs/screenshot.png)\n\n---\n\n## Table of contents\n\n- [What it does](#what-it-does)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Install with Docker Compose](#install-with-docker-compose)\n  - [1. Get the files](#1-get-the-files)\n  - [2. Configure `.env`](#2-configure-env)\n  - [3. Enable custom icon uploads (optional)](#3-enable-custom-icon-uploads-optional)\n  - [4. Start it](#4-start-it)\n- [Configuration reference](#configuration-reference)\n- [Using the app](#using-the-app)\n- [Custom icon uploads \u0026 the Homepage restart](#custom-icon-uploads--the-homepage-restart)\n- [Backups](#backups)\n- [Updating](#updating)\n- [How icons render](#how-icons-render)\n- [Release notes](#release-notes)\n- [Building from source / development](#building-from-source--development)\n- [Limitations](#limitations)\n- [License](#license)\n\n---\n\n## What it does\n\nHomepage's `services.yaml` is hand-edited YAML: a list of sections, each containing a list\nof services with fields like `icon`, `href`, `description`, `ping`, and widgets. Homepage GUI\ngives that file a fast, modern editor:\n\n- Mount your existing Homepage `config` directory into the container.\n- Edit `services.yaml` visually in your browser, on any LAN device.\n- Saves write **straight back** to the same file Homepage reads, with a timestamped backup\n  every time. Homepage hot-reloads, so changes appear immediately (only new **icon uploads**\n  need a Homepage restart, which the app can do for you).\n\n## Features\n\n- **Drag \u0026 drop** — reorder sections, reorder services within a section, and drag services\n  between sections.\n- **Sidebar** — section navigator with a live filter, plus draggable \"Service\" / \"Section\"\n  blocks you can drop onto the canvas or click to append.\n- **Full service editing** — name, icon, URL (`href`), description and `ping` as first-class\n  fields, plus an **Advanced (YAML)** panel that round-trips widgets, `server`/`container`\n  and any other keys without losing them.\n- **Icon chooser** with combined search across all sources (origin-badged), or per-source tabs:\n  - **Dashboard Icons** (`name.svg`) · **Material Design Icons** (`mdi-`) · **Font Awesome**\n    (`fas-`/`far-`/`fab-`) · **SVG / freesvgicons** (200k+ Iconify icons, stored as a URL).\n  - **My Uploads** — upload your own **PNG/SVG** files.\n- **Icon color overrides** — for sources Homepage can recolor (`mdi-`/`si-`/`sh-` via `-#hex`,\n  and Iconify SVG URLs via `?color=`), with a color picker.\n- **Alphabetical sort** per section (A→Z / Z→A).\n- **Safe saves** — generated YAML is validated before writing, writes are atomic, and a\n  timestamped backup is taken first. Common fields are emitted in Homepage's conventional\n  order (`icon`, `href`, `description`, `ping`); empty fields stay blank, not `null`.\n- **Backups \u0026 restore** in the UI, with **14-day auto-purge** (configurable) and a count cap.\n- **YAML preview** before saving.\n- **One-click Homepage restart** so newly-uploaded icons get served.\n- **In-app release notes** (click the version in the sidebar footer).\n- Self-hosted **Inter** font and cache-busted assets; in-app **Source** link (AGPL §13).\n\n## Requirements\n\n- A host running **Docker** and **Docker Compose v2** (`docker compose …`).\n- An existing **Homepage** install whose `config` directory (containing `services.yaml`) is\n  on the same host.\n- A browser with internet access for icon **search/preview** (Iconify \u0026 jsDelivr CDNs — the\n  same ones Homepage uses). Editing and saving work fully offline.\n\n## Install with Docker Compose\n\nDocker Compose is the supported way to run Homepage GUI.\n\n### 1. Get the files\n\n```bash\ngit clone https://github.com/hyprlab/homepage-gui.git\ncd homepage-gui\n```\n\nThe repo ships a ready-to-use `compose.yaml` that pulls `hyprlab/homepage-gui:latest`:\n\n```yaml\nservices:\n  homepage-gui:\n    image: ${IMAGE:-hyprlab/homepage-gui:latest}\n    build: .\n    container_name: homepage-gui\n    restart: unless-stopped\n    user: \"0:0\"                       # needed to write a root-owned services.yaml\n    environment:\n      - HOMEPAGE_CONFIG_DIR=/config\n      - BACKUP_DIR=/config/.homepage-gui-backups\n      - KEEP_BACKUPS=40\n      - KEEP_BACKUP_DAYS=14\n      - ICONS_DIR=/icons\n      - HOMEPAGE_CONTAINER=${HOMEPAGE_CONTAINER:-homepage}\n    ports:\n      - \"${HOST_PORT:-5005}:5000\"\n    volumes:\n      - ${HOST_CONFIG_DIR:-./config}:/config\n      - ${HOST_ICONS_DIR:-./icons}:/icons\n      - /var/run/docker.sock:/var/run/docker.sock\n```\n\n### 2. Configure `.env`\n\nCopy the example and point it at your host paths:\n\n```bash\ncp .env.example .env\n```\n\n```ini\n# .env\nHOST_CONFIG_DIR=/path/to/homepage/config   # folder containing services.yaml\nHOST_ICONS_DIR=/path/to/homepage/icons     # shared custom-icons folder (see step 3)\nHOST_PORT=5005                             # browse to http://\u003chost\u003e:5005\nHOMEPAGE_CONTAINER=homepage                # your Homepage container's name\n```\n\n\u003e **Tip:** verify the resolved config before starting with `docker compose config`.\n\n### 3. Enable custom icon uploads (optional)\n\nHomepage serves local icons from `/app/public/icons` (referenced as `/icons/\u003cfile\u003e`).\nFor uploads to appear in Homepage, the **same host folder** must be mounted into **both**\ncontainers. Add this volume to your **Homepage** `compose.yaml`:\n\n```yaml\nservices:\n  homepage:\n    volumes:\n      - /path/to/homepage/config:/app/config\n      - /path/to/homepage/icons:/app/public/icons   # \u003c-- add this (matches HOST_ICONS_DIR)\n      - /var/run/docker.sock:/var/run/docker.sock\n```\n\nThen recreate Homepage once: `docker compose up -d` in your Homepage directory.\n\nThe Docker socket mount on the GUI lets its **Restart Homepage** button apply new icons.\nIf you'd rather not expose the socket, omit that volume — uploads still work, you'll just\nrestart Homepage yourself.\n\n### 4. Start it\n\n```bash\ndocker compose up -d\n```\n\nOpen **`http://\u003chost\u003e:5005`** (the port from `HOST_PORT`) on any device on your LAN.\n\n## Configuration reference\n\nThese are set in `compose.yaml`'s `environment:` (container-side) and `.env` (host-side).\n\n**Container environment variables**\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `HOMEPAGE_CONFIG_DIR` | `/config` | Directory (inside the container) holding `services.yaml` |\n| `SERVICES_PATH` | `$HOMEPAGE_CONFIG_DIR/services.yaml` | Override the exact file path |\n| `BACKUP_DIR` | `$HOMEPAGE_CONFIG_DIR/.homepage-gui-backups` | Where backups are written |\n| `KEEP_BACKUPS` | `40` | Hard cap on number of backups (`0` = unlimited) |\n| `KEEP_BACKUP_DAYS` | `14` | Auto-purge backups older than N days (`0` = keep forever) |\n| `ICONS_DIR` | `/icons` | Where uploaded icons are stored (shared with Homepage) |\n| `HOMEPAGE_CONTAINER` | `homepage` | Container the GUI restarts to load new icons |\n| `DOCKER_SOCK` | `/var/run/docker.sock` | Docker socket used for the restart |\n| `SOURCE_URL` | this repo | Source link shown in-app (set to your fork if modified) |\n| `PORT` | `5000` | In-container listen port (host port is mapped in compose) |\n\n**`.env` (host-side, used by compose)**\n\n| Variable | Example | Purpose |\n|---|---|---|\n| `HOST_CONFIG_DIR` | `/srv/homepage/config` | Host path mounted to `/config` |\n| `HOST_ICONS_DIR` | `/srv/homepage/icons` | Host path mounted to `/icons` |\n| `HOST_PORT` | `5005` | Host port mapped to the container's `5000` |\n| `HOMEPAGE_CONTAINER` | `homepage` | Passed through for the restart feature |\n| `IMAGE` | `hyprlab/homepage-gui:1.0.0` | Pin a specific image tag (optional) |\n\nThe container runs as `root` (`user: \"0:0\"`) so it can write a typically root-owned\n`services.yaml`. Change `user:` if your config files are owned by a different UID/GID.\n\n## Using the app\n\n- **Add a section** — the `+` in the sidebar, or drag the \"Section\" block onto the canvas.\n- **Add a service** — a section's `+`, or drag the \"Service\" block into a section.\n- **Edit** — click ✎ on a card (or double-click it) to open the editor; set fields and pick\n  an icon. Use **Advanced (YAML)** for widgets and other keys.\n- **Reorder / move** — drag the ⠿ handles; drag services across sections.\n- **Sort a section** — the ⇅ button (toggles A→Z / Z→A).\n- **Preview** — see the exact YAML before saving.\n- **Save** — `Ctrl/Cmd+S` or the Save button. A backup is taken automatically.\n- **Backups** — open the Backups dialog to restore a previous version.\n\n## Custom icon uploads \u0026 the Homepage restart\n\nIn the icon chooser, the **My Uploads** tab lets you upload **PNG/SVG** icons (button or\ndrag-and-drop). They're saved to the shared icons folder and referenced as `/icons/\u003cfile\u003e`.\nBecause Homepage only reads `public/icons` at startup, **new uploads require a Homepage\nrestart** — use the **Restart Homepage** button in the sidebar (it restarts the\n`HOMEPAGE_CONTAINER` via the Docker socket). Workflow: upload → select the icon for a\nservice → **Save** → **Restart Homepage**.\n\n## Backups\n\nEvery save and restore first writes a timestamped copy to `BACKUP_DIR`\n(`/config/.homepage-gui-backups/` by default — a dot-folder Homepage ignores). Backups older\nthan `KEEP_BACKUP_DAYS` (default **14**) are purged automatically, with `KEEP_BACKUPS`\n(default 40) as a hard cap. Purging runs on each save and whenever the page or Backups dialog\nloads. Restore or inspect any backup from the **Backups** dialog.\n\n## Updating\n\n```bash\ncd homepage-gui\ndocker compose pull        # fetch the latest image\ndocker compose up -d       # recreate the container\n```\n\nTo pin a version, set `IMAGE=hyprlab/homepage-gui:1.0.0` in `.env`.\n\n## How icons render\n\nIcon previews and search use public CDNs (the Iconify API and jsDelivr), so the browser you\nedit from needs internet access — the same CDNs Homepage itself uses for dashboard icons.\nCore editing and saving work fully offline; only icon search/preview needs the network.\n\n## Release notes\n\nSee [CHANGELOG.md](CHANGELOG.md), or click the version number in the app's sidebar footer for\nin-app release notes (both read from the same source).\n\n## Building from source / development\n\nBuild and run the image locally instead of pulling:\n\n```bash\ndocker compose up -d --build\n```\n\nRun the Flask app directly (without Docker) for development:\n\n```bash\npip install -r requirements.txt\nHOMEPAGE_CONFIG_DIR=/path/to/homepage/config \\\nICONS_DIR=/path/to/homepage/icons \\\npython app.py            # serves on http://localhost:5000\n```\n\n**Stack:** Flask + PyYAML + gunicorn (backend); vanilla JS + SortableJS + js-yaml (frontend);\nbundled [Inter](https://rsms.me/inter/) (SIL OFL). No build step, no database.\n\n## Limitations\n\n- Comments in `services.yaml` (other than the standard header) are not preserved — the file\n  is regenerated from the parsed structure. The previous version is always backed up first.\n- Group-level settings (a section whose value is a mapping rather than a list of services)\n  are shown read-only and preserved verbatim; edit those via **Preview**/raw if needed.\n\n## License\n\nLicensed under the **GNU Affero General Public License v3.0** — see [LICENSE](LICENSE).\nBecause Homepage GUI is network-served software, AGPL §13 requires that users who interact\nwith a modified version over a network can obtain its corresponding source. The in-app\n**Source** link and `SOURCE_URL` exist for this — point them at your fork if you modify it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyprlab%2Fhomepage-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyprlab%2Fhomepage-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyprlab%2Fhomepage-gui/lists"}