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

• docs/PRODUCT.md — what Hearth is for and what's planned
• docs/SOFTWARE-DESIGN.md — architecture, services, endpoints and environment variables
• docs/HARDWARE.md — the e-paper frame build

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.