132 lines
6.8 KiB
Markdown
132 lines
6.8 KiB
Markdown
# DockDeck-Public
|
|
|
|
DockDeck is a self-hosted start dashboard for Unraid and other home-server environments. It combines application shortcuts, favorites, server health, weather, and optional read-only service widgets in one responsive interface.
|
|
|
|
|
|
|
|
## What you get
|
|
|
|
- Automatic application discovery through AppOps or the optional read-only Docker socket proxy
|
|
- Search, favorites, categories, personal-project filtering, layout presets, and custom wallpapers
|
|
- Responsive desktop, tablet, and mobile layouts with light and dark themes
|
|
- Unraid array, host, UPS, CPU, memory, and temperature information from read-only sources
|
|
- Optional widgets for services such as Plex, Jellyfin, Gitea, Home Assistant, Grafana, Nextcloud, and the Arr stack
|
|
- Server-side storage for integration credentials; exports intentionally exclude credentials
|
|
- Optional built-in HTTP Basic authentication for trusted-LAN use
|
|
|
|
DockDeck never needs the Docker socket in its normal AppOps profile. The fallback proxy profile exposes only the Docker GET endpoints used for inventory and status.
|
|
|
|
## Quick start
|
|
|
|
Requirements: Docker with Compose v2, or Node.js 22 with npm **11.16.0** for development. The pinned npm version is required by the nested dependency overrides in the lockfile; Docker builds install it automatically.
|
|
|
|
1. Clone the repository and copy `.env.example` to `.env`:
|
|
|
|
```sh
|
|
git clone https://gitea.itworx.tech/Jens/DockDeck-Public.git
|
|
cd DockDeck-Public
|
|
cp .env.example .env
|
|
```
|
|
|
|
On Windows PowerShell, use `Copy-Item .env.example .env` for the last command.
|
|
|
|
2. Generate an operator password hash (this host-side helper requires Node.js 22 or newer, including when the application itself runs in Docker):
|
|
|
|
```sh
|
|
node scripts/hash-operator-password.mjs
|
|
```
|
|
|
|
The prompt does not echo the password. Put the generated value in `DOCKDECK_OPERATOR_PASSWORD_HASH` and choose `DOCKDECK_OPERATOR_USER`.
|
|
|
|
3. Start DockDeck:
|
|
|
|
```sh
|
|
docker compose up -d --build
|
|
```
|
|
|
|
4. Open `http://127.0.0.1:1218`.
|
|
|
|
The default port publication is loopback-only. To make DockDeck reachable on a trusted LAN, set `DOCKDECK_BIND_ADDRESS` to the intended host address and keep operator authentication enabled. Use an authenticated HTTPS reverse proxy for access beyond that LAN; HTTP Basic credentials must not cross an untrusted plaintext connection.
|
|
|
|
## Build your first dashboard
|
|
|
|
Start with a few application links and favourites, then arrange their groups before adding integrations. Connect one read-only provider at a time and check its reported availability. A working shortcut only proves that a link exists; it does not establish application health.
|
|
|
|
Keep connector credentials on the server. If an integration fails, check its endpoint, permissions and trusted TLS configuration before granting broader access. Back up the SQLite state and the integration-secret file together when you use persisted connectors.
|
|
|
|
## Discovery profiles
|
|
|
|
The recommended profile points `APPOPS_URL` at a read-only AppOps inventory endpoint. No Docker socket is mounted.
|
|
|
|
If AppOps is unavailable, use the isolated socket-proxy override:
|
|
|
|
```sh
|
|
docker compose -f docker-compose.yml -f docker-compose.socket-proxy.yml up -d --build
|
|
```
|
|
|
|
DockDeck performs GET requests for Docker inventory, host information, and one-shot statistics. Nginx Proxy Manager uses a POST only to obtain its session token; resource discovery remains read-only.
|
|
|
|
## Configure DockDeck
|
|
|
|
Open Settings to:
|
|
|
|
- organize apps and mark personal projects;
|
|
- create favorites and layout presets;
|
|
- configure the Unraid server identity and polling interval;
|
|
- add provider URLs and least-privilege credentials;
|
|
- export or import non-secret dashboard configuration.
|
|
|
|
When a provider URL changes to another origin, DockDeck clears any omitted stored credentials and requires them to be supplied again. Redirects on credential-bearing integration requests are rejected.
|
|
|
|
Integration values entered in Settings are stored in `INTEGRATION_ENV_PATH` with owner-only permissions where the platform supports them. Back up that file and the SQLite database as secrets. JSON exports do not include integration credentials, but they can still reveal service names and topology.
|
|
|
|
## Unraid
|
|
|
|
An example Community Applications template is available at `deploy/dockdeck-unraid-template.xml`. It uses `/data/integrations.env` for persistent integration settings and requires an operator username and generated password hash. Replace the example AppOps and Unraid hostnames with values for your environment.
|
|
|
|
Raw Unraid DockerMan XML frequently contains private hosts and service names. Run `deploy/sanitize-unraid-templates.py` before mounting template metadata, and still review the resulting `Name`, `WebUI`, and `Icon` values before sharing them.
|
|
|
|
|
|
|
|
The screenshots show deterministic mock discovery, not a live server inventory. The interface currently uses Dutch labels.
|
|
|
|
## Optional browser extension
|
|
|
|
`browser-extension/dockdeck-new-tab` contains a Manifest V3 extension that opens DockDeck for new tabs. Load it as an unpacked extension, then set your DockDeck HTTP(S) URL on its Options page. The public source contains no operator-specific address.
|
|
|
|
## Development and verification
|
|
|
|
```sh
|
|
npm install --global npm@11.16.0
|
|
npm ci
|
|
npm run dev
|
|
```
|
|
|
|
Before contributing, run:
|
|
|
|
```sh
|
|
npm run format:check
|
|
npm run lint
|
|
npm run typecheck
|
|
npm test
|
|
npm run test:security
|
|
npm run test:e2e
|
|
npm run build
|
|
npm audit --audit-level=moderate
|
|
docker compose config --quiet
|
|
```
|
|
|
|
See `CONTRIBUTING.md`, `SECURITY.md`, and `docs/ARCHITECTURE.md` for contribution, disclosure, and design guidance.
|
|
|
|
## Security boundary
|
|
|
|
DockDeck is an operator dashboard, not a multi-tenant authorization system. Keep it on loopback or a trusted LAN, enable built-in authentication when it is network-reachable, use HTTPS at an external reverse proxy, and give every integration the narrowest read scope available. `/api/health` intentionally remains unauthenticated and returns only health state, not credentials.
|
|
|
|
## License
|
|
|
|
No open-source license has been selected yet. Until a license file is added, the source is publicly viewable but normal copyright restrictions remain in effect.
|
|
|
|
## Public source distribution
|
|
|
|
The private canonical repository remains the development source. Reviewed snapshots are synchronized automatically to `DockDeck-Public` after changes reach its default branch. The public export contains application source, dependency locks, generic deployment examples and selected demo visuals; private Git history, infrastructure workflows and operational records are excluded. `PUBLIC_SOURCE_MANIFEST.json` identifies the exact source revision and file hashes.
|