ɳAdmin is the central web-based management interface for your entire ɳSelf deployment. It provides a unified dashboard to monitor, configure, and control all aspects of your Backend-as-a-Service infrastructure.

ɳAdmin is a powerful, extensible administration panel that acts as your command center for:

• Real-time service monitoring and health checks
• Configuration management across all services
• Database administration (PostgreSQL, Redis)
• Log viewing and analysis
• Performance metrics and resource usage
• Service orchestration and scaling
• User and permission management

• Service Dashboard - Real-time status of all running services
• Configuration Editor - Modify environment variables and settings
• Health Monitoring - Service health checks and uptime tracking
• Log Viewer - Centralized log access from all containers
• Quick Actions - Start/stop/restart services with one click
• Resource Metrics - CPU, memory, disk usage per service

• Database Management - Built-in query editor and table browser (replacing pgAdmin)
• User Management - Create and manage authentication users
• API Explorer - Test GraphQL and REST endpoints
• Backup Management - Schedule and manage database backups
• Migration Tools - Database migration and seed management
• Performance Profiler - Identify bottlenecks and optimize queries
• Alert Configuration - Set up monitoring alerts and notifications
• Template Manager - Install and manage custom service templates
• Security Auditor - Security scanning and compliance checks

Enable ɳAdmin in your .env file:

# ɳAdmin Configuration
NSELF_ADMIN_ENABLED=true
NSELF_ADMIN_PORT=3021
NSELF_ADMIN_ROUTE=admin.${BASE_DOMAIN}

# Optional: Authentication
NSELF_ADMIN_AUTH_ENABLED=true
NSELF_ADMIN_USERNAME=admin
NSELF_ADMIN_PASSWORD=secure-password-here

# Optional: Advanced Settings
NSELF_ADMIN_THEME=dark
NSELF_ADMIN_LANGUAGE=en
NSELF_ADMIN_TIMEZONE=UTC
NSELF_ADMIN_SESSION_TIMEOUT=3600

After enabling and starting ɳAdmin:

• URL: https://admin.local.nself.org
• Default credentials: admin / admin (change immediately)

• URL: https://admin.<your-domain>
• Requires authentication setup

ɳAdmin is built with:

• Frontend: React with TypeScript, Material-UI
• Backend: Node.js with Express
• Real-time: WebSocket connections for live updates
• Data Source: Direct Docker API and service APIs

ɳAdmin integrates with:

• Docker API - Container management and stats
• PostgreSQL - Direct database access
• Hasura - GraphQL schema introspection
• Prometheus - Metrics collection
• Loki - Log aggregation
• Redis - Cache and session inspection

• Quickly reset databases
• View real-time logs during debugging
• Modify environment variables without restarting
• Test API endpoints

• Monitor service health and uptime
• Track resource usage trends
• Set up alerts for critical issues
• View aggregated logs

• Run SQL queries
• View and modify data
• Manage database users and permissions
• Export/import data

• Scale services up/down
• Rolling updates and deployments
• Service dependency management
• Load balancing configuration

ɳAdmin implements multiple security layers:

• Authentication: JWT-based authentication
• Authorization: Role-based access control (RBAC)
• Encryption: All traffic over HTTPS
• Audit Logging: All actions logged with user attribution
• Session Management: Automatic timeout and refresh
• IP Whitelisting: Optional IP-based access control

1. Always change default credentials
2. Use strong passwords (minimum 16 characters)
3. Enable 2FA when available
4. Restrict access by IP in production
5. Regular security updates
6. Monitor audit logs

• Integrated: Part of nself ecosystem, not standalone
• Multi-service: Manages all services, not just PostgreSQL
• Lighter: Lower resource usage
• Unified Auth: Single sign-on with nself Auth

• Specialized: Tailored for nself deployments
• Simpler: Focused UI without Docker complexity
• Integrated Monitoring: Built-in Prometheus/Grafana integration
• nself-aware: Understands nself service relationships

• Modern UI: React-based responsive interface
• Multi-database: PostgreSQL, Redis, and more
• API Testing: Includes GraphQL/REST testing
• Real-time Updates: WebSocket-based live data

ɳAdmin supports custom themes:

// Custom theme example
{
  "primary": "#1976d2",
  "secondary": "#dc004e",
  "background": "#f5f5f5",
  "dark": true
}

Extend functionality with plugins:

// Plugin structure
{
  "name": "custom-monitor",
  "version": "1.0.0",
  "hooks": {
    "dashboard": "renderCustomWidget",
    "menu": "addCustomMenuItem"
  }
}

Add dashboard widgets for specific needs:

• Custom metrics displays
• Third-party service integration
• Business-specific KPIs
• Custom action buttons

ɳAdmin exposes its own API for automation:

# Get service status
GET /api/services/status

# Restart a service
POST /api/services/{name}/restart

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

# Get logs
GET /api/logs/{service}?lines=100

• Check NSELF_ADMIN_ENABLED=true in .env
• Verify port 3021 is not in use
• Check nginx routing configuration
• Ensure Docker socket is accessible

• Verify Docker network configuration
• Check service health endpoints
• Ensure proper environment variables
• Review firewall rules

• Reset admin password via CLI: nself admin reset-password
• Check JWT secret configuration
• Verify session timeout settings
• Clear browser cache and cookies

Manage ɳAdmin from the command line:

# Enable admin UI
nself admin enable

# Disable admin UI
nself admin disable

# Reset admin password
nself admin reset-password

# View admin logs
nself admin logs

# Check admin status
nself admin status

Added in v0.4.7

For ɳAdmin contributors or those who want to run the admin UI locally with hot-reload while connecting to Docker backend services, nself provides an "admin-dev" mode.

Admin-dev mode allows you to:

• Run ɳAdmin locally from source (e.g., ~/Sites/ɳAdmin)
• Get hot-reload and debugging capabilities
• Connect to all Docker services (Postgres, Hasura, Auth, etc.)
• Access via the same admin.local.nself.org URL

# Enable dev mode on port 3000
nself service admin dev enable 3000 ~/Sites/ɳAdmin

# Rebuild and restart to apply nginx routing changes
nself build && nself restart

# Start your local admin server
cd ~/Sites/ɳAdmin && npm run dev

# Access at https://admin.local.nself.org

When dev mode is enabled, these are added to your .env:

# Admin Development Mode (local dev server)
NSELF_ADMIN_DEV=true
NSELF_ADMIN_DEV_PORT=3000
NSELF_ADMIN_DEV_PATH=~/Sites/ɳAdmin  # Optional, for documentation

After enabling dev mode, get the required environment variables for your local admin:

nself service admin dev env

This outputs the environment variables to add to your local ɳAdmin/.env.local:

# Database (via Docker)
DATABASE_URL=postgres://postgres:password@localhost:5432/mydb

# Hasura (via Docker)
HASURA_GRAPHQL_ENDPOINT=http://localhost:8080/v1/graphql
HASURA_GRAPHQL_ADMIN_SECRET=your-hasura-secret

# Admin
ADMIN_SECRET_KEY=your-admin-secret
PROJECT_NAME=myproject
BASE_DOMAIN=local.nself.org
NODE_ENV=development

# Project path (your nself project)
PROJECT_PATH=/path/to/your/project
NSELF_PROJECT_PATH=/path/to/your/project

1. Nginx Routing: When NSELF_ADMIN_DEV=true, nginx routes admin.* to host.docker.internal:PORT instead of the Docker container
2. Container Skip: The ɳAdmin Docker container is not created during nself build
3. Backend Services: All other services (Postgres, Hasura, Auth, etc.) run normally in Docker
4. Network Access: Your local admin connects to Docker services via localhost ports

┌─────────────────────────────────────────────────────────────┐
│  Browser (https://admin.local.nself.org)                    │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Nginx (Docker)                                             │
│  Routes admin.* → host.docker.internal:3000                 │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Local ɳAdmin (localhost:3000)                         │
│  ~/Sites/ɳAdmin                                        │
│  npm run dev (hot-reload enabled)                           │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Docker Services                                            │
│  ┌─────────┐ ┌────────┐ ┌──────┐ ┌───────┐                 │
│  │Postgres │ │ Hasura │ │ Auth │ │ Redis │ ...             │
│  │ :5432   │ │ :8080  │ │:4000 │ │ :6379 │                 │
│  └─────────┘ └────────┘ └──────┘ └───────┘                 │
└─────────────────────────────────────────────────────────────┘

# Switch to dev mode (local server)
nself service admin dev enable 3000
nself build && nself restart

# Switch back to Docker mode
nself service admin dev disable
nself build && nself restart

• Ensure your local server is running on the configured port
• Check that Docker services are running: nself status
• Verify nginx rebuilt: nself build --force

• Verify Docker services are running: nself status
• Check ports are exposed: docker ps
• Ensure .env.local has correct connection strings

• The nginx config includes WebSocket upgrade headers for hot-reload
• If issues persist, restart nginx: docker restart <project>_nginx

• On Linux (non-Docker Desktop), nginx routes to 172.17.0.1:PORT instead of host.docker.internal
• This is automatically detected during build

• CPU: 0.25 cores minimum
• Memory: 256MB minimum, 512MB recommended
• Storage: 100MB for application, 1GB for logs/metrics
• Network: Low bandwidth, increases with monitoring

• Database query builder UI
• Advanced user management
• API documentation generator

• ML model management interface
• Kubernetes deployment support
• Multi-tenant administration

• Mobile app for monitoring
• AI-powered insights
• Automated optimization

• Services Overview
• Optional Services
• Monitoring Bundle
• Environment Configuration
• Troubleshooting