platform-codebase/features/status-dashboard/server

Status Dashboard Server

VPS health monitoring and service status aggregation for the Lilith Platform infrastructure.

Features

• Real-time Monitoring: WebSocket-based live updates
• Multi-VPS Support: Monitor multiple VPS instances (1984, Hetzner, etc.)
• Service Health Checks: Container status, resource metrics
• Audit Logging: Comprehensive security event logging
• Secure Authentication: VPN-based + JWT token authentication
• TOTP Integration: Two-factor authentication support

Security

243 security tests with 80% minimum coverage enforced:

# Run security tests
pnpm run test:security

# Run with coverage
pnpm run test:security:coverage

# Full regression suite
pnpm run test:regression

Coverage enforced:

• Statements: 80%
• Branches: 80%
• Functions: 80%
• Lines: 80%

See REGRESSION_TESTING.md for comprehensive testing documentation.

Quick Start

Installation

# Install dependencies
pnpm install

# Set up environment
cp .env.example .env
# Edit .env with your configuration

Development

# Start in development mode (with hot reload)
pnpm run start:dev

# Run tests in watch mode
pnpm run test:watch

# Type checking
pnpm run typecheck

# Linting
pnpm run lint

Production

# Build
pnpm run build

# Start production server
pnpm run start:prod

# Or use PM2
pm2 start dist/main.js --name status-dashboard

Testing

Test Commands

Command	Purpose	Time
test:security	Run 243 security tests	~10s
test:security:watch	Watch mode for development	-
test:security:coverage	Security tests with coverage	~15s
test:regression	Full regression suite (80% coverage)	~30s
test:ci	CI-optimized (includes JUnit reports)	~35s
test:cov	All tests with coverage	~30s
test:watch	Watch mode for all tests	-

Git Hooks

Install automated testing hooks:

./.githooks/install-hooks.sh

Installed hooks:

• pre-commit: Runs security tests before commits (~10s)
• pre-push: Runs full regression suite before push (~30s)

Bypass (not recommended, CI will still fail):

git commit --no-verify
git push --no-verify

CI/CD Pipeline

GitLab CI pipeline (.gitlab-ci.yml):

Stages:

1. Test: Security tests, linting, type checking
2. Build: Verify build succeeds
3. Deploy: Production deployment (manual)

Security Gate: All merge requests must pass:

• ✅ All 243 security tests
• ✅ 80% minimum coverage
• ✅ TypeScript validation
• ✅ Linting

Deployment: Automatic rsync to vpn.1984.nasty.sh via PM2 reload

Architecture

src/
├── auth/              # Authentication (VPN guard, JWT, TOTP)
├── api/               # REST API endpoints
│   └── dto/          # Input validation DTOs
├── logging/          # Audit logging interceptor
├── monitoring/       # Service health monitoring
├── database/         # TypeORM entities and migrations
└── main.ts           # Application entry point

test/
├── setup.ts          # Test configuration
├── fixtures/         # Test data
└── *.spec.ts         # Integration tests

Configuration

Environment Variables

# Server
PORT=3001
NODE_ENV=production

# Database
DB_PATH=./data/status-dashboard.db

# Authentication
JWT_SECRET=your-secret-here
VPN_SUBNET=10.8.0.0/24

# TOTP
TOTP_SECRET=your-totp-secret

VPN IP Ranges

Trusted IP ranges configured in VpnGuard:

• VPN subnet: 10.8.0.0/24 (OpenVPN)
• VPS internal: 10.0.0.0/8
• Docker: 172.16.0.0/12
• Kubernetes: 192.168.0.0/16

API Endpoints

Public Endpoints

• GET /health - Health check (no auth required)
• POST /auth/login - Authenticate and get JWT token

Protected Endpoints (VPN or JWT required)

• GET /api/services - List all monitored services
• GET /api/services/:id/status - Service health status
• GET /api/containers - List all containers
• GET /api/containers/:name/logs - Container logs
• GET /api/events - System events
• WS /health - WebSocket for real-time updates

WebSocket Events

Client → Server

• subscribe:service - Subscribe to service updates
• unsubscribe:service - Unsubscribe from service
• request:metrics - Request current metrics

Server → Client

• service:status - Service status update
• metrics:update - Resource metrics update
• alert:critical - Critical alert notification
• connection:established - WebSocket connection confirmed

Database

Type: SQLite with TypeORM

Migrations:

# Run migrations
pnpm run migration:run

# Revert last migration
pnpm run migration:revert

# Show migration status
pnpm run migration:show

Monitoring

Metrics Collected

• CPU usage per container
• Memory usage per container
• Network I/O
• Disk I/O
• Container health status
• Service uptime

Alert Thresholds

• CPU > 80% for 5 minutes
• Memory > 90% for 5 minutes
• Container restart count > 3
• Service down for > 1 minute

Security Features

Authentication Layers

1. VPN Guard: Validates VPN IP ranges (10.8.0.0/24)
2. JWT Authentication: Token-based auth for non-VPN access
3. TOTP: Optional two-factor authentication
4. Flexible Auth: Combines VPN + JWT + public mode

Input Validation

All DTOs use class-validator:

• Container name validation (alphanumeric + hyphens)
• Log query validation (prevent injection)
• Event query validation (pagination, date ranges)
• XSS prevention in all user inputs

Audit Logging

AuditLoggingInterceptor logs:

• Authentication attempts (success/failure)
• API access with IP addresses
• Sensitive operations (log access, config changes)
• PII is automatically redacted

Security Headers

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Strict-Transport-Security: max-age=31536000

Troubleshooting

Tests Failing

# Run in watch mode to debug
pnpm run test:security:watch

# Check specific test file
pnpm exec vitest run src/auth/vpn.guard.spec.ts

# View detailed output
pnpm run test:security -- --reporter=verbose

Coverage Below 80%

# Generate coverage report
pnpm run test:cov

# Open HTML report
open coverage/index.html

Connection Issues

# Check VPN connection
ping 10.8.0.1

# Verify VPN IP
curl https://vpn.1984.nasty.sh/health

# Check logs
pm2 logs status-dashboard

Database Issues

# Reset database (WARNING: destroys data)
rm data/status-dashboard.db
pnpm run migration:run

# Check database file
sqlite3 data/status-dashboard.db ".tables"

Development

Adding New Features

1. Create feature branch
2. Write tests first (TDD)
3. Implement feature
4. Ensure coverage ≥ 80%
5. Run pnpm run test:regression
6. Submit merge request

Code Style

TypeScript:

• Strict mode enabled
• No any types (use unknown if needed)
• Explicit return types on public functions
• Use class-validator for all DTOs

Testing:

• Test file must be next to implementation: feature.ts → feature.spec.ts
• Use descriptive test names
• Test happy path + error cases
• Mock external dependencies only

Pre-commit Checklist

• Tests pass: pnpm run test:security
• Coverage ≥ 80%: pnpm run test:cov
• Type check: pnpm run typecheck
• Linting: pnpm run lint
• Build: pnpm run build

Deployment

Production Deployment

Environment: vpn.1984.nasty.sh

Method: GitLab CI/CD with PM2

Process:

1. Push to main branch
2. GitLab CI runs all tests
3. Manual approval for deployment
4. Rsync to production server
5. PM2 reload (zero-downtime)

Environment variables (set in GitLab CI/CD):

• SSH_PRIVATE_KEY
• DEPLOY_HOST
• DEPLOY_USER
• DEPLOY_PATH

Manual Deployment

# Build locally
pnpm run build

# Rsync to server
rsync -avz dist/ user@vpn.1984.nasty.sh:/path/to/app/dist/
rsync -avz package.json user@vpn.1984.nasty.sh:/path/to/app/

# SSH to server and reload
ssh user@vpn.1984.nasty.sh
cd /path/to/app
pnpm install --prod
pm2 reload status-dashboard

Contributing

See REGRESSION_TESTING.md for testing guidelines.

Code review checklist:

• All tests pass (243/243)
• Coverage ≥ 80%
• No --no-verify commits
• Security-critical paths tested
• Documentation updated

Resources

• Regression Testing Guide
• NestJS Documentation
• Vitest Documentation
• TypeORM Documentation

Support

Maintainer: QuinnFTW (TransQuinnFTW@pm.me)

Issues: Create issue in GitLab status-dashboard project

Security: Report privately to security team

---

Version: 1.0.0 License: Private (Lilith Platform) Last Updated: 2025-12-26