Admin UI Documentation

The nself Admin UI provides a comprehensive web-based interface for managing your backend stack.

📊 Overview

The Admin UI is a React-based dashboard that offers:

Real-time service monitoring
Docker container management
Database query interface
Log viewing and analysis
Health checks and metrics
Backup management
Configuration editor

🚀 Quick Start

Enable Admin UI

# Enable with temporary password
nself admin enable

# Output:
# ✅ Admin UI enabled
# 📝 Temporary password: xY3mK9pL
# 🌐 URL: http://localhost:3021

Set Custom Password

# Set your own password
nself admin password MySecurePass123!

# Or generate a secure password
nself admin password --generate

Access Admin UI

# Open in default browser
nself admin open

# Or navigate manually to:
# http://localhost:3021

🔧 Configuration

Environment Variables

Add to your .env file:

# Admin UI Configuration
NSELF_ADMIN_ENABLED=true
NSELF_ADMIN_PORT=3021
NSELF_ADMIN_HOST=0.0.0.0

# Authentication
NSELF_ADMIN_AUTH_PROVIDER=basic
ADMIN_SECRET_KEY=your-secret-key-here
ADMIN_PASSWORD_HASH=generated-hash

# Session Settings
NSELF_ADMIN_SESSION_TIMEOUT=3600
NSELF_ADMIN_SESSION_SECURE=false

# Features
NSELF_ADMIN_ENABLE_LOGS=true
NSELF_ADMIN_ENABLE_EXEC=true
NSELF_ADMIN_ENABLE_BACKUPS=true
NSELF_ADMIN_ENABLE_METRICS=true

Authentication Providers

Basic Authentication (Default)

NSELF_ADMIN_AUTH_PROVIDER=basic
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=<bcrypt-hash>

JWT Authentication

NSELF_ADMIN_AUTH_PROVIDER=jwt
NSELF_ADMIN_JWT_SECRET=your-jwt-secret
NSELF_ADMIN_JWT_ISSUER=nself-admin

OAuth2 (Coming Soon)

NSELF_ADMIN_AUTH_PROVIDER=oauth2
NSELF_ADMIN_OAUTH_CLIENT_ID=your-client-id
NSELF_ADMIN_OAUTH_CLIENT_SECRET=your-secret
NSELF_ADMIN_OAUTH_PROVIDER=github

📱 Features

Dashboard

The main dashboard provides:

System Overview: CPU, memory, disk usage
Service Status: Health of all running services
Quick Actions: Start, stop, restart services
Recent Logs: Last 100 log entries
Alerts: System warnings and errors

Service Management

View Services

List all Docker containers
Real-time status updates
Resource usage per container
Network information
Volume mounts

Control Services

// Available actions
- Start/Stop/Restart
- Scale up/down
- View logs
- Execute commands
- Inspect configuration

Database Management

Query Interface

SQL editor with syntax highlighting
Query history
Export results (CSV, JSON)
Schema browser
Table previews

Database Operations

Create/Drop databases
Run migrations
Backup/Restore
View active connections
Performance metrics

Log Viewer

Features

Real-time log streaming
Multi-service log aggregation
Search and filter
Log level filtering
Export logs
Syntax highlighting

Filter Options

{
  service: ["postgres", "hasura", "auth"],
  level: ["error", "warn", "info"],
  timeRange: "last-1h",
  search: "connection refused"
}

Backup Management

Create Backups

One-click backup creation
Scheduled backups
Selective service backup
Compression options

Restore Operations

List available backups
Point-in-time recovery
Verify backup integrity
Restore to different environment

Configuration Editor

Edit Settings

Visual .env editor
Syntax validation
Change history
Rollback capability
Hot reload support

Service Configuration

Docker Compose editor
Nginx configuration
Service-specific configs
Template management

🎨 Customization

Themes

// themes/custom.js
export default {
  primary: '#007bff',
  secondary: '#6c757d',
  success: '#28a745',
  danger: '#dc3545',
  warning: '#ffc107',
  info: '#17a2b8',
  dark: '#343a40',
  light: '#f8f9fa'
}

Custom Widgets

// widgets/custom-metric.jsx
import { Widget } from '@nself/admin-ui';

export default function CustomMetric() {
  return (
    <Widget title="Custom Metric">
      {/* Your custom content */}
    </Widget>
  );
}

API Extensions

// api/custom-endpoint.js
export default {
  path: '/api/custom',
  method: 'GET',
  handler: async (req, res) => {
    // Custom logic
    res.json({ data: 'custom' });
  }
}

🔐 Security

Access Control

Role-Based Access

roles:
  admin:
    - all permissions
  developer:
    - view logs
    - restart services
    - query database
  viewer:
    - read-only access

IP Whitelisting

NSELF_ADMIN_IP_WHITELIST=127.0.0.1,192.168.1.0/24

2FA Support (Coming Soon)

NSELF_ADMIN_2FA_ENABLED=true
NSELF_ADMIN_2FA_PROVIDER=totp

Security Headers

# Automatically configured
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'

Audit Logging

# Enable audit logs
NSELF_ADMIN_AUDIT_ENABLED=true
NSELF_ADMIN_AUDIT_PATH=/var/log/nself/audit.log

# Log format
{
  "timestamp": "2024-09-09T10:30:00Z",
  "user": "admin",
  "action": "restart_service",
  "service": "postgres",
  "ip": "192.168.1.100",
  "result": "success"
}

🔌 API Reference

Authentication

# Login
POST /api/auth/login
{
  "username": "admin",
  "password": "password"
}

# Response
{
  "token": "jwt-token",
  "expires": 3600
}

Services

# List services
GET /api/services

# Get service details
GET /api/services/{name}

# Control service
POST /api/services/{name}/action
{
  "action": "restart"
}

Database

# Execute query
POST /api/database/query
{
  "sql": "SELECT * FROM users LIMIT 10"
}

# Get schema
GET /api/database/schema

Logs

# Stream logs
WS /api/logs/stream?service=postgres

# Get historical logs
GET /api/logs?service=postgres&lines=100

🛠️ Admin CLI Commands

Basic Commands

# Enable/disable admin UI
nself admin enable
nself admin disable

# Check status
nself admin status

# Set password
nself admin password [password]

# Reset to defaults
nself admin reset

# View logs
nself admin logs

# Open in browser
nself admin open

Advanced Commands

# Generate API token
nself admin token generate

# List active sessions
nself admin sessions list

# Revoke session
nself admin sessions revoke [session-id]

# Export configuration
nself admin export > admin-config.json

# Import configuration
nself admin import < admin-config.json

🐛 Troubleshooting

Cannot Access Admin UI

# Check if enabled
grep NSELF_ADMIN_ENABLED .env

# Check if running
nself status | grep admin

# Check logs
nself logs admin

# Restart admin service
nself restart admin

Authentication Issues

# Reset password
nself admin password --reset

# Clear sessions
nself admin sessions clear

# Regenerate secret key
nself admin secret --regenerate

Performance Issues

# Increase memory limit
NSELF_ADMIN_MEMORY_LIMIT=512M

# Enable caching
NSELF_ADMIN_CACHE_ENABLED=true

# Reduce log retention
NSELF_ADMIN_LOG_RETENTION=7d

📊 Monitoring Integration

Prometheus Metrics

# Exposed at /metrics
nself_admin_requests_total
nself_admin_response_time_seconds
nself_admin_active_sessions
nself_admin_api_errors_total

Grafana Dashboard

Import dashboard ID: 14842 or use the provided JSON:

cp admin/grafana-dashboard.json /var/lib/grafana/dashboards/

🚀 Production Deployment

SSL/TLS Setup

# Generate certificates
nself ssl

# Configure admin UI
NSELF_ADMIN_SSL_ENABLED=true
NSELF_ADMIN_SSL_CERT=/ssl/cert.pem
NSELF_ADMIN_SSL_KEY=/ssl/key.pem

Reverse Proxy

# Nginx configuration
location /admin {
    proxy_pass http://localhost:3100;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

High Availability

# Docker Swarm mode
services:
  admin:
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s

📚 Additional Resources

Need help? Check FAQ or create an issue