App Dashboard

Architecture

The project is composed of two sub-projects, managed as GitHub submodules:

1. settings-dashboard
   Path: ./settings-dashboard/
   Documentation: settings-dashboard readme

2. dashboard-core
   Path: ./dashboard-core/
   Documentation: dashboard-core readme

Getting Started

Installation

Install project dependencies:

pnpm install

Configuration

Configure the following environment variables by referring to their respective documentation:

1. Core Configuration
   Path: ./settings-dashboard/config/core.env.json
   Documentation: core.env.json documentation

Development

Option 1: Standard Development Server

Start the development server:

pnpm start

Option 2: Docker Environment (Recommended)

Use Docker to simulate a PCS (Personal Cloud Server) environment, which is closer to the real deployment environment. This simulates a state just after a PCS has been created (with .env and os-init.sh executed).

cd dev/run
cp .env.example .env
# edit .env — fill in UID, USER_JWT, DEFAULT_PWD, PROVIDER_STR, EMAIL
docker compose up -d --build

Open https://admin-dev.localhost/ once the stack is healthy. See dev/run/README.md for service architecture, the one-time Caddy CA trust step, and troubleshooting.

Notes:

• Authentication is delegated to Authelia via OIDC (auto-registered with mesh-router-auth). The dashboard mints its own short-lived app JWT after a successful OIDC callback.
• For a clean reset, docker compose down -v from dev/run/.

Public Health Endpoint

GET /api/health is unauthenticated and returns a small JSON snapshot from RAM only — no shell, no SSH, no file I/O on call. It exists so the Yundera control plane can poll each PCS roughly once a day to confirm the deployed version and that the last self-check did not report failures.

GET /api/health

{
  "version": "0.1.0",
  "selfCheck": {
    "ok": true,
    "lastRunAt": "2026-04-29T03:00:12"
  },
  "lastRefreshedAt": "2026-04-29T03:05:00.000Z"
}

• selfCheck.ok — true on success, false on failures, null if no completion line has been observed yet.
• selfCheck.lastRunAt — host-local timestamp from the self-check log (no timezone).
• lastRefreshedAt — UTC timestamp of the last successful cache refresh.

The cache is owned by settings-dashboard/src/backend/server/Health/Health.ts and refreshed every 5 minutes by tailing /DATA/AppData/casaos/apps/yundera/log/yundera.log over SSH.

Deployment

Build and publish using Dockflow:

npx dockflow build
npx dockflow publish

Project Structure

./
├── settings-dashboard/          # Main dashboard application
│   ├── config/
│   │   ├── core.env.json
│   └── readme.md
├── dashboard-core/              # Core functionality
│   └── readme.md
└── README.md*