Files
dahoam/README.md
T
Niklas Haiden b6e5d81dc0 feat: status dots show whether a link's address answers
With STATUS_CHECKS=true the server requests the address of every link of
the open dashboard once a minute and the tile shows a green dot or a red
ring. Off by default: users choose the addresses, so a user could find
out which hosts and ports the server reaches.
2026-11-21 19:19:44 +01:00

6.3 KiB

Dahoam

A start page for your homelab: wallpaper, clock, search and your links. TanStack Start, Collabry components, Better Auth, Drizzle and Postgres. See PLAN.md.

Run

cp .env.example .env          # then set BETTER_AUTH_SECRET (openssl rand -base64 32)
docker compose up -d          # Postgres on localhost:5432
pnpm install
pnpm dev                      # http://localhost:3000

Production: pnpm build && pnpm start (reads .env when present, PORT sets the port).

The server applies the database migrations in drizzle/ when it starts. If that fails, it stops.

Image and CI

.gitea/workflows/images.yml checks the code (typecheck, lint, tests) and builds the image for linux/amd64 and linux/arm64. A push to main also pushes it to the registry as $REGISTRY_PATH/web, tagged :<short sha> and :latest. Pull requests only build.

The repository on Gitea needs:

  • variable REGISTRY_PATH: registry and Harbor project, for example reg.nhaiden.io/dahoam
  • secrets HARBOR_USERNAME and HARBOR_PASSWORD: a robot account that can push to that project

Run the image:

docker run -p 3000:3000 \
  -e DATABASE_URL=postgres://user:password@host:5432/dashboard \
  -e BETTER_AUTH_SECRET=... -e BETTER_AUTH_URL=https://home.example.com \
  reg.nhaiden.io/dahoam/web:latest

Build it yourself: docker build -t dahoam .

Configuration

Variable Purpose
DATABASE_URL Postgres connection string
BETTER_AUTH_SECRET Signs sessions. Required.
BETTER_AUTH_URL Public URL of the app
TRUSTED_PROXIES IPs/CIDRs of your reverse proxy, comma separated. The login rate limit needs it to tell clients apart.
DISABLE_SIGNUP true closes email/password registration. Set it after you made your account.
OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET Turns on the SSO button. Redirect URI: <BETTER_AUTH_URL>/api/auth/callback/sso
OIDC_PROVIDER_NAME Text on the SSO button ("Continue with …")
STATUS_CHECKS true shows on every link whether its address answers. Off by default, see Notes.
SEARXNG_URL Your SearXNG instance. Makes SearXNG selectable in Settings.

Use

  • Dashboards are separate sets of cards, for example Home and Work. Settings → Dashboards adds, renames and deletes them and sets the default, the one that opens when you sign in. With more than one, switch at the top of the page or with /switch to work. The address of a dashboard (/?d=…) can be bookmarked. Every dashboard has its own wallpaper, clock and search are the same on all.
  • Cards group your links (Apps, Media, Bookmarks, ...). "New card" under the cards adds one. Click a card's name to rename or delete it.
  • Links: + at the top or on a card adds a link. Hover a link and click the pencil to edit or delete it.
  • Move links by dragging, inside a card or to another card. Touch: press and hold first. Keyboard: focus a link, Space picks it up, arrow keys move it, Space puts it down.
  • Move cards by dragging their title bar, the links come along. Touch: press and hold first. Keyboard: Space on the grip next to the plus, arrow keys, Space.
  • Icons: leave the field empty and the icon is looked up by name in dashboard-icons, then from the site's /favicon.ico. When the library has a light version of the icon (github-light), that one is used, because the cards are dark. Or type in the field to search that library and click an icon, paste an image URL, or upload your own image (PNG, JPEG, WebP, AVIF or SVG, up to 1 MB).
  • Status (with STATUS_CHECKS=true): a green dot on a link means that its address answers, a red ring that it does not. Checked once a minute.
  • Search: / focuses the bar. !w cats uses DuckDuckGo bangs. /settings, /add link, /add card, /add dashboard and /sign out run commands.
  • Open a link from the search bar: type the start of its name (jel for Jellyfin). The link is highlighted and Enter opens it. To search the web for the same word, press the up arrow first, so that no row is highlighted. /jel shows only your links and commands.
  • Wallpaper: Settings (or the pencil at the bottom right) takes an image URL or an upload (JPEG, PNG, WebP, AVIF, up to 10 MB). A slider sets how much it is darkened. Each dashboard has its own: the pencil opens the one of the dashboard you are on, and Settings → Wallpaper has a switch for the others.
  • Clock: Settings has five fonts and three styles. Glass shows the wallpaper blurred through the digits, Tinted takes its color from the wallpaper.

Notes

  • Suggestions come from DuckDuckGo, or from SearXNG (/autocompleter) when it is the selected engine. The server fetches them, the browser never calls those hosts directly.
  • Status checks: the server requests each link's address (a GET, redirects are not followed, the answer is thrown away) and tells the browser only up or down. Up is any answer below 500, and also a certificate that the server does not trust. Because users choose the addresses, a user can find out which hosts and ports the server can reach. Turn it on for people you trust, together with DISABLE_SIGNUP=true.
  • SSO does not take over an existing password account with the same email (Better Auth blocks it, because password emails are not verified). Use one or the other per email.
  • Icon lookups send the link name to the jsDelivr CDN. The link dialog also loads the library's list of icons from there, and so does the server, once a day.
  • Uploaded icons are stored in Postgres and only their owner can load them. One that no link uses any more is deleted with that user's next upload.
  • UI components come from collabry-components, copied into src/vendor/collabry at a pinned commit. Add or update one with scripts/sync-collabry.sh (see src/vendor/collabry/UPSTREAM.md). The glass look is applied from outside, in src/components/glass.tsx and src/styles.css.
  • Schema changes: edit src/db/schema.ts, then pnpm db:generate. The server applies the new migration on its next start (pnpm db:migrate does the same without a start).
  • pnpm test, pnpm typecheck, pnpm lint.

Default wallpaper: photo by Andrew Coelho on Unsplash.