Node Management - StellarStack

Overview

Nodes are the physical or virtual servers that run the StellarStack daemon and host game server containers. Each node represents a machine in your infrastructure with allocated CPU, memory, and disk resources.

Multi-Node Support

Deploy game servers across multiple machines for scalability

Location-Based

Organize nodes by geographic location for low-latency gameplay

Health Monitoring

Real-time online/offline status with heartbeat latency tracking

Resource Allocation

Define CPU cores, memory (GB), and disk (GB) limits per node

Node Architecture

StellarStack uses a distributed architecture:

Panel: Central management web interface (this application)
Daemon: Rust-based daemon runs on each node, managing Docker containers
WebSocket: Real-time communication between panel and daemon
Token Authentication: Each node has a unique token for secure communication

┌─────────────┐
│ Panel (Web) │
└──────┬──────┘
       │ HTTP/WebSocket
       │
   ┌───┴────────┬────────────┬─────────────┐
   │            │            │             │
┌──▼──┐     ┌──▼──┐     ┌──▼──┐      ┌──▼──┐
│Node1│     │Node2│     │Node3│  ... │NodeN│
└─────┘     └─────┘     └─────┘      └─────┘
Daemon      Daemon      Daemon       Daemon

Creating a Node

Administrators can add nodes from Admin → Nodes → Add Node.

Required Information

Display Name

Friendly name shown in the panel (e.g., “US West Node 1”)

Host & Port

Host: IP address or domain where the daemon is accessible
Port: Daemon API port (default: 8080)
Protocol: HTTP, HTTPS, or HTTPS_PROXY

Resource Limits

CPU Cores: Number of physical/virtual cores (e.g., 4)
Memory: Total RAM in GB (e.g., 8)
Disk: Total storage in GB (e.g., 50)

These limits determine how many servers can be created on this node.

Network Configuration

SFTP Port: Port for SFTP file access (default: 2022)
Upload Limit: Maximum file upload size in MB (default: 100)

Location Assignment (Optional)

Associate the node with a geographic location for organization and display.

Node Credentials

After creating a node, you’ll receive:

Token ID: Unique identifier for the daemon
Token: Secret authentication token (base64url encoded)

The token is shown only once. Copy and save it immediately. You’ll need both the Token ID and Token to configure the daemon.

Daemon Configuration

On your node server, configure the daemon with the credentials:

# Example daemon configuration
TOKEN_ID="abc123-def456-ghi789"
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
API_PORT=8080
SFTP_PORT=2022

The daemon authenticates with the panel using:

Authorization: Bearer {token_id}.{token}

Node Status

Nodes display their current status in the panel:

Online
Offline

Daemon is connected and responding to heartbeats

Accepts new server deployments
Real-time stats available
Servers can start/stop

Heartbeat Monitoring

The panel continuously pings each node to check availability:

Heartbeat Interval: Every 30 seconds
Latency Display: Shows round-trip time in milliseconds
Auto-Status Update: Nodes marked offline if heartbeat fails

Resource Tracking

StellarStack tracks resource allocation across all servers on a node:

Available Resources

When creating a server, the panel checks:

// Example validation
usedMemory + newServerMemory <= nodeMemoryLimit
usedDisk + newServerDisk <= nodeDiskLimit
usedCpuCores + newServerCpuCores <= nodeCpuLimit

Overallocation Prevention

The panel prevents resource overcommitment:

Sum of all server allocations cannot exceed node limits
Admins cannot create servers if resources are exhausted
Clear error messages when resources are insufficient

Resource limits are hard limits. If a node has 8 GB RAM with 7 GB allocated to servers, you can only create servers with ≤1 GB RAM.

Locations

Organize nodes by geographic region using locations.

Creating Locations

Navigate to Admin → Locations → Add Location Required Fields:

Name: Location identifier (e.g., “US West”, “EU Central”)
Country: ISO country code or full name (optional)
City: City name (optional)
Description: Additional context (optional)

Assigning Nodes to Locations

When creating or editing a node, select a location from the dropdown. This:

Groups nodes in the UI for easier management
Displays location in server details (e.g., “Los Angeles, US”)
Helps users choose low-latency nodes for their region

Node Details

View comprehensive information about a node:

Basic Information

Display name
Connection URL (protocol://host:port)
Online/offline status
Heartbeat latency

Resource Overview

CPU: 4 cores
RAM: 8 GB
Disk: 50 GB
SFTP Port: 2022
Upload Limit: 100 MB

Assigned Servers

List of all servers hosted on this node with:

Server names
Resource allocations
Current status
Quick actions (view, stop, restart)

Allocations

IP:Port allocations available or assigned to servers on this node.

Editing Nodes

Administrators can modify node configuration:

Navigate to the node details page
Click Edit button
Update allowed fields:
- Display name
- Resource limits (CPU, memory, disk)
- SFTP port
- Upload limit
- Location assignment

You cannot change the host, port, or protocol after creation. Changing resource limits below current usage will fail.

Deleting Nodes

Remove a node from the panel:

Navigate to Admin → Nodes
Click Delete on the target node
Confirm the destructive action

Requirements:

Node must have no assigned servers
All allocations must be unassigned

Deleting a node from the panel does NOT uninstall the daemon. The daemon will continue running but won’t receive server deployments.

SFTP Access

Each node runs an SFTP server for file access:

Port: Configurable (default: 2022)
Authentication: Username format: {server_id}.{user_email}
Password: User’s account password
Chroot: Automatically jailed to /home/container per server

Connection Example

sftp -P 2022 [email protected]@node-host.com

The daemon handles:

User authentication via panel API
Permission validation
Automatic directory restriction to server files

Communication Protocols

HTTP/HTTPS API

The panel communicates with daemons via REST API: Endpoints:

POST /api/servers - Create server container
POST /api/servers/{id}/power - Power actions (start, stop, restart, kill)
POST /api/servers/{id}/install - Trigger installation
POST /api/servers/{id}/sync - Sync configuration changes
GET /api/servers/{id} - Fetch server state
DELETE /api/servers/{id} - Remove server container

WebSocket Connection

Real-time bidirectional communication: Panel → Daemon:

Console commands
Power actions
File operations

Daemon → Panel:

Console output stream
Resource statistics (CPU, memory, network)
Installation progress
State changes

Security

All daemon communication uses:

Token-based authentication: Bearer token with node ID
SSRF protection: Host validation prevents internal network access
TLS encryption: HTTPS protocol for production deployments
Request signing: Prevents token replay attacks

Best Practices

Use Multiple Nodes for Redundancy

Don’t put all servers on one node. Distribute across multiple nodes for:

High availability
Load balancing
Geographic distribution

Monitor Node Health

Regularly check:

Heartbeat latency (should be less than 50ms on local networks)
Resource utilization
Disk space availability

Group by Location

Create locations for each region:

US East, US West, EU, Asia
Helps users choose low-latency nodes
Organize billing by region

Set Realistic Resource Limits

Don’t set node limits to 100% of hardware:

Leave 10-20% headroom for OS overhead
Account for Docker daemon memory usage
Monitor actual resource consumption

Troubleshooting

Node Shows Offline

Check daemon service: Ensure daemon is running on the node
Verify network connectivity: Panel must reach node on configured port
Check firewall: Allow inbound traffic on daemon port (8080) and SFTP port (2022)
Validate token: Ensure daemon is using correct token ID and token
Review daemon logs: Check for authentication or connection errors

Cannot Create Server (Insufficient Resources)

Check resource usage: View total allocated vs. available on node
Increase node limits: Edit node to increase CPU/RAM/disk
Remove unused servers: Delete stopped servers to free resources
Deploy to different node: Choose a node with available capacity

SFTP Connection Fails

Verify SFTP port: Ensure port is open and daemon is listening
Check credentials: Format must be {server_id}.{user_email}
Confirm user password: SFTP uses panel account password
Review daemon logs: Check authentication errors
Test with verbose mode: sftp -v for detailed connection info

Overview

Getting Started

Core Features

User Management

Automation

Advanced

Deployment

​Overview

Multi-Node Support

Location-Based

Health Monitoring

Resource Allocation

​Node Architecture

​Creating a Node

​Required Information

​Node Credentials

​Daemon Configuration

​Node Status

​Heartbeat Monitoring

​Resource Tracking

​Available Resources

​Overallocation Prevention

​Locations

​Creating Locations

​Assigning Nodes to Locations

​Node Details

​Basic Information

​Resource Overview

​Assigned Servers

​Allocations

​Editing Nodes

​Deleting Nodes

​SFTP Access

​Connection Example

​Communication Protocols

​HTTP/HTTPS API

​WebSocket Connection

​Security

​Best Practices

​Troubleshooting

​Node Shows Offline

​Cannot Create Server (Insufficient Resources)

​SFTP Connection Fails

Build docs developers (and LLMs) love

Overview

Node Architecture

Creating a Node

Required Information

Node Credentials

Daemon Configuration

Node Status

Heartbeat Monitoring

Resource Tracking

Available Resources

Overallocation Prevention

Locations

Creating Locations

Assigning Nodes to Locations

Node Details

Basic Information

Resource Overview

Assigned Servers

Allocations

Editing Nodes

Deleting Nodes

SFTP Access

Connection Example

Communication Protocols

HTTP/HTTPS API

WebSocket Connection

Security

Best Practices

Troubleshooting

Node Shows Offline

Cannot Create Server (Insufficient Resources)

SFTP Connection Fails