{"id":46533703,"url":"https://github.com/kts982/homedash","last_synced_at":"2026-04-01T20:02:31.981Z","repository":{"id":342397256,"uuid":"1173824055","full_name":"kts982/Homedash","owner":"kts982","description":"Terminal dashboard for homelab server -  Built with Go + Bubble Tea","archived":false,"fork":false,"pushed_at":"2026-03-20T19:12:57.000Z","size":7023,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-21T10:26:02.373Z","etag":null,"topics":["bubbletea","dashboard","docker","docker-compose","go","golang","homelab","linux","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","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/kts982.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03-05T19:40:47.000Z","updated_at":"2026-03-20T19:12:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kts982/Homedash","commit_stats":null,"previous_names":["kts982/homedash"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/kts982/Homedash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kts982%2FHomedash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kts982%2FHomedash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kts982%2FHomedash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kts982%2FHomedash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kts982","download_url":"https://codeload.github.com/kts982/Homedash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kts982%2FHomedash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: 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":["bubbletea","dashboard","docker","docker-compose","go","golang","homelab","linux","terminal","tui"],"created_at":"2026-03-06T23:04:29.217Z","updated_at":"2026-04-01T20:02:31.972Z","avatar_url":"https://github.com/kts982.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HomeDash\n\n[![CI](https://github.com/kts982/Homedash/actions/workflows/ci.yml/badge.svg)](https://github.com/kts982/Homedash/actions/workflows/ci.yml)\n[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go\u0026logoColor=white)](https://go.dev)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nA terminal dashboard for single-host Linux homelabs.\n\nHomeDash combines host metrics, Docker Compose stacks, stack summaries, container and stack logs, and common stack or container actions in one TUI. It is built for people running a personal server who want one operational view instead of jumping between `docker ps`, `docker logs`, `htop`, and ad-hoc scripts.\n\nIt reads system data from `/proc`, talks directly to the Docker socket, and optionally fetches weather from [wttr.in](https://wttr.in).\n\n\u003e Status: early-stage, Linux-only, source install for now.\n\n## Who It's For\n\n- people running a personal or home Linux server\n- Docker Compose users who think in stacks more than raw Docker objects\n- users who prefer terminal workflows over web dashboards\n\n## Non-Goals\n\n- replacing `lazydocker` as a general Docker admin console\n- managing clusters, Kubernetes, or multi-host fleets\n- being a generic monitoring platform\n\n## Screenshots\n\nScreenshots below use the Dracula theme.\n\n### Dashboard Overview\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"900\" alt=\"HomeDash dashboard overview\" src=\"docs/screenshots/dashboard-overview.png\" /\u003e\n\u003c/p\u003e\n\nFull-width system metrics, grouped Compose stacks, inline health and state, weather in the header, and the dashboard action bar in one view.\n\n### Inspect And Act\n\n\u003cp\u003e\n\u003cimg width=\"430\" alt=\"HomeDash container detail view\" src=\"docs/screenshots/container-detail.png\" /\u003e\n\u003cimg width=\"430\" alt=\"HomeDash quick actions menu\" src=\"docs/screenshots/quick-actions.png\" /\u003e\n\u003c/p\u003e\n\nContainer detail with live logs and metadata, plus the stack or container quick-action popup without leaving the dashboard.\n\n### Alerts Drawer\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"900\" alt=\"HomeDash alerts drawer\" src=\"docs/screenshots/alerts-drawer.png\" /\u003e\n\u003c/p\u003e\n\nPersistent recent events and problem history stay visible without leaving the main screen.\n\n## Features\n\n- **Unified homelab view** - host metrics, Docker containers, and quick actions in one terminal UI\n- **Compose-stack grouping and summaries** - containers grouped by `com.docker.compose.project`, with collapsible stacks, health counts, and aggregate stack status\n- **Container and stack detail views** - full-screen log viewers with default follow mode on entry, merged stack logs, stack resource hotspots, richer mount and label metadata, published port hints, and start/stop/restart actions\n- **Log search and navigation** - `/` in detail views highlights matches across logs, with `n`/`N` to cycle through them\n- **Quick-action menu** - `space` opens fast stack or container actions, including stack logs, without leaving the dashboard\n- **System metrics** - full-width two-column panel with CPU/RAM sparklines, gauges with disk usage/capacity detail, load averages, Linux task and file-handle counts, network I/O, and swap\n- **Dashboard sort and filter** - filter containers by text or field tokens such as `state:running`, `health:unhealthy`, `stack:infra`, and `image:nginx`, then cycle sort modes for quick triage\n- **Deterministic test mode** - `--test-mode` flag for developers to run the TUI with synthetic data and frozen UI elements for stable testing and screenshots (internal helper)\n- **Focus-aware refresh** - background polling pauses automatically when the terminal loses focus on the dashboard, and resumes with an immediate refresh on refocus; detail/log views stay live regardless\n- **Freshness indicators** - system and container panel titles show current data age and mark stale snapshots when refresh falls behind\n- **Notifications and alerts drawer** - Docker state and health transitions, disk warnings, weather errors, and a persistent problems/history view with timestamps for recent events\n- **Weather** - current conditions via [wttr.in](https://wttr.in), shown in the header bar with responsive degradation\n- **Responsive layout** - works across narrow and wide terminals\n- **State persistence** - collapsed stack groups are remembered across sessions at `~/.config/homedash/state.json`\n- **Themes, options, and mouse support** - Tokyo Night, Catppuccin, Dracula, an in-app options dialog for theme, disk, refresh, and Docker settings, plus click and scroll navigation\n\n## Status\n\nHomeDash is early-stage, but usable for day-to-day homelab monitoring and container operations.\n\nCurrent scope:\n\n- Linux only\n- single host only\n- Docker and Docker Compose focused\n- source install first\n\nExpect ongoing UI and feature changes while the project settles.\n\n## Roadmap\n\nNear term:\n\n- packaging and release improvements\n\nNot planned:\n\n- Kubernetes support\n- multi-host orchestration\n- generic Docker object management beyond the homelab workflow\n\n## Install\n\n### From source\n\nRequires [Go 1.25+](https://go.dev/dl/) and Linux.\n\n```bash\ngit clone https://github.com/kts982/Homedash.git\ncd Homedash\nmake build\n./homedash\n```\n\n### Development\n\nRun the local checks before pushing:\n\n```bash\ngo test ./...\nmake lint\n```\n\n### Requirements\n\n- **Linux** (reads from `/proc`)\n- **Docker socket** accessible at `/var/run/docker.sock` (no sudo needed if your user is in the `docker` group)\n- **Optional**: Internet access for weather via [wttr.in](https://wttr.in)\n\n## Configuration\n\nHomeDash uses a YAML config file at `~/.config/homedash/config.yaml`. All fields are optional, and unknown fields are rejected to catch typos.\n\nIf the config file does not exist, HomeDash starts with auto-detected local mounts where possible and falls back to `/` if detection yields nothing useful.\n\nPress `O` on the dashboard to open the Options dialog and save theme, disks, refresh intervals, and Docker host back to this file.\n\nSee [`config.example.yaml`](config.example.yaml) for a full annotated example.\n\n### Config Reference\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `theme` | string | `tokyo-night` | Color theme: `tokyo-night`, `catppuccin`, `dracula` |\n| `system.disks` | list | auto-detected local mounts, with `/` fallback | Disk mount points to monitor |\n| `system.disks[].path` | string | required | Absolute path to mount point |\n| `system.disks[].label` | string | same as path | Display label |\n| `refresh.system` | duration | `2s` | System metrics refresh interval (min: `1s`) |\n| `refresh.docker` | duration | `5s` | Docker stats refresh interval (min: `3s`) |\n| `refresh.weather` | duration | `5m` | Weather refresh interval (min: `1m`) |\n| `docker.host` | string | `unix:///var/run/docker.sock` | Docker daemon socket |\n\nThe Docker host can also be set via the `DOCKER_HOST` environment variable, which takes precedence over the config file.\n\n### Config Examples\n\n#### Minimal Config\n\n```yaml\n# Just override what you need\ntheme: dracula\nsystem:\n  disks:\n    - path: /\n    - path: /mnt/storage\n      label: storage\n```\n\n#### Lower Refresh Rates\n\n```yaml\nrefresh:\n  system: 5s\n  docker: 10s\n  weather: 10m\n```\n\n## State File\n\nHomeDash saves UI state (collapsed stack groups) to `~/.config/homedash/state.json`. This file is managed automatically and does not need manual editing. The state path is not configurable.\n\n## Key Bindings\n\n### Dashboard\n\n| Key | Action |\n|-----|--------|\n| `tab` / `shift+tab` | Cycle focused panel |\n| `j` / `k` or `Up` / `Down` | Select container / group |\n| `PgUp` / `PgDn` | Page through the container / stack list |\n| `Home` / `End` | Jump to the first / last visible item |\n| `a` | Toggle the alerts / problems drawer |\n| `O` | Open the options dialog |\n| `enter` | Expand/collapse selected stack, or open selected container detail |\n| `l` | Open logs for the selected container or stack |\n| `o` | Cycle dashboard sort mode (`default`, `cpu`, `mem`, `unhealthy`) |\n| `space` | Open quick-action menu for selected container or stack |\n| `/` | Search / filter containers |\n| `s` | Stop selected container or stack (with confirmation) |\n| `S` | Start selected container or stack (with confirmation) |\n| `R` | Restart selected container or stack (with confirmation) |\n| `r` | Force refresh all data |\n| `q` / `ctrl+c` | Quit |\n\nContainer filtering supports plain text plus field tokens like `state:running`, `health:unhealthy`, `stack:infra`, and `image:nginx`.\n\n### Detail View\n\n| Key | Action |\n|-----|--------|\n| `esc` / `q` | Back to dashboard |\n| `j` / `k` or `Up` / `Down` | Scroll logs |\n| `ctrl+u` / `ctrl+d` or `PgUp` / `PgDn` | Scroll by half page |\n| `g` / `G` | Jump to top / bottom of logs |\n| `f` | Toggle log follow mode (live streaming) |\n| `/` | Search logs (substring highlight) |\n| `n` / `N` | Jump to next / previous search match |\n| `l` | Refresh logs |\n| `s` | Stop current container or stack |\n| `S` | Start current container or stack |\n| `R` | Restart current container or stack |\n\nSelecting `View Stack Logs` from the stack quick-action menu opens a merged stack log view while leaving `enter` on dashboard stack rows reserved for expand/collapse.\n\n### Mouse\n\n| Action | Effect |\n|--------|--------|\n| Click container row | Select container |\n| Click group header | Toggle collapse |\n| Double-click container | Open detail view |\n| Scroll wheel | Scroll container list or logs |\n\n## How It Works\n\n```\n/proc/stat, /proc/meminfo, ...  ──2s──\u003e  System panel (full-width, two-column)\n/var/run/docker.sock (API v1.47) ──5s──\u003e  Container list + stats\nwttr.in JSON API               ──5min──\u003e  Header bar (compact weather)\n```\n\nMost data collection is tick-driven through [Bubble Tea](https://charm.land/bubbletea) commands. Docker container stats are fetched in parallel with a 5-worker pool, and log follow mode uses streaming goroutines tied to the active container or stack detail view. Background polling pauses when the terminal loses focus on the dashboard and resumes on refocus.\n\nContainers are grouped by the `com.docker.compose.project` label, so any compose-based setup works automatically. Standalone containers appear ungrouped.\n\n## Project Structure\n\n```\ncmd/homedash/           Entry point\ninternal/collector/     Data collection (system, docker, weather)\ninternal/config/        YAML config loader\ninternal/state/         Persistent UI state\ninternal/ui/            Bubble Tea UI layer\n  components/           Reusable primitives (gauge, sparkline, panel)\n  panels/               Screen sections (system, containers, detail, header, help)\n  styles/               Theme palettes\n```\n\n## Built With\n\n- [Go](https://go.dev) — language\n- [Bubble Tea v2](https://charm.land/bubbletea) — TUI framework\n- [Bubbles v2](https://charm.land/bubbles) — TUI components\n- [Lip Gloss v2](https://charm.land/lipgloss) — terminal styling and layout compositing\n\n## Troubleshooting\n\n**\"Cannot connect to Docker\"** — Ensure the Docker socket exists and your user has access:\n```bash\nls -la /var/run/docker.sock\n# If permission denied, add yourself to the docker group:\nsudo usermod -aG docker $USER\n# Then log out and back in\n```\n\n**No weather data** — Requires outbound HTTP access to `wttr.in`. Weather will retry automatically on failure.\n\n**Disk not showing** — Check that the mount path in your config is correct and accessible. Inaccessible paths show a warning notification instead of silently failing.\n\n**High CPU usage** — Increase the refresh intervals under [Configuration](#configuration), especially `refresh.system` and `refresh.docker`.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkts982%2Fhomedash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkts982%2Fhomedash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkts982%2Fhomedash/lists"}