- TypeScript 95.7%
- JavaScript 3.7%
- CSS 0.5%
- Dockerfile 0.1%
| client | ||
| docs | ||
| server | ||
| .dockerignore | ||
| .gitignore | ||
| .woodpecker.yml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| nginx.conf | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| screenshot.png | ||
Personal Homepage
A customizable personal homepage with monitoring widgets and integrations for self-hosted services.
Full documentation: https://homepage.matthewweber.xyz/docs/
What it is
A dashboard for a home lab. Drag-and-drop widget layout, 30+ widgets covering media servers, feeds, monitoring, music, analytics and more, 50+ built-in themes, and configurable keybindings. React + TypeScript on the front, Node + Express + SQLite behind it, packaged for Docker.
Quick start
git clone https://codeberg.org/thelinuxcast/Homepage.git
cd Homepage
docker compose up -d
If you don't want to build this yourself you can use the image at ghcr.io/huntedraven7/homepage:latest
this builds weekly at the Blueprint repo on Github!
No configuration files to fill in. Everything — widget credentials included —
is configured in the UI and stored encrypted in data/.
Open the app, and the first-run screen will offer to set a dashboard password. Set one if the instance is reachable from anywhere but your own network.
Local development
npm install
npm run dev
Client on :3000, API on :3001.
Security in brief
- Dashboard password stored as a bcrypt hash; sessions are 7-day JWTs.
- Widget credentials (API keys, upstream passwords) are AES-256-GCM encrypted and never sent to the browser — the server attaches them to upstream requests itself.
- Backups contain your layout, not your credentials.
- Docker access goes through a filtering socket proxy rather than a raw socket mount.
See the security guide before exposing this to the internet.
Documentation
Everything — widget-by-widget configuration, theming, layout, keybindings, deployment — lives in the docs site:
| Getting started | Install and first run |
| Configuration | Settings, themes, header |
| Layout | Grid, sizing, tabbed widgets |
| Keybindings | Shortcuts and rebinding |
| Security | Auth, credential storage, exposure |
| Widgets | All widgets and their options |
| Docker | Deployment and upgrades |
To run the docs locally:
cd docs && npm install && npm run dev
Contributing
Adding a widget? Register it in client/src/components/widgets/registry.ts
(and defaultWidgets in client/src/App.tsx for fresh installs), add a config
form under client/src/components/settings/widget-forms/, and document it in
docs/widgets/ plus the overview table and sidebar. Credential fields are
encrypted automatically when their names end like one (apiKey,
immichApiToken, password, clientSecret, …) — see
server/src/config/secret-fields.ts. If the widget's server route uses a stored
credential, add the route to server/src/config/integrations.ts with the
fields it sends and the URL or account fields the credential is bound to; a
route that is not listed there gets no stored credentials.
License
See repository.
