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)

Setup Steps:

1. Configure the development environment
   Configure dev-env according to dev/run/dev-env.example

2. Start the Docker environment
   Ensure Docker is running, then execute:

   .\dev\run-simple.ps1

Important Notes:

• Clean Installation: The run-simple script automatically cleans Docker volumes for fresh testing
• Yundera stack: this process will create a non-functional Yundera stack that can be ignored
• Authentication: Sign-in 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.

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*