Hearth
A calm, self-hosted home dashboard for a wall-mounted e-paper frame and any browser in the house.
Project site: hearth.lucas-vertrees.me — a tour of the frame, the dashboard and how to build one (source in site/).
What it shows
- Dashboard widgets: Agenda (tasks and calendar events), Weather, Countdowns, Moon Phase, Today's News (RSS), Daily Quote, Today's Arc, Birds Nearby, Almanac, Trains & Buses, Sports, plus Now Playing from Spotify.
- Frame modes: Ambient, Daily (laid out in a template of small, medium and large slots — Full, Halves, Feature, Banner, Quarters — or free columns, with Today's Arc, Today, Coming Up, Week Ahead, Countdowns, Almanac, Moon Phase, Daily Quote, Birds Nearby, Last Played, Last Result & Next Game, a photo of the day, Headlines, Scheduled Departures and On This Day), Photo, Countdown, Night and Note, on a schedule you set in Settings → Frame.
- Pages:
/ dashboard, /calendar month grid, /ambient photo slideshow, /settings, /frame e-paper render target, and an optional /logs (Dozzle).
How it works
One host runs everything behind Caddy. The Display service has the renderer screenshot /frame on a schedule, and the frame pulls the finished, dithered picture.
flowchart LR
browser["Phone / browser<br/>dashboard · settings"]
frame["E-paper frame<br/>Pi Zero 2 W + Inky 13.3″<br/>runs inkypull"]
apis["Upstream APIs<br/>Open-Meteo · Unsplash · Google Calendar<br/>Spotify · eBird · Transitland · ESPN · ZenQuotes<br/>Wikipedia · RSS"]
subgraph host["Host — Docker Compose"]
caddy["Caddy<br/>one origin"]
web["SvelteKit app<br/>dashboard + /frame page"]
services["13 .NET services<br/>Tasks · Calendar · Weather · Photos<br/>Almanac · Birds · Quote · History · RSS<br/>Trains · Sports · Spotify · Display<br/>(own SQLite each)"]
renderer["Renderer<br/>headless Chromium → 6-ink dither"]
end
browser -->|HTTPS| caddy
frame -->|"GET /display/frame (PNG)"| caddy
caddy -->|pages| web
caddy -->|"/tasks, /weather, …"| services
services -->|fetch + cache| apis
services -->|"Display, on a schedule"| renderer
renderer -->|"loads /frame"| caddy
Quick start
You need Docker Engine 25+ and Compose v2.22+. Compose expects each service's .env file to exist, even if it's empty:
touch apps/services/{Almanac,Birds,Calendar,Photos,Spotify,Trains,Weather}/.env
cd infra && docker compose up --build
Open http://localhost and set the home location and time zone in Settings → Home. Tasks, quotes and news work with no keys.
Configuration
Add keys only for the integrations you want. Each file is read by one service:
| Integration | File | Keys | Get a key |
|---|
| Unsplash photos | apps/services/Photos/.env | UNSPLASH_ACCESS_KEY | Unsplash developers |
| Spotify | apps/services/Spotify/.env | SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REDIRECT_URI | Spotify dashboard |
| Google Calendar | apps/services/Calendar/.env | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI | Google Cloud console |
| eBird | apps/services/Birds/.env | EBIRD_API_KEY | eBird API key |
| Transitland | apps/services/Trains/.env | TRANSITLAND_API_KEY | Transitland |
| Frost dates (optional) | apps/services/Almanac/.env | FIRST_FROST, LAST_FROST (MM-DD) | — |
LATITUDE, LONGITUDE and TZ in these files are only fallbacks until a home location is saved in Settings → Home. Every variable, including the redirect URIs to register, is listed per service in docs/SOFTWARE-DESIGN.md: Photos, Spotify, Calendar, Birds, Trains, Almanac, Weather.
Development
docker compose watch (from infra/) runs the stack with hot reload. To run pieces natively instead (needs the .NET 10 SDK and Node.js 20+), start any service with dotnet run --project apps/services/<Service> and the frontend with cd apps/frontend && npm run dev. The ports Vite proxies to are in apps/frontend/vite.config.ts.
Before a PR, run dotnet build Hearth.slnx && dotnet test Hearth.slnx, and npm run check && npm run test in apps/frontend/. More in Development workflow.
Deploying
CI publishes amd64 and arm64 images to GHCR on every green push to main. A host pulls them with infra/deploy/update.sh, run by a systemd timer. See Deploying to a host.
To build the frame itself, see docs/HARDWARE.md and the companion client inky-pull.
Docs
Credits
Hearth is built on these open-source projects and data providers:
- Frontend: SvelteKit and Svelte (MIT), Vite (MIT), Tailwind CSS (MIT), Lucide via
@lucide/svelte (ISC), DOMPurify (MPL-2.0 or Apache-2.0), svelte-dnd-action (MIT), Vitest (MIT), Prettier (MIT)
- Fonts: Fontsource builds of Inter, Fraunces, Lora, Manrope, Nunito, Source Serif 4 and Space Grotesk (SIL OFL 1.1), and Roboto Slab (Apache-2.0)
- Backend: .NET and ASP.NET Core (MIT), SQLite via Microsoft.Data.Sqlite (MIT) and SQLitePCLRaw (Apache-2.0), FusionCache (MIT), SkiaSharp (MIT), SpotifyAPI-NET (MIT), Google APIs .NET client (Apache-2.0), DotNetEnv (MIT), (Apache-2.0)
License
AGPL-3.0 — see LICENSE.
