# 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.

![DockDeck dashboard](docs/design/dockdeck-canon-v1/implementation/dashboard-dark-desktop-1440x900.png)

## 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:

   ```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.

## 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.

![DockDeck responsive dashboard](docs/design/dockdeck-canon-v1/implementation/dashboard-dark-mobile-390x844.png)

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.