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