OneStack - Complete All-in-One Server Platform

🚀 Overview

OneStack is a comprehensive, modular server platform built with Node.js that provides HTTP/HTTPS hosting, DNS services, email server, SSH access, and a powerful REST API with 50+ endpoints for extensions. It features a modern admin panel and dynamic module system for unlimited extensibility.

🎉 NEW: Complete REST API + Dynamic Module Loading + Extension System

✨ Features

Core Services

• 🌐 HTTP/HTTPS Server - Virtual host management with statistics
• 🔍 DNS Server - Full DNS zone and record management
• 📧 Email Server - SMTP/IMAP with complete mailbox management
• 🔑 SSH Server - Secure shell access
• 📊 Admin Panel - Modern, dark-themed web UI

Developer Features (NEW!)

• 🔧 REST API - 50+ endpoints for complete programmatic control
• 🔌 Dynamic Modules - Auto-discovery and hot-loading of custom modules
• 📡 WebSocket API - Real-time updates and event streaming
• 🛠️ Module SDK - Complete framework for building extensions
• 📚 Comprehensive Docs - 6 detailed guides (3500+ lines total)
  • API_DOCUMENTATION.md - Complete REST API reference
  • MODULE_DEVELOPMENT.md - Module development guide
  • EXTENSION_GUIDE.md - Extension system overview
  • EMAIL_GUIDE.md - Email system documentation
  • EMAIL_IMPLEMENTATION.md - Email architecture
  • QUICKSTART.md - Testing guide

Architecture

Modular Design

Each protocol is implemented as a separate module that extends the BaseModule class. Modules run independently and can create their own child threads for additional processing.

Threading Model

• Each module runs in the main process but can spawn:
  • Worker Threads - For CPU-intensive operations
  • Custom Threads - For background tasks like monitoring, cleanup, and processing

Module Structure

modules/
├── base_module.js   - Base class with common functionality
├── http.js          - HTTP server implementation
├── https.js         - HTTPS server implementation
├── dns.js           - DNS server implementation
├── email.js         - Email (SMTP/IMAP) implementation
└── ssh.js           - SSH server implementation

Quick Start

1. Installation

npm install

2. Start the Server

npm start

3. Access Admin Panel

Open your browser and navigate to:

http://localhost:3000

Default Credentials:

• Username: admin
• Password: admin123

⚠️ Change these credentials in config.json before deploying to production!

Configuration

File-Based Configuration

Configuration is stored in config.json. The file is automatically created with defaults on first run.

Example configuration structure:

{
  "server": {
    "name": "OneStack Server",
    "version": "1.0.0",
    "adminPanel": {
      "enabled": true,
      "port": 3000,
      "username": "admin",
      "password": "admin123"
    }
  },
  "modules": {
    "http": {
      "enabled": true,
      "port": 8080,
      "host": "0.0.0.0",
      "monitoring": {
        "enabled": true,
        "interval": 30000
      }
    },
    "dns": {
      "enabled": true,
      "port": 5353,
      "records": {
        "localhost.local": {
          "type": "A",
          "ttl": 300,
          "data": "127.0.0.1"
        }
      }
    }
    // ... more modules
  }
}

Environment Variables

You can override configuration values using environment variables:

# Admin Panel
ADMIN_PORT=3000
ADMIN_USERNAME=admin
ADMIN_PASSWORD=secretpassword

# Module Ports
HTTP_PORT=8080
HTTPS_PORT=8443
DNS_PORT=5353
SMTP_PORT=2525
IMAP_PORT=1143
SSH_PORT=2222

# Enable/Disable Modules
HTTP_ENABLED=true
DNS_ENABLED=false

Example:

ADMIN_PORT=8000 HTTP_PORT=9090 npm start

Default Ports

Service	Default Port	Privileged Port	Notes
Admin Panel	3000	N/A	Web interface
HTTP	8080	80	Use non-privileged by default
HTTPS	8443	443	Use non-privileged by default
DNS	5353	53	Port 53 requires admin/root
SMTP	2525	25	Port 25 requires admin/root
IMAP	1143	143	Standard port is 143
SSH	2222	22	Port 22 requires admin/root

💡 Tip: Default configuration uses non-privileged ports (>1024) to avoid requiring administrator/root access.

Accessing Services

HTTP

# Using browser
http://localhost:8080

# Using curl
curl http://localhost:8080
curl http://localhost:8080/status
curl http://localhost:8080/health

DNS

# Query DNS server (using dig on Linux/Mac or nslookup on Windows)
nslookup onestack.local 127.0.0.1

Built-in DNS records:

• localhost.local → 127.0.0.1
• onestack.local → 127.0.0.1
• www.onestack.local → onestack.local (CNAME)

Email (SMTP)

# Send test email using telnet
telnet localhost 25
HELO localhost
MAIL FROM:<sender@example.com>
RCPT TO:<recipient@example.com>
DATA
Subject: Test
This is a test email.
.
QUIT

SSH

# Connect to SSH server
ssh admin@localhost -p 22
# Password: admin (demo only!)

# Available commands in SSH shell:
# - help
# - status
# - uptime
# - whoami
# - exit

Admin Panel Features

Dashboard

• Real-time server statistics
• Module status overview
• Quick actions for common tasks
• Live connection status

Modules Management

• Start/Stop/Reload individual modules
• View module configuration
• Monitor worker threads
• Real-time status updates via WebSocket

Configuration Editor

• Visual JSON editor
• Real-time validation
• Save/Reload/Reset options
• Export/Import configuration
• Syntax highlighting

Logs

• Real-time log viewer
• WebSocket-based updates
• Filterable log entries

REST API

The admin panel exposes a REST API for programmatic control:

Authentication

All API endpoints require Basic Authentication:

const auth = 'Basic ' + btoa('admin:admin123');
fetch('/api/status', {
  headers: { 'Authorization': auth }
});

Endpoints

Server Status

GET /api/status

Returns server uptime, memory usage, and module status.

Get Configuration

GET /api/config

Returns current configuration.

Update Configuration

PUT /api/config
Content-Type: application/json

{
  "modules": {
    "http": {
      "port": 8090
    }
  }
}

Module Operations

POST /api/modules/:name/start
POST /api/modules/:name/stop
POST /api/modules/:name/reload
GET  /api/modules/:name/status
GET  /api/modules/:name/config
PUT  /api/modules/:name/config

Configuration Management

GET  /api/config/export        # Download config as JSON
POST /api/config/import        # Import configuration
POST /api/config/reload        # Reload from file
POST /api/config/reset         # Reset to defaults

Example: Update HTTP Port

curl -X PUT http://localhost:3000/api/config \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{"modules":{"http":{"port":9090}}}'

WebSocket API

Real-time updates are available via WebSocket at ws://localhost:3000

Message Types

// Connection established
{ "type": "connected", "data": { "timestamp": "..." } }

// Status update (every 5 seconds)
{ "type": "status", "data": { ...serverStatus } }

// Configuration updated
{ "type": "configUpdated", "data": { ...newConfig } }

// Module events
{ "type": "moduleStarted", "data": { "module": "http" } }
{ "type": "moduleStopped", "data": { "module": "dns" } }

Using Configuration Files

Edit Configuration

1. Via Admin Panel: Navigate to the Configuration tab
2. Via File: Edit config.json directly
3. Via API: Use PUT /api/config

Reload Configuration

After editing config.json:

# Option 1: Via API
curl -X POST http://localhost:3000/api/config/reload -u admin:admin123

# Option 2: Via Admin Panel
# Click "Reload Config" button in Dashboard

# Option 3: Restart server

Reset to Defaults

curl -X POST http://localhost:3000/api/config/reset -u admin:admin123

Export Configuration

curl http://localhost:3000/api/config/export -u admin:admin123 > backup.json

Import Configuration

curl -X POST http://localhost:3000/api/config/import \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d @backup.json

Module Development

Creating a New Module

1. Create a new file in modules/ directory
2. Extend the BaseModule class
3. Implement start() and stop() methods
4. Add module to main.js

Example:

const BaseModule = require('./base_module');

class MyProtocolModule extends BaseModule {
  constructor(config) {
    super('MyProtocol', config);
  }

  async start() {
    await super.start();
    // Initialize your server here
    
    // Create a worker thread if needed
    this.createCustomThread(this.backgroundTask, { interval: 10000 });
  }

  async backgroundTask(thread, data) {
    while (thread.running) {
      await new Promise(resolve => setTimeout(resolve, data.interval));
      // Do background work
    }
  }

  async stop() {
    // Clean up resources
    await super.stop();
  }
}

module.exports = MyProtocolModule;

BaseModule API

• createWorkerThread(workerFile, workerData) - Create a worker thread
• createCustomThread(threadFunction, data) - Create a custom async thread
• stopThread(threadId) - Stop a specific thread
• log(message) - Emit a log message
• error(error) - Emit an error
• getStatus() - Get module status

Module Configuration Options

HTTP Module

{
  "enabled": true,
  "port": 8080,
  "host": "0.0.0.0",
  "monitoring": {
    "enabled": true,
    "interval": 30000
  },
  "routes": {
    "enableDefaultRoutes": true
  }
}

DNS Module

{
  "enabled": true,
  "port": 5353,
  "host": "0.0.0.0",
  "records": {
    "example.local": {
      "type": "A",
      "ttl": 300,
      "data": "192.168.1.100"
    }
  },
  "cacheCleanup": {
    "enabled": true,
    "interval": 60000
  }
}

Email Module

{
  "enabled": true,
  "smtp": {
    "enabled": true,
    "port": 2525,
    "host": "0.0.0.0"
  },
  "imap": {
    "enabled": true,
    "port": 1143,
    "host": "0.0.0.0"
  },
  "processing": {
    "enabled": true,
    "interval": 5000
  }
}

SSH Module

{
  "enabled": true,
  "port": 2222,
  "host": "0.0.0.0",
  "authentication": {
    "users": [
      {
        "username": "admin",
        "password": "admin",
        "allowPasswordAuth": true,
        "allowPublicKeyAuth": true
      }
    ]
  },
  "monitoring": {
    "enabled": true,
    "interval": 30000
  }
}

Security Notes

⚠️ This is a demonstration project. Do NOT use in production without implementing proper security measures:

• Change default credentials in config.json
• Use HTTPS for the admin panel in production
• Implement rate limiting for API endpoints
• Use proper SSL certificates for HTTPS module
• Implement proper authentication for SSH (key-based recommended)
• Add input validation and sanitization
• Enable firewall rules to restrict access
• Use environment variables for sensitive credentials
• Regular security updates of all dependencies

Recommended Production Setup

1. Change Admin Credentials:

{
  "server": {
    "adminPanel": {
      "username": "your-secure-username",
      "password": "your-very-secure-password"
    }
  }
}

2. Use Environment Variables:

export ADMIN_USERNAME=secure_user
export ADMIN_PASSWORD=complex_password_here
npm start

3. Restrict Access:

• Bind admin panel to localhost only
• Use reverse proxy (nginx/Apache) with HTTPS
• Implement IP whitelisting
• Use VPN for remote access

Dependencies

• ssh2 - SSH server implementation
• nodemailer - Email utilities
• dns-packet - DNS protocol implementation

License

MIT

Contributing

Feel free to submit issues and enhancement requests!