52 lines
1.5 KiB
Markdown
52 lines
1.5 KiB
Markdown
# HexaHost GameCloud Node Agent
|
|
|
|
Go daemon that runs on each game node. It maintains an outbound connection to the control plane, reports heartbeats and resource metrics, and executes signed lifecycle commands for Minecraft server containers.
|
|
|
|
## Phase 0 scope
|
|
|
|
- Environment-based configuration loader
|
|
- Versioned JSON protocol message types (`agent.hello`, `agent.heartbeat`, `server.start`, …)
|
|
- Health endpoints (`/healthz`, `/readyz`)
|
|
- Main loop stub with graceful shutdown on `SIGINT`/`SIGTERM`
|
|
|
|
## Build
|
|
|
|
```bash
|
|
make build
|
|
make test
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `NODE_ID` | yes | Unique node identifier |
|
|
| `NODE_AGENT_PUBLIC_URL` | yes | Control plane WebSocket URL |
|
|
| `NODE_TOKEN` | no* | Enrollment token (*required in production) |
|
|
| `NODE_AGENT_HEALTH_ADDR` | no | Health listen address (default `:9100`) |
|
|
| `NODE_HEARTBEAT_INTERVAL` | no | Heartbeat interval (default `10s`) |
|
|
| `NODE_DATA_DIR` | no | Server data root (default `/var/lib/hexahost-gamecloud`) |
|
|
| `LOG_LEVEL` | no | Log level |
|
|
|
|
See repository root `.env.example` for the full variable list.
|
|
|
|
## Protocol
|
|
|
|
Messages use a common envelope:
|
|
|
|
```json
|
|
{
|
|
"protocolVersion": 1,
|
|
"messageId": "01...",
|
|
"type": "agent.heartbeat",
|
|
"timestamp": "2026-01-01T00:00:00Z",
|
|
"payload": {}
|
|
}
|
|
```
|
|
|
|
See `internal/protocol/messages.go` for all supported types.
|
|
|
|
## Deployment
|
|
|
|
Production deployment uses systemd. See `deploy/systemd/node-agent.service`.
|