Files
dahoam/README.md
T
niklas 5001cae163
images / check (push) Successful in 30s
images / image (push) Successful in 21s
add ability to move cards
2026-11-19 18:07:50 +01:00

101 lines
5.3 KiB
Markdown

# 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](PLAN.md).
## Run
```bash
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:
```bash
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 …") |
| `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](https://github.com/homarr-labs/dashboard-icons), then from the
site's `/favicon.ico`. 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).
- **Search**: `/` focuses the bar. `!w cats` uses DuckDuckGo bangs. `/plex` jumps to
a link, `/settings`, `/add link`, `/add card`, `/add dashboard` and `/sign out` run 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.
- 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.
- 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](https://git.nhaiden.io/niklas/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](https://unsplash.com/photos/VB-w_3dnyvI) on Unsplash.