🐇 RabbitHome

A personal, customizable home dashboard — inspired by Glance, but trimmed down and tailored to the widgets and interactions I actually want.

Widgets: Clock · Weather · RSS · Hacker News · Markets · Calendar.

Everything is customized in the UI — no config files to edit. Add feeds and tickers with a button, drag widgets around, drop in background photos (the text auto-adjusts for contrast), and pick fonts/units.

---

Getting started

There are two ways to run RabbitHome. Pick one:

• Option A — Docker (recommended): one command, runs anywhere, auto-starts on reboot. Best if you just want to use it.
• Option B — Standalone: build it from source and run the binary directly. Best if you want to hack on it or don't want Docker.

Both serve the dashboard at http://localhost:7171.

---

Option A — Docker

Step 1 — Install Docker

• Windows / macOS: download Docker Desktop from https://www.docker.com/products/docker-desktop/ and install it.
• Linux (Ubuntu): install Docker Engine following https://docs.docker.com/engine/install/ubuntu/.

Step 2 — Make sure Docker is running

Run:

docker info

• If you see a Server: section with details → Docker is running. ✅
• If you see Cannot connect to the Docker daemon… → start it:
  • Windows/macOS: open the Docker Desktop app and wait for "running".
  • Linux: sudo systemctl enable --now docker (this also makes it start on boot).

About sudo (Linux): if docker commands say "permission denied", you have two choices:

1. Prefix every command with sudo (e.g. sudo docker compose up -d), or
2. Add yourself to the docker group once so you never need sudo:

   sudo usermod -aG docker $USER
   newgrp docker        # or just log out and back in

All commands below work with or without sudo — add it if needed.

Step 3 — Start RabbitHome

Easiest (uses the prebuilt image — no download of source code):

mkdir -p ~/rabbithome && cd ~/rabbithome
curl -sL https://raw.githubusercontent.com/Jacobsonradical/RabbitHome/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

That makes a folder ~/rabbithome, drops a docker-compose.yml into it, and starts the container in the background.

Or build it yourself from source (if the prebuilt image isn't available):

git clone https://github.com/Jacobsonradical/RabbitHome.git
cd RabbitHome
docker build -t rabbithome:latest .
docker run -d --name rabbithome --restart unless-stopped \
  -p 7171:7171 -v rabbithome-data:/data rabbithome:latest

What the docker run flags mean:

• -d — run in the background.
• --name rabbithome — name it so it's easy to manage.
• --restart unless-stopped — auto-start on every reboot (see below).
• -p 7171:7171 — expose it on your machine's port 7171.
• -v rabbithome-data:/data — save your dashboard + backgrounds in a volume so they survive restarts and updates.

Step 4 — Open it

Go to http://localhost:7171 in your browser.

Managing it

docker ps                     # is it running? look for "rabbithome"
docker logs -f rabbithome     # view logs (Ctrl+C to stop watching)
docker stop rabbithome        # stop
docker start rabbithome       # start again
docker rm -f rabbithome       # remove the container (your data stays in the volume)

Auto-start on reboot

Two things make this work, and both are already handled above:

1. The Docker service starts on boot — sudo systemctl enable --now docker (Linux), or enable "Start Docker Desktop when you log in" in Docker Desktop settings.
2. The container has a restart policy — --restart unless-stopped (the docker run above) or restart: unless-stopped (the compose file).

After a reboot, check with docker ps — it should already be Up.

Updating later

# prebuilt-image method:
cd ~/rabbithome && docker compose pull && docker compose up -d

# from-source method:
cd RabbitHome && git pull && docker build -t rabbithome:latest . \
  && docker rm -f rabbithome \
  && docker run -d --name rabbithome --restart unless-stopped \
     -p 7171:7171 -v rabbithome-data:/data rabbithome:latest

Your config and backgrounds live in the rabbithome-data volume, so they survive updates.

---

Option B — Standalone (build from source)

Step 1 — Install the tools

You need Go ≥ 1.25 and Node.js ≥ 20.

• Go: download from https://go.dev/dl/ (or sudo apt install golang-go on recent Ubuntu — check go version is ≥ 1.25).
• Node.js: download from https://nodejs.org/ (or use nvm: nvm install 20).

Verify:

go version     # should print go1.25 or newer
node --version # should print v20 or newer

Step 2 — Get the code

git clone https://github.com/Jacobsonradical/RabbitHome.git
cd RabbitHome

Step 3 — Build

make build

This installs the frontend dependencies, builds the web UI, and compiles everything into a single program called rabbithome in the current folder.

Step 4 — Run

./rabbithome                       # opens in Firefox (default)
./rabbithome --browser chrome-app  # chromeless app-style window instead
./rabbithome --serve               # just serve; open http://localhost:7171 yourself

--browser accepts firefox | chrome-app | default | auto.

Your settings are saved to ~/.config/rabbithome/ (override with the RABBITHOME_DATA environment variable).

---

Using the dashboard

• ＋ Add widget — pick any component; it drops onto the grid.
• ✥ Arrange — drag widgets by their header, resize from the corner, rename inline, or remove. The layout saves automatically.
• ⚙ Settings — choose a font and text size, upload background photos (static or shuffle), and enable OS notifications.
• RSS — add feed URLs and optional "filter words". A filter word (e.g. AI) splits the feed into an AI category and Other by title; categories collapse. Set the max length, click ✕ to permanently ignore an item, read items dim, and new items raise a notification.
• Weather — auto-detects your location (or search a place); shows the current temperature in both °C and °F, an hourly strip, and a past+future daily forecast with wind, rain %, and sunrise/sunset.
• Markets — one tab per ticker; each shows price, an interactive intraday chart (hover for price + time), key stats, and company-specific news. Add a stock by searching its name (e.g. "Nvidia" → NVDA).
• Clock — an analog dial set in a starfield, with the live digital time.

---

How it works

A single Go binary serves a small REST API and the embedded React app, so there's nothing else to install. It runs three ways: a standalone window, a plain web app (--serve), or in Docker.

• Backend: Go. Uses only key-free data sources so anyone can run it: Open-Meteo (weather + geocoding), Hacker News API, Yahoo Finance (quotes, news, symbol search), ipapi (IP geolocation), and any RSS/Atom feed.
• Frontend: React + Vite, react-grid-layout for drag/resize.
• Persistence: the whole dashboard is one JSON document the backend stores verbatim (config.json); backgrounds are saved as files. Both live in ~/.config/rabbithome/, or /data inside Docker.

main.go            entry: starts the server, opens the window/browser
launch.go          standalone window (Firefox by default; chrome-app for a chromeless window)
internal/server/   HTTP routes (data APIs, config, background upload, static SPA)
internal/feeds/    upstream integrations (rss, hn, weather, markets, news, geo) + cache
internal/config/   on-disk paths + atomic config save
web/               React frontend (built into web/dist, embedded into the binary)

Development (hot reload)

make dev-api   # Go backend on :7171
make dev-web   # Vite dev server on :5173 (proxies /api to the backend)

---

Notes & limitations

• Notifications are a browser feature, so they only fire while the page is open (a background tab is fine). They don't fire with the browser fully closed. On http://localhost they work after you click "allow".
• Calendar is a local month view (clickable days); Google Calendar sync is a planned follow-up.
• A Reddit widget was originally planned but removed — Reddit shut down unauthenticated access to its public JSON (HTTP 403).
• The standalone window opens a browser (Firefox by default) rather than an embedded webview, because the common Go webview binding needs webkit2gtk-4.0, which Ubuntu 24.04 replaced with 4.1.