Replica of the reference start page: wallpaper, serif clock, search bar and link cards, as a TanStack Start app. - Better Auth: email/password and OIDC single sign-on - Postgres with Drizzle for the auth tables, cards, links, settings and uploaded wallpapers; the server applies the migrations on start - cards group links; links are dragged inside and between cards - search with DuckDuckGo, SearXNG or Google, suggestions and / commands - settings page: name, search engine, wallpaper, account - UI from collabry-components, copied into src/vendor/collabry - Dockerfile and a Gitea workflow that checks the code, builds the image for amd64 and arm64 and pushes it to the registry on main
86 lines
4.1 KiB
Markdown
86 lines
4.1 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
|
|
|
|
- **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.
|
|
- **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 enter an icon name (`home-assistant`) or an image URL.
|
|
- **Search**: `/` focuses the bar. `!w cats` uses DuckDuckGo bangs. `/plex` jumps to
|
|
a link, `/settings`, `/add link`, `/add card` 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).
|
|
|
|
## 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.
|
|
- 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.
|