The card dialog has a dashboard field. Settings orders the dashboards with arrows. The link dialog offers the images that were uploaded before.
121 lines
6.9 KiB
Markdown
121 lines
6.9 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 …") |
|
|
| `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, orders 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, or to move it to another dashboard.
|
|
- **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`. 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).
|
|
The images that you uploaded before are offered again under "Your images".
|
|
- **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.
|
|
- **Export and import**: Settings → Export and import downloads all dashboards with their
|
|
cards and links as one JSON file, and loads such a file again. It also takes the bookmarks
|
|
file that a browser exports (HTML) and makes a dashboard "Bookmarks" of it, with a card per
|
|
folder. An import adds dashboards and replaces nothing. Uploaded wallpapers and icons are
|
|
not part of an export.
|
|
- **Password**: Settings → Account changes it. That signs you out on your other devices.
|
|
- **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](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.
|