NexaDash

NexaDash is a modern, self-hosted, plugin-based dashboard for Homelab, server and infrastructure services. It connects to Proxmox, AdGuard Home, Jellyfin, Home Assistant, authentik, Beszel and many more through a secure, extensible plugin system — all configurable from the web UI, no CLI required.

Features

• Plugin-based architecture: Add services as plugins via the UI or ZIP upload.
• Modern UI: Next.js, Tailwind CSS, shadcn/ui, dark mode first, glassmorphism design.
• Secure by default: Argon2id, JWT sessions, RBAC, encrypted secrets, audit log, SSRF protection, security headers.
• Dashboard editor: Drag & drop, resize, multiple breakpoints, favorites, folders, import/export.
• Multi-user: Owner, Admin, Editor, Viewer roles with permission system.
• Background workers: Celery for plugin syncs and scheduled jobs.
• Live updates: WebSocket/SSE support and auto-refresh.
• Mail settings: SMTP configuration via UI for invitations and password resets.
• Backup/restore: Database dumps and restore documentation included.

Quick Start

Requires Docker and Docker Compose.

# 1. Clone the repository
git clone https://github.com/nexadash/nexadash.git
cd nexadash

# 2. Configure environment
cp .env.example .env
# Edit .env and set strong passwords

# 3. Start the stack
docker compose up -d

# 4. Open the UI
open http://localhost:3000

The initial setup wizard appears on first launch. Create the owner account, then add services from the plugin registry.

Architecture

nexadash/
  apps/
    web/          Next.js frontend
    api/          FastAPI backend
    worker/       Celery background worker
  packages/
    plugin-sdk/   TypeScript SDK for plugin developers
    shared/       Shared types and constants
    ui/           shadcn/ui component library
  plugins/        Built-in plugin manifests
  docs/           Documentation
  docker/         Dockerfiles
  compose.yaml
  .env.example

Plugin System

NexaDash plugins are declarative packages consisting of:

• plugin.manifest.json — metadata, schemas, widgets, permissions.
• Backend connector — either a built-in connector or a registered Python class.
• Optional frontend widget components.

Plugins are installed, activated, configured and updated entirely from the web UI. Built-in plugins include:

• Proxmox VE
• Proxmox Backup Server
• AdGuard Home
• Zoraxy
• Jellyfin
• Home Assistant
• authentik
• Beszel
• Generic HTTP

See docs/plugins/README.md for the full developer guide.

Security

• Passwords hashed with Argon2id.
• JWT access + refresh tokens in HTTP-only cookies.
• Service credentials encrypted at rest with Fernet.
• RBAC with Owner/Admin/Editor/Viewer.
• Audit log for all critical actions.
• SSRF protection for outbound service URLs.
• Rate limiting and account lockout.
• Security headers on all API responses.
• No secrets exposed to the frontend.

See docs/security/README.md for details.

Backup and Restore

# Backup
docker compose exec postgres pg_dump -U nexadash nexadash > nexadash-backup.sql

# Restore
docker compose exec -T postgres psql -U nexadash nexadash < nexadash-backup.sql

Important volumes: postgres_data, redis_data, plugin_data.

Update

git pull
docker compose build
docker compose up -d
docker compose exec api alembic upgrade head

PostgreSQL 18 Upgrade Note

The bundled Docker Compose stack uses PostgreSQL 18.4. PostgreSQL 18 changed the official Docker image data directory, so existing PostgreSQL 16/17 deployments should be backed up before upgrading and restored into the new container:

docker compose exec postgres pg_dump -U nexadash nexadash > nexadash-backup.sql
docker compose down
docker volume rm nexadash_postgres_data
docker compose up -d postgres
docker compose exec -T postgres psql -U nexadash nexadash < nexadash-backup.sql
docker compose up -d

Developer Setup

Backend

# Python 3.12+
python -m venv .venv
. .venv/bin/activate
pip install poetry
poetry install

# Run migrations
alembic upgrade head

# Start API
python -m uvicorn apps.api.src.main:app --reload

# Start worker (separate terminal)
celery -A apps.worker.src.celery_app worker -l info

Frontend

# Node 20+, pnpm 9+
pnpm install
pnpm dev

Testing

# Backend
pytest

# Frontend
pnpm test

Roadmap

• Public plugin marketplace.
• Additional widget types (charts, maps, logs).
• Webhook-triggered plugin actions.
• OIDC/SAML authentication.
• Mobile app.

Contributing

Contributions are welcome. Please follow the existing code style, add tests for new features and update the documentation.

License

MIT License — see LICENSE.

Support

For questions and issues, open a GitHub issue or discussion.