Server Infrastructure & Orchestration Architecture

Adjust monthly community donations, bare-metal node size, and the idle hibernation overcommit ratio below to see how many Mumble Voice Servers (32 MB avg) and Game Servers (3.5 GB avg) Trash Panda Hosting can sustain under each architecture.

Any platform offering free compute is an immediate target for crypto-miners (XMRig disguised as java), outbound UDP reflection/DDoS scripts, zip/disk bombs, and noisy-neighbor CPU starvation. Trash Panda Hosting enforces four kernel-level guardrails on every node:

By defining this single interface in backend/internal/orchestrator/orchestrator.go, Trash Panda Hosting's HTTP handlers, sqlc PostgreSQL queries, and Angular Control Panel remain 100% decoupled from whether the underlying node runs raccoond, HashiCorp Nomad, or Kubernetes + Agones:

package orchestrator

import (
	"context"
	"io"
	"time"
)

// ServerSpec defines the desired resource and network allocation on a target bare-metal node.
type ServerSpec struct {
	ServerID           string            `json:"serverId"`
	NodeID             string            `json:"nodeId"`
	Kind               string            `json:"kind"`               // "game" | "voice"
	Template           string            `json:"template"`           // "minecraft-paper", "valheim", "mumble", etc.
	Image              string            `json:"image"`              // OCI image or binary target
	HostIP             string            `json:"hostIp"`
	Port               int               `json:"port"`               // Shared TCP+UDP primary port
	MemoryMB           int               `json:"memoryMb"`           // Hard cgroups v2 memory.max
	CPUMillicores      int               `json:"cpuMillicores"`      // e.g. 2000 = 2.0 cores
	DiskQuotaMB        int               `json:"diskQuotaMb"`        // ZFS/Btrfs subvolume refquota
	MaxPlayers         int               `json:"maxPlayers"`
	HibernationEnabled bool              `json:"hibernationEnabled"` // Enables 15m 0-player Wake-on-Packet proxy
	Env                map[string]string `json:"env"`
}

// RuntimeStatus reports live telemetry from the node agent back to the Go Control Plane.
type RuntimeStatus struct {
	State          string    `json:"state"`          // "running" | "stopped" | "hibernating" | "provisioning"
	CurrentPlayers int       `json:"currentPlayers"` // Sampled via SLP / A2S_INFO / Murmur RPC
	MemoryUsedMB   int       `json:"memoryUsedMb"`
	CPUPercent     float64   `json:"cpuPercent"`
	DiskUsedMB     int       `json:"diskUsedMb"`
	LastActiveAt   time.Time `json:"lastActiveAt"`
}

// NodeOrchestrator abstracts raccoond (mTLS gRPC), HashiCorp Nomad (HTTP API), and Kubernetes (Agones CRD).
type NodeOrchestrator interface {
	// ProvisionServer creates the ZFS/Btrfs quota volume, pulls the image, and starts or registers the server.
	ProvisionServer(ctx context.Context, spec ServerSpec) (*RuntimeStatus, error)

	// StartServer wakes a hibernating or stopped server and hands the host UDP/TCP port to the container.
	StartServer(ctx context.Context, nodeID, serverID string) (*RuntimeStatus, error)

	// StopServer sends a graceful save command (RCON/SIGTERM) and stops the container without binding the wake proxy.
	StopServer(ctx context.Context, nodeID, serverID string) (*RuntimeStatus, error)

	// HibernateServer stops the container, snapshots the disk, and binds raccoond's UDP/TCP Wake-on-Packet listener.
	HibernateServer(ctx context.Context, nodeID, serverID string, port int) (*RuntimeStatus, error)

	// DeprovisionServer removes the container, unbinds ports, and destroys the ZFS/Btrfs subvolume.
	DeprovisionServer(ctx context.Context, nodeID, serverID string) error

	// StreamConsole attaches to live stdout/stderr and accepts RCON/stdin commands for the Angular panel.
	StreamConsole(ctx context.Context, nodeID, serverID string, stdin io.Reader) (io.ReadCloser, error)
}

// Driver implementations selectable per-node via Node.Orchestrator ("raccoond" | "nomad" | "agones-k8s"):
//   - RaccoonDaemonDriver: mTLS gRPC client to raccoond on :9443 (Default for Phase 1–2)
//   - NomadDriver:         Nomad HTTP v1 Jobs API client (docker + raw exec task drivers)
//   - AgonesK8sDriver:     client-go dynamic client managing agones.dev/v1 GameServer CRDs