cailurus/hearth repository overview

⁠Hearth

A lightweight, self-hosted home dashboard for your services.

中文文档⁠

⁠✨ Features

⁠Navigation & Layout

• 🏠 Grouped App Links - Organize your services into custom groups
• 🔖 Bookmarks - Compact pill-style link groups for quick access
• 🔍 Quick Launch - Cmd/Ctrl+K to search apps instantly, with pinyin support
• 🟢 Service Status - Live health-check indicators (supports HTTPS with self-signed certs)
• 🖱️ Drag & Drop - Reorder groups and items freely
• 🎨 Frosted Glass UI - Borderless glassmorphism card design with backdrop blur

⁠Widgets

• 🌤️ Weather - Current weather with 7-day forecast (Open-Meteo, no API key needed)
• 📈 Market Ticker - US stocks, HK stocks, and crypto prices with intraday sparkline charts (Yahoo Finance)
• 💱 Currency Exchange - Up to 4 currency pairs with 30-day history sparklines and flag emojis (Frankfurter API)
• 📰 RSS Feed - Aggregate up to 10 RSS/Atom feeds with manual refresh, resizable height
• 🕐 World Clock - Up to 4 configurable timezone clocks
• 📊 System Metrics - CPU, memory, disk, and network monitoring with historical charts (7-day retention)
• 🐳 Docker Monitoring - Container status, resource usage, start/stop/restart actions
• 🗓️ Holidays - Upcoming holidays for selected countries
• 📝 Notes - Quick notes and memos

⁠Personalization

• 👋 Greeting & Daily Quote - Time-based greeting with daily quotes (Hitokoto in Chinese, ZenQuotes in English)
• 🗓️ Solar Terms - Optional Chinese 24 solar terms display next to date (toggleable)
• 🎨 Dynamic Backgrounds - Bing daily, random, Unsplash, Picsum, or video backgrounds
• 🌓 Bilingual UI - Chinese and English with full i18n
• 📱 Mobile Friendly - Responsive design for all devices
• ✨ Easter Eggs - 5 hidden particle effects (snow, rain, sakura, firefly, shooting stars)

⁠🚀 Quick Start

⁠Docker (Recommended)

docker run -d \
  --name hearth \
  -p 8787:8787 \
  -v hearth-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --restart unless-stopped \
  cailurus/hearth:latest

Open http://localhost:8787 and log in as admin. Use HEARTH_INITIAL_PASSWORD if configured; otherwise find the generated first-run password in docker logs hearth.

⁠Docker Compose

services:
  hearth:
    image: cailurus/hearth:latest
    ports:
      - "8787:8787"
    volumes:
      - hearth-data:/data
      - /var/run/docker.sock:/var/run/docker.sock  # Optional: enables Docker monitoring
    restart: unless-stopped

volumes:
  hearth-data:

⁠🔐 Security

To retrieve the generated password from a running container:

docker logs hearth | head -20

⁠⚙️ Configuration

⁠Widget data and offline behavior

• Widgets load independently. A failed refresh retains usable previous data and displays a warning instead of turning a provider failure into a zero price or an endless loading placeholder.
• Weather, resolved locations, reference exchange rates, RSS metadata, annual holiday data and quotes use bounded snapshots under $HEARTH_DATA_DIR/widget-cache. The existing Docker data volume preserves them across restarts. Expired but usable snapshots are displayed while one background refresh runs; data beyond the retention limit is not presented as current.
• A first visit without any usable snapshot still needs a successful provider response. Timeouts, partial results, pending refreshes and source timestamps are shown explicitly. Manual RSS refresh bypasses the fresh cache.
• Picking a weather city saves its coordinates. Existing city-only configurations remain supported through a bounded, cached lookup that does not fetch timezone data before weather.
• Frankfurter v1 provides working-day reference rates, not bank buy/sell quotes. Market prices retain their actual currency and provider observation time; they are not guaranteed live trading data. Yahoo/CoinGecko prices remain memory-only, and deployments must comply with provider data-use terms.
• A verified 2026 Chinese holiday calendar is included for offline startup, with its source license and provenance. Annual data is updated in the background; unpublished future holidays are not invented.
• Chinese daily quotes use Hitokoto; English quotes use ZenQuotes. Provider attribution remains visible. No paid provider or shared API credential is enabled automatically.

mkdir -p /vol2/1000/ServiceStore/docker-sock
mount --bind /var/run /vol2/1000/ServiceStore/docker-sock

⁠🔍 Comparison

The self-hosted dashboard space has several mature options. Hearth is built for Chinese-speaking home users on NAS platforms (fnOS / Synology / ZSpace) who want a personal launcher with a sense of warmth — pinyin Cmd+K search, glassmorphism UI, 24 solar terms, particle Easter eggs. The table below is a reference, not a ranking.

Choosing the right tool. If you run dozens of services and want auto-discovery via Docker labels, pick homepage. If you want the prettiest news-reader-style aggregator with the smallest footprint, pick glance. If you need shared dashboards with SSO and RBAC for a team, pick homarr. If you are a Chinese-speaking home user who wants pinyin search, seasonal touches, and a single-binary backend, Hearth is built for that taste.

⁠🐳 Docker Labels (auto-discovery)

Hearth can pick apps up from the labels on your running Docker containers and add them to the dashboard automatically — no UI clicks per service. Add a few labels to any container's docker-compose.yml and the app appears within ~30 seconds:

services:
  jellyfin:
    image: jellyfin/jellyfin
    labels:
      - "hearth.name=Jellyfin"
      - "hearth.group=Media"
      - "hearth.href=http://nas.lan:8096/"
      - "hearth.icon=lucide:film"
      - "hearth.description=Movie & TV server"

Already on gethomepage / homepage? Hearth also reads homepage.* labels with the same field names, so you can keep your existing docker-compose unchanged. When both prefixes are set on the same container, hearth.* wins per-field.

Lifecycle: Containers must be in state="running" to appear. Stopping or removing a container makes the app vanish from the dashboard within 30 seconds. Docker-discovered apps are read-only in the UI (the backend refuses PUT / DELETE on them) — labels are the source of truth.

Toggling discovery off: Set HEARTH_DOCKER_LABEL_INTERVAL=0 to disable the polling loop entirely.

⁠🛠️ Development

# Prerequisites: Go 1.25+, Node.js 20+

git clone https://github.com/cailurus/Hearth
cd Hearth

# Dev mode (backend + frontend with hot reload)
make dev

# Build production
make build
./dist/hearth

⁠📁 Data Storage & Persistence

All data (including user credentials, app links, settings) is stored in /data:

data/
├── hearth.db    # SQLite database (users, apps, settings)
├── icons/       # Cached app icons
└── cache/       # Background images

⁠Persisting Data Across Container Updates

To ensure your data survives container updates, mount a volume or host directory:

Using Docker named volume (recommended):

docker run -d -v hearth-data:/data cailurus/hearth:latest

Using host directory:

docker run -d -v /path/to/my/data:/data cailurus/hearth:latest

When updating the container, your data remains intact:

docker pull cailurus/hearth:latest
docker stop hearth && docker rm hearth
docker run -d --name hearth -p 8787:8787 \
  -v hearth-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  cailurus/hearth:latest

⁠📄 License

MIT⁠