dPanel Overview

This guide walks you through the core building blocks of dPanel – the web‑based control panel for managing servers and websites. We cover the user interface, authentication flow, authorization model, record storage, and background queues.

UI Layer

• Built with React and Tailwind CSS for a responsive experience.
• All pages are served as single‑page applications (SPA) via the /ui endpoint.
• UI components communicate with the backend through a RESTful API (/api/v1/*).
• State management is handled by Redux Toolkit, enabling predictable data flow.

// Example UI configuration (ui-config.json)
{
  "theme": "dark",
  "language": "en",
  "features": {
    "metrics": true,
    "logs": true
  }
}

Authentication

dPanel supports multiple authentication methods:

• Local accounts stored in the users table (bcrypt‑hashed passwords).
• OAuth2 providers (Google, GitHub) via the auth/oauth module.
• API tokens for programmatic access.

The login flow:

1. UI posts credentials to /api/v1/auth/login.
2. Backend validates and creates a JWT (signed with HS256).
3. JWT is stored in an HttpOnly cookie (dpanel_auth).

# Verify a JWT using the CLI tool
$ dpanel jwt verify <token>

Authorization

Authorization is role‑based (RBAC) and enforced on every API endpoint.

• Roles: admin, operator, viewer.
• Permissions are defined in config/roles.yml.
• The middleware checks the JWT’s role claim against the required permission.

# config/roles.yml
admin:
  - "*"
operator:
  - "server:read"
  - "site:create"
viewer:
  - "server:read"
  - "site:read"

Records (Data Storage)

All persistent data lives in a PostgreSQL database. Key tables include:

• users – authentication credentials and profile data.
• sites – website definitions, domains, and SSL settings.
• servers – physical/virtual server inventory.
• audit_log – immutable record of every privileged action.

The ORM layer uses Prisma, providing type‑safe queries and migrations.

Queues (Background Jobs)

Long‑running tasks (e.g., SSL certificate issuance, backup creation) are off‑loaded to a Redis‑backed queue managed by BullMQ.

• Jobs are enqueued via /api/v1/jobs/* endpoints.
• Workers run as separate Node.js processes (dpanel-worker).
• Job status can be queried from the UI under Tasks → Queue.

// Enqueue a site backup job
await queue.add('site-backup', { siteId: 42 }, { attempts: 3, backoff: 5000 });

Putting It All Together

1. User logs in → UI receives JWT.
2. UI requests data → JWT is validated, role checked.
3. API returns records from PostgreSQL.
4. Heavy operations are placed on the queue; workers process them and update the audit_log.
5. UI polls for job status and reflects progress.

By separating concerns—UI, auth, authz, records, and queues—dPanel remains modular, testable, and easy to extend.