HHostingByteSoftware
Ctrl K
ComunidadGuías…

README.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
<div align="center">
  <img src="public/logo.svg" alt="NasDash logo" width="112" height="112" />
  <h1>NasDash</h1>
  <p><strong>A self-hosted cockpit for homelab services, infrastructure, Docker, telemetry, and network visibility.</strong></p>

  <p>
    <a href="https://nasdash.lucas-homelab.fr"><strong>Website</strong></a> ·
    <a href="https://demo.nasdash.lucas-homelab.fr"><strong>Live demo</strong></a> ·
    <a href="https://docs.nasdash.lucas-homelab.fr"><strong>Documentation</strong></a>
  </p>

  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-20c8e8" alt="MIT license" /></a>
    <img src="https://img.shields.io/badge/self--hosted-111827" alt="Self-hosted" />
    <img src="https://img.shields.io/badge/container-GHCR-111827" alt="Container on GHCR" />
  </p>

  <img src="docs/assets/screenshots/nasdash-demo-home.jpg" alt="NasDash home dashboard with isolated fictional demo data" width="1200" />
</div>

## Overview

NasDash brings services, machines, Docker, the network, media, downloads, music and photos into one calm, self-hosted dashboard. Each page is a free grid of widgets: 47 of them, from service categories and machine telemetry to Jellyfin, the *arr apps, DNS blocking, VPN and UPS.

Configuration stays on your own server in a persistent Docker volume or bind-mounted directory. A new installation starts private, asks for a setup code printed in the container log, and walks you through a short guide. Integrations are optional: the dashboard remains useful as a service cockpit while deeper infrastructure capabilities can be enabled deliberately.

## Product preview

Every service, address, metric, and log line below comes from NasDash's isolated public-demo profile, or from a throwaway new installation for the first-start screens. No personal installation or real infrastructure is connected during capture. Screenshots show NasDash **0.3.6**, captured on **29 October 2026**, with the English interface. [Capture provenance](docs/assets/screenshots/manifest.json) records the source revision, dimensions, and image hashes.

The demo has one page per part of a homelab:

| Media | Machines |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-media.jpg" alt="NasDash Media page with fictional films, series and photos" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-machines.jpg" alt="NasDash machine telemetry from fictional demo integrations" width="640" /> |

| Docker | Network |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-docker.jpg" alt="NasDash Docker details with fictional metrics, volumes, and logs" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-networks.jpg" alt="NasDash network page with DNS blocking, VPN and topology" width="640" /> |

| Downloads | Music |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-downloads.jpg" alt="NasDash downloads page with the *arr apps and download clients" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-music.jpg" alt="NasDash music page with fictional albums and playlists" width="640" /> |

First start: a setup code, then a short guide and a tour of the dashboard.

| Setup code | First-run guide |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-first-start-code.jpg" alt="NasDash sign-in screen asking for the setup code" width="640" /> | <img src="docs/assets/screenshots/nasdash-guide-appearance.jpg" alt="NasDash first-run guide, language and look step" width="640" /> |

| Page editor | Widget library |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-editor.jpg" alt="NasDash free-grid page editor with widget controls" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-library.jpg" alt="NasDash searchable widget library" width="640" /> |

Theme, wallpaper, and glass are first-class product surfaces, not a single default look:

| Appearance settings | Themes gallery |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-settings.jpg" alt="NasDash appearance settings with wallpaper, blur and veil" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-themes.jpg" alt="NasDash themes and icons gallery" width="640" /> |

<details>
<summary>More pages, themes, and mobile</summary>

| Services | Feeds |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-services.jpg" alt="NasDash services page with fictional categories and bookmarks" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-feeds.jpg" alt="NasDash feeds page with news, markets and the calendar" width="640" /> |

| GitHub Light | Apple Dark |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-home-github-light.jpg" alt="NasDash home dashboard in the GitHub Light theme" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-home-apple-dark.jpg" alt="NasDash home dashboard in the Apple Dark theme" width="640" /> |

| Dracula | Nord |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-home-dracula.jpg" alt="NasDash home dashboard in the Dracula theme" width="640" /> | <img src="docs/assets/screenshots/nasdash-demo-home-nord.jpg" alt="NasDash home dashboard in the Nord theme" width="640" /> |

| Cyberpunk | Dashboard tour |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-home-cyberpunk.jpg" alt="NasDash home dashboard in the Cyberpunk theme" width="640" /> | <img src="docs/assets/screenshots/nasdash-tour.jpg" alt="NasDash dashboard tour bubble" width="640" /> |

| Mobile home | Mobile Docker |
| --- | --- |
| <img src="docs/assets/screenshots/nasdash-demo-mobile-home.jpg" alt="NasDash responsive home dashboard" width="390" /> | <img src="docs/assets/screenshots/nasdash-demo-mobile-docker.jpg" alt="NasDash responsive Docker dashboard" width="390" /> |

</details>

## Highlights

- Service categories with local and secondary URLs, live availability for each address, and drag-and-drop ordering. Secondary-link bubbles follow the ping-details setting and close after navigation.
- Hardware metrics from Glances, Netdata, Beszel, Prometheus/node_exporter, Proxmox VE, and Libre Hardware Monitor. Separate CPU and GPU temperature readings when the source reports them, with independent widget presentation and alerts.
- Storage volumes grouped by host by default, with optional fullest-first or manual order. Reorder metric readings with handles in page edit mode, then save the page.
- Docker containers, logs, images, volumes, and guarded actions through Portainer, Dockhand, an optional socket proxy, or a Docker-compatible API/socket. Search, filter and sort resource lists, paginate them, inspect tags and linked containers, and confirm selected unused resources before removal. Page selection stays in the table header on desktop and mobile; usage counts sit beside Refresh.
- Network topology editor with groups, links, and service/device associations.
- Composable pages: every page is a free grid of widgets you can move, resize and add from a library, with ready-made official pages and appearance profiles.
- Custom API connections for JSON endpoints, fetched on the server with configurable authentication; widgets receive selected values while connection addresses and credentials stay private.
- Sonarr, Radarr and Lidarr calendars and queues, *arr health, Prowlarr indexers, and qBittorrent, Transmission, Deluge, SABnzbd and NZBGet download status. Administrators can pause or resume an item or a whole client; demo controls stay offline. *arr disk readings come from media root folders, with only folder names returned. Multiple saved sources share a widget; credentials stay on the server.
- Coming soon combines *arr calendars, library follow-ups, and public catalogue watchlists or discovery (TVMaze, Kitsu, optional AniList, and TMDB with a saved API key). Catalogue searches are administrator-only; public posters use allowlisted catalogue CDNs. It can follow series in a Jellyfin, Emby or Plex library through TVMaze: only provider IDs leave the server. Empty calendars show the next releases, empty queues show recent imports, downloads include available session totals and completions, and indexers include hourly search activity.
- Music widgets for Jellyfin, Emby, Plex and Subsonic-compatible servers (Navidrome, Gonic, Airsonic): current tracks and queues, added or played albums, playlists, search, library statistics and all-time top albums. Signed-in readers with Media access can play listed tracks through a private audio proxy; administrators can control compatible Jellyfin/Emby sessions. Subsonic track history is unavailable.
- Jellyfin, Emby and Plex connections for now playing, recent additions and library totals. Media artwork passes through NasDash; server links are administrator-only and account names follow each widget’s privacy setting.
- A complete English, French, Spanish, German, and Italian interface with an instance-wide server preference.
- Public or private access mode, local admin/viewer accounts, and viewer allowlists.
- Encrypted integration credentials, coordinated configuration writes with rollback on reported failures, and backup/restore tooling.

## Quick start

Photo library statistics can use Immich, PhotoPrism, Piwigo or LibrePhotos connections in Settings → Integrations → Photos. Add the photo statistics widget to a page; available figures depend on the provider and account permissions.

### Docker Compose

Requirements: Docker Engine with Compose `2.24.0` or newer and host port `2504`. Docker management is optional; choose an existing Portainer or Dockhand server, a restricted socket proxy, or a Docker-compatible API/socket. The optional local proxy requires a Linux Docker socket.

Create `docker-compose.yml`:

```yaml
services:
  nasdash:
    image: ghcr.io/lucas-lepajollec/nasdash:latest
    ports:
      - "2504:2504"
    env_file:
      - path: .env
        required: false
    volumes:
      - ./data:/app/data
    pid: host
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

  # Optional local engine connection: docker compose --profile docker-proxy up -d
  docker-proxy:
    profiles: ["docker-proxy"]
    image: tecnativa/docker-socket-proxy:v0.5.0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      VOLUMES: 1
      NETWORKS: 1
      INFO: 1
      POST: 1
      DELETE: 0
    restart: unless-stopped
```

Prepare the host data folder for the runtime user before starting. See [first-install and Synology guidance](https://docs.nasdash.lucas-homelab.fr/en/docs/getting-started/docker-installation) for `1001:1001`, a custom Compose `user`, and DSM folder permissions.

```bash
docker compose up -d
docker compose ps
docker compose logs nasdash
```

No `.env` is required. New accounts are initialized at server startup; generated passwords are printed once after their hashes are saved. Existing accounts are preserved across restart. Store account data and cryptographic keys in `./data`. An optional untracked `.env` can provide advanced overrides. Sign in, change the passwords, then open `http://<server-ip>:2504` from the LAN, or `http://localhost:2504` on the Docker host, and configure only the integrations you need. Portainer and Dockhand use their server URL, environment ID and dedicated API key/token; they need no socket proxy. To use the optional local proxy, run `docker compose --profile docker-proxy up -d` and add `http://docker-proxy:2375` as an HTTP API connection. The matching `2504:2504` ports are the Docker host port and container port. Prefer an authenticated HTTPS reverse proxy before leaving a trusted network.

Operational logs use English regardless of the interface language. New installations start in English with English example resource names. Names and content you customize remain yours: changing the interface language or upgrading does not rename existing machines, services or pages.

The `docker-proxy` profile is opt-in. On an existing installation using that service, keep its custom Compose configuration or enable the profile on every recreate; for example `docker compose --profile docker-proxy up -d`. Keep the existing data mount. `pid: host` shares host process visibility and can be removed when not needed; remote monitoring integrations do not require it.

The repository's default Compose file pulls the published image and stores data in `./data`. Do not replace that folder with a named volume on an existing installation: the app would start empty while the real files stay on disk. [`docker-compose.named-volume.yml`](docker-compose.named-volume.yml) is only an optional alternative for a brand-new install. To build the current checkout instead, add [`docker-compose.build.yml`](docker-compose.build.yml):

```bash
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
```

### Local development

```bash
git clone https://github.com/lucas-lepajollec/nasdash.git
cd nasdash
npm ci
cp .env.example .env
npm run dev
```

Development binds to `127.0.0.1:2499` by default. Use `npm run dev:lan` only when deliberately testing on a trusted network.

## Configuration and persistence

- The default `./data` folder contains configuration, users, password hashes, encryption material, and uploaded logos.
- Keep persisted keys and any existing `NASDASH_JWT_SECRET` configuration stable. Adding or changing an override can invalidate sessions and make saved integration credentials unreadable.
- Back up the entire data store before upgrades; never run `docker compose down -v` unless deleting all NasDash state is intentional.
- Before updating, record the current NasDash image digest and run the documented backup. Pull and recreate the stack, then verify `docker compose ps` and `/api/health`. Roll back by changing the `image:` line to the previous version or `sha-<full-commit>` tag and recreating without removing the data directory.
- Make `./data` writable by the actual runtime UID:GID (default `1001:1001`). Use [`docker-compose.named-volume.yml`](docker-compose.named-volume.yml) only when you deliberately want a named volume instead of a host folder.

See [backup procedures](https://docs.nasdash.lucas-homelab.fr/en/docs/operations/backup) for named-volume and bind-mount procedures, and [installation and permissions](https://docs.nasdash.lucas-homelab.fr/en/docs/getting-started/docker-installation) for permission diagnostics, and [first-start recovery](https://docs.nasdash.lucas-homelab.fr/en/docs/getting-started/first-start) for a lost password without deleting data. Startup initialization, permission checks and offline recovery are available in version 0.2.2 or later.

Share installation experiences and constructive feedback through [GitHub Issues](https://github.com/lucas-lepajollec/nasdash/issues/new/choose), using **User feedback**, **Bug report**, or **Feature request**. Remove initial passwords and other secrets from logs before posting.

## Security, privacy, and limitations

- Put NasDash behind HTTPS before access leaves a trusted network.
- Never expose an unauthenticated Docker socket or socket proxy to the internet.
- Treat `pid: host`, `CONTAINERS=1`, and Docker socket access as explicit high-risk integration exceptions. The optional proxy is not published and destructive deletion is disabled by default. Its `:ro` socket mount prevents replacing the socket file; it does not make Docker API access read-only.
- Keep destructive Docker capabilities disabled unless explicitly needed.
- A Docker host can also use a Unix socket mounted directly into the NasDash container (Docker `/var/run/docker.sock`, Podman `/run/podman/podman.sock`). That gives NasDash full control of the engine; a restricted socket proxy is one optional way to limit available endpoints. No direct socket mount is needed when using Portainer or Dockhand.
- Portainer and Dockhand Docker hosts use an API key or token: create a dedicated one, it is stored encrypted and never shown again.
- Service pings accept self-signed HTTPS certificates automatically (they carry no credentials and only check that the service answers).
- "Accept a self-signed certificate" (devices and Docker hosts) skips the HTTPS certificate check for that address only. Enable it only for your own servers, such as Proxmox's default certificate.
- Restrict remote Docker proxies to a private LAN or overlay address and firewall them to the NasDash host.
- Use a dedicated least-privilege Proxmox API token; a read-only role such as `PVEAuditor` is preferable.
- Never commit `.env` or a real runtime `data/` directory.
- Public demo controls and infrastructure data are fictional and isolated.

Read [access rules](https://docs.nasdash.lucas-homelab.fr/en/docs/guide/authentication-roles), [SECURITY.md](SECURITY.md), and the [integration troubleshooting guide](https://docs.nasdash.lucas-homelab.fr/en/docs/operations/troubleshooting) before exposing integrations.

## Architecture

| Layer | Technology |
| --- | --- |
| Application | Next.js, React, TypeScript |
| Persistence and auth | Local server-side data, encrypted credentials, JWT sessions |
| Integrations | Docker-compatible hosts, six monitoring sources, Tailscale/Headscale, ICS and weather |
| Deployment | Non-root Docker image and Docker Compose |

```text
src/app/          # Next.js pages and API routes
src/components/   # Dashboard, widgets, settings, and editors
src/lib/          # Persistence, auth, access, and page contracts
src/integrations/ # Shared connection manifests and monitoring adapters
src/widgets/      # Widget definitions and views
src/i18n/         # Five maintained interface languages
e2e/              # Isolated browser paths
scripts/          # Demo, tests, backup, restore, and smoke tooling
```

## Interface languages

English is the default interface. French, Spanish, German, and Italian are maintained alongside it, and the selected language is stored in the server configuration for the whole NasDash instance. The isolated public demo keeps changes temporary and can also receive an explicit `?lang=en`, `?lang=fr`, `?lang=es`, `?lang=de`, or `?lang=it` handoff.

New interface copy should use a semantic key in `src/i18n/messages.ts`. `src/i18n/generated.ts` is the reviewed migration dictionary for legacy French source phrases; keep its existing keys stable and update all five values together when correcting one of those messages. Use the locale exposed by `useI18n()` for dates, times, numbers, weather lookup, and other regional formatting. User-created names and content remain untouched when no maintained translation exists.

## Development and quality

| Command | Purpose |
| --- | --- |
| `npm run lint` | Run ESLint. |
| `npm run check:i18n` | Verify translation completeness, placeholders, and hard-coded interface copy. |
| `npm test` | Run the Vitest suite. |
| `npm run build` | Create the production build. |
| `npm run test:e2e` | Exercise isolated critical browser paths. |
| `npm run test:container` | Run the production-container smoke test. |
| `npm run demo:capture` | Regenerate the documented demo screenshots. |

See [TESTING.md](TESTING.md) and [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md) for the complete validation and capture workflows.

## Public demo

The [public demo](https://demo.nasdash.lucas-homelab.fr) uses deterministic fictional services, addresses, metrics, logs, and actions. Modifications are temporary and no private Docker host, Tailscale account, or personal infrastructure is reachable. See [demo mode](https://docs.nasdash.lucas-homelab.fr/en/docs/operations/demo-mode).

The public demo uses Vercel Web Analytics for visitor and page-view counts only when hosted on Vercel with `NASDASH_DEMO_MODE=true`. Analytics is disabled in normal self-hosted installations and local demo runs.

## Documentation and community

The dedicated documentation is the canonical home for installation, operation,
access control, demo mode and customization. This repository keeps the quick
start and contributor/maintainer contracts.

- [Documentation](https://docs.nasdash.lucas-homelab.fr)
- [Contributing guide](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [MIT License](LICENSE)