Network Access Guide - Admin Panel

Overview

The OneStack admin panel can now be accessed from any network location (including VPS, cloud servers, remote machines). This guide covers how to configure network access and important security considerations.

Configuration

Enable Network Access

Edit config.json and set the admin panel host to 0.0.0.0:

{
  "server": {
    "adminPanel": {
      "enabled": true,
      "port": 3000,
      "host": "0.0.0.0",
      "username": "admin",
      "password": "admin123"
    }
  }
}

Host Options

Host Value	Access Level	Use Case
`127.0.0.1`	Localhost only	Development on local machine
`0.0.0.0`	All network interfaces	Production VPS/cloud server
`192.168.1.100`	Specific network interface	Multi-homed servers

Port Options

Default: 3000
Alternative: Any unused port (1024-65535 recommended for non-root)
Production: Consider using reverse proxy with standard ports (80/443)

Accessing the Admin Panel

From Localhost (Same Machine)

http://localhost:3000

From Local Network

# Replace with your server's local IP
http://192.168.1.100:3000

From Internet (VPS/Cloud)

# Replace with your server's public IP
http://your-server-ip:3000

# Example
http://45.123.45.67:3000

With Domain Name

If you have a domain pointing to your server:

http://yourdomain.com:3000

🔒 CRITICAL Security Considerations

⚠️ WARNING: Public Access Risk

When setting host: "0.0.0.0", your admin panel is accessible from ANY IP address that can reach your server. This includes:

The entire internet (if on a VPS/cloud server)
Anyone on your local network
Potential attackers

Required Security Measures

1. Strong Credentials (MANDATORY)

DO NOT use default credentials in production!

{
  "adminPanel": {
    "username": "admin",          // ❌ WEAK - Change this!
    "password": "admin123"        // ❌ WEAK - Change this!
  }
}

Use strong credentials:

{
  "adminPanel": {
    "username": "secure_admin_user_2025",
    "password": "Xk9$mP2&vL8@qN4#wR6^tY1!"
  }
}

Password requirements:

Minimum 16 characters
Mix of uppercase, lowercase, numbers, symbols
No dictionary words
No personal information
Use a password manager to generate

2. Firewall Rules (RECOMMENDED)

Linux (UFW):

# Allow only specific IP to access admin panel
sudo ufw allow from YOUR_IP_ADDRESS to any port 3000

# Or allow specific IP range
sudo ufw allow from 192.168.1.0/24 to any port 3000

Linux (iptables):

# Allow specific IP
sudo iptables -A INPUT -p tcp -s YOUR_IP_ADDRESS --dport 3000 -j ACCEPT

# Block all others
sudo iptables -A INPUT -p tcp --dport 3000 -j DROP

Windows Firewall:

# Allow specific IP
New-NetFirewallRule -DisplayName "OneStack Admin" -Direction Inbound -LocalPort 3000 -Protocol TCP -RemoteAddress YOUR_IP_ADDRESS -Action Allow

Cloud Provider Firewalls:

AWS Security Groups: Add inbound rule for port 3000 from your IP
DigitalOcean Firewall: Create firewall rule limiting access
Azure NSG: Configure network security group rules
Google Cloud: Set up firewall rules in VPC

3. HTTPS/SSL (HIGHLY RECOMMENDED)

Running the admin panel over HTTP sends credentials in plain text. Use a reverse proxy with SSL:

Nginx Reverse Proxy with SSL:

server {
    listen 443 ssl;
    server_name admin.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/admin.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/admin.yourdomain.com/privkey.pem;

    # Strong SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }

    # WebSocket support
    location /ws {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name admin.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

Apache Reverse Proxy with SSL:

<VirtualHost *:443>
    ServerName admin.yourdomain.com

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/admin.yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/admin.yourdomain.com/privkey.pem

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://127.0.0.1:3000/$1" [P,L]
</VirtualHost>

Get Free SSL Certificates:

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate for nginx
sudo certbot --nginx -d admin.yourdomain.com

# Get certificate for apache
sudo certbot --apache -d admin.yourdomain.com

4. VPN Access (BEST PRACTICE)

Instead of exposing the admin panel to the internet, use a VPN:

WireGuard VPN Setup:

Install WireGuard on server
Configure VPN with your devices
Set admin panel to host: "10.0.0.1" (VPN interface IP)
Access admin panel only through VPN tunnel

Benefits:

Encrypted connection
No exposed ports
Multi-factor authentication via VPN
Better logging and access control

5. IP Whitelisting in Application

For additional security, you can modify the admin API to check allowed IPs:

Add to admin-api.js:

setupMiddleware() {
  // IP whitelist
  const allowedIPs = [
    '192.168.1.100',  // Your home IP
    '203.0.113.45',   // Your office IP
  ];

  this.app.use('/api', (req, res, next) => {
    const clientIP = req.ip || req.connection.remoteAddress;
    
    if (!allowedIPs.includes(clientIP)) {
      console.log(`[Security] Blocked access from ${clientIP}`);
      return res.status(403).json({ error: 'Access denied' });
    }
    
    next();
  });

  // ... rest of middleware
}

VPS/Cloud Setup Examples

DigitalOcean Droplet

Create droplet with Ubuntu 22.04
Install OneStack:

cd /opt
git clone https://github.com/yourusername/onestack.git
cd onestack
npm install

Configure for network access:

nano config.json
# Set "host": "0.0.0.0"
# Change username/password!

Setup firewall:

# Allow SSH
sudo ufw allow 22

# Allow admin panel from your IP only
sudo ufw allow from YOUR_IP to any port 3000

# Allow HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Enable firewall
sudo ufw enable

Run as service:

# Create systemd service
sudo nano /etc/systemd/system/onestack.service

[Unit]
Description=OneStack Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/onestack
ExecStart=/usr/bin/node main.js
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable onestack
sudo systemctl start onestack

Access admin panel:

http://your-droplet-ip:3000

AWS EC2

Launch EC2 instance
Configure Security Group:
- Add inbound rule: TCP port 3000 from your IP
- Add inbound rule: TCP port 80 from anywhere (0.0.0.0/0)
- Add inbound rule: TCP port 443 from anywhere (0.0.0.0/0)
Install and configure OneStack (same as DigitalOcean)
Optional: Use Elastic IP for consistent IP address
Access:

http://your-ec2-public-ip:3000

Azure VM

Create Virtual Machine
Configure Network Security Group:
- Add inbound port rule for 3000
- Limit source to your IP address range
Install OneStack (same steps)
Access via public IP:

http://your-vm-public-ip:3000

Connection Troubleshooting

Can't Connect from Network

Check 1: Server is listening on 0.0.0.0

# On server
netstat -tulpn | grep 3000
# Should show: 0.0.0.0:3000 or :::3000

Check 2: Firewall allows traffic

# Linux
sudo ufw status
sudo iptables -L -n

# Windows
Get-NetFirewallRule | Where-Object {$_.LocalPort -eq 3000}

Check 3: Cloud provider firewall

Check security groups (AWS)
Check firewall rules (GCP)
Check NSG (Azure)
Check firewall (DigitalOcean)

Check 4: Port is actually open

# From remote machine
telnet your-server-ip 3000
# Or
nc -zv your-server-ip 3000

WebSocket Connection Fails

Symptom: Panel loads but doesn't update in real-time

Fix 1: Ensure proxy supports WebSocket

# Nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

Fix 2: Check browser console for errors

Fix 3: Verify WebSocket port isn't blocked

Authentication Fails

Check: Credentials match config.json Check: Basic Auth header is being sent Check: No special characters breaking JSON parsing

Production Deployment Checklist

Security Best Practices Summary

✅ DO

Use host: "0.0.0.0" for network access
Set strong, unique credentials (16+ characters)
Use firewall rules to limit access
Implement HTTPS with valid SSL certificates
Use reverse proxy (Nginx/Apache) for SSL termination
Consider VPN for truly secure access
Monitor access logs regularly
Keep credentials in password manager
Use non-standard ports if needed
Enable automatic security updates
Test security regularly

❌ DON'T

Use default credentials (admin/admin123)
Expose admin panel without firewall rules
Use HTTP for admin panel over internet
Share credentials via unencrypted channels
Use weak passwords
Ignore security warnings in server logs
Leave unnecessary ports open
Forget to update SSL certificates
Use the same password across multiple services

Example Secure Configuration

{
  "server": {
    "name": "Production OneStack",
    "version": "1.0.0",
    "adminPanel": {
      "enabled": true,
      "port": 3000,
      "host": "127.0.0.1",
      "username": "secure_admin_x9k2p",
      "password": "Xk9$mP2&vL8@qN4#wR6^tY1!zQ3"
    }
  }
}

Notes:

host: "127.0.0.1" - Only accessible via localhost
Access remotely through Nginx reverse proxy with SSL
Nginx listens on 443 (HTTPS) with Let's Encrypt certificate
Firewall blocks direct access to port 3000
Strong credentials used
Additional IP-based restrictions in Nginx

Monitoring Access

Server Logs

OneStack logs all admin panel access:

[Admin API] POST /api/vhosts
[Admin API] GET /api/status
[Admin API] WebSocket client connected

Enhanced Logging

Add to admin-api.js for IP logging:

this.app.use((req, res, next) => {
  const ip = req.ip || req.connection.remoteAddress;
  console.log(`[Admin API] ${req.method} ${req.path} from ${ip}`);
  next();
});

Failed Login Attempts

Monitor for authentication failures:

// In setupMiddleware()
if (username !== config.server.adminPanel.username || 
    password !== config.server.adminPanel.password) {
  const ip = req.ip || req.connection.remoteAddress;
  console.log(`[Security] Failed login from ${ip}`);
  // Consider: Rate limiting, IP banning, alerts
  res.status(401).json({ error: 'Invalid credentials' });
}

Support

If you encounter issues with network access:

Check server logs for errors
Verify firewall configuration
Test from localhost first
Test from local network second
Test from internet last
Review this guide's troubleshooting section

Summary

Network access to the OneStack admin panel is now fully supported. By setting host: "0.0.0.0" in your configuration, you can manage your server from anywhere. However, security is critical when exposing the admin panel to the network. Follow the security best practices in this guide to protect your server.

Quick Start for VPS:

Set "host": "0.0.0.0" in config.json
Change default username/password
Configure firewall to allow port 3000 from your IP
Set up HTTPS with Nginx reverse proxy
Access from https://your-domain.com or https://your-ip:3000

FilesExpand file tree

NETWORK_ACCESS_GUIDE.md

Latest commit

History