nessi
dfec7976c4
Add ALLOWED_HOSTS configuration to restrict trusted hosts in TrustedHostMiddleware. Enhance SSRF protection to block all private, loopback, link-local, multicast, reserved, and unspecified IP addresses using ipaddress module and DNS resolution checks. Add encrypt_value/decrypt_value aliases for encryption functions. Upgrade PostgreSQL from 16 to 18.4 in Docker Compose with updated data directory path (/var/lib/postgresql). Add security_opt no
188 lines
4.7 KiB
Markdown
188 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Node 20+, pnpm 9+
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# 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.
|