nessi
d694c8b8e3
Add .env.example with configuration for database, Redis, security, SMTP, workers, and plugins. Add .gitignore for Python, Node.js, Next.js, Docker volumes, and IDE files. Add MIT License. Update README.md with feature overview, quick start guide, architecture description, plugin system documentation, security details, backup/restore instructions, and developer setup. Add Alembic configuration files and placeholder directories for API, web, worker, and plugin components
173 lines
4.2 KiB
Markdown
173 lines
4.2 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
|
|
```
|
|
|
|
## 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.
|