Homepage GUI

Homepage GUI is a self-hosted, drag-and-drop web editor for gethomepage's services.yaml. Instead of hand-editing YAML, you arrange your dashboard by dragging sections and services around in the browser — with automatic backups, a YAML preview, and one-click live reload to your running Homepage instance.

Features

Drag & drop reordering of sections, services within a section, and services across sections
Full service editing — name, icon, URL, description, ping, and advanced YAML fields (widgets, server/container keys)
Icon chooser across Dashboard Icons, Material Design Icons, Font Awesome, 200k+ Iconify icons, and your own PNG/SVG uploads, with per-icon color overrides
Safe saves — atomic writes, validation, and automatic timestamped backups with a restore UI (14-day auto-purge, count cap)
YAML preview before you commit, plus alphabetical sort per section
One-click Homepage restart so new icons load immediately
Self-hosted Inter font; core editing and saving work fully offline

Requirements

A host running Docker and Docker Compose v2
An existing Homepage install with a config directory (containing services.yaml)

Install with Docker Compose

Grab the files and create your .env:

git clone https://github.com/hyprlab/homepage-gui.git
cd homepage-gui
cp .env.example .env

Point .env at your Homepage install:

HOST_CONFIG_DIR=/path/to/homepage/config
HOST_ICONS_DIR=/path/to/homepage/icons
HOST_PORT=5005
HOMEPAGE_CONTAINER=homepage

compose.yaml:

services:
  homepage-gui:
    image: ${IMAGE:-hyprlab/homepage-gui:latest}
    container_name: homepage-gui
    restart: unless-stopped
    user: "0:0"
    environment:
      - HOMEPAGE_CONFIG_DIR=/config
      - BACKUP_DIR=/config/.homepage-gui-backups
      - KEEP_BACKUPS=40
      - KEEP_BACKUP_DAYS=14
      - ICONS_DIR=/icons
      - HOMEPAGE_CONTAINER=${HOMEPAGE_CONTAINER:-homepage}
    ports:
      - "${HOST_PORT:-5005}:5000"
    volumes:
      - ${HOST_CONFIG_DIR:-./config}:/config
      - ${HOST_ICONS_DIR:-./icons}:/icons
      - /var/run/docker.sock:/var/run/docker.sock

Start it, then open http://<host>:5005:

docker compose up -d

To build from source instead, use docker compose up -d --build.

Configuration

Variable	Default	Purpose
`HOMEPAGE_CONFIG_DIR`	`/config`	Directory holding `services.yaml`
`BACKUP_DIR`	`$HOMEPAGE_CONFIG_DIR/.homepage-gui-backups`	Where backups are stored
`KEEP_BACKUPS`	`40`	Hard cap on backup count (`0` = unlimited)
`KEEP_BACKUP_DAYS`	`14`	Auto-purge backups older than N days (`0` = keep forever)
`ICONS_DIR`	`/icons`	Uploaded-icon storage
`HOMEPAGE_CONTAINER`	`homepage`	Container name used by the restart feature

Updating

cd homepage-gui
docker compose pull
docker compose up -d

Pin a specific version with IMAGE=hyprlab/homepage-gui:1.0.0 in .env.

Tech stack & license

Flask · PyYAML · gunicorn on the backend; vanilla JavaScript · SortableJS · js-yaml on the front — no build step, no database. Free and open source under the GNU AGPL-3.0. Full docs and releases on GitHub.