arc-frp/node

node

Home Server Agent

A lightweight Node.js agent for managing game servers on your home server through Docker containers. This agent provides a secure REST API to start, stop, and monitor game servers remotely.

Features

• 🎮 Game Server Management: Start, stop, and monitor popular game servers (Minecraft, Valheim, Terraria)
• 🐳 Docker Integration: Leverages Docker for containerized game server deployment
• 🔒 Security: Token-based authentication for API access
• 📊 Monitoring: Real-time status monitoring and system statistics
• 🌐 REST API: Clean RESTful API for remote management
• 📝 Logging: Comprehensive logging with Winston
• 🔄 Auto-restart: Containers automatically restart on failure
• 💾 Data Persistence: Game data persisted in Docker volumes

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ (for development)
• Bun (optional, for development)

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd home-server-agent
   

2. Install dependencies

   bun install
   # or
   npm install
   

3. Set up environment

   cp .env.example .env
   # Edit .env with your configuration
   

4. Start development server

   bun run dev
   # or
   npm run dev
   

Production Deployment

1. Build and start with Docker Compose

   docker-compose up -d
   

2. Or start with just the agent for testing

   docker-compose -f docker-compose.dev.yml up -d
   

API Endpoints

Authentication

All API endpoints (except /health) require authentication via Bearer token or X-API-Key header:

# Using Bearer token
curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3000/api/status

# Using API key header
curl -H "X-API-Key: your-secret-token-here" http://localhost:3000/api/status

Available Endpoints

Endpoint	Method	Description
/health	GET	Health check (no auth required)
/api/status	GET	Get overall server status
/api/status/ports	GET	Get active ports and services
/api/gameserver/list	GET	List all available game servers
/api/gameserver/start/:serviceName	POST	Start a game server
/api/gameserver/stop/:serviceName	POST	Stop a game server
/api/gameserver/restart/:serviceName	POST	Restart a game server
/api/gameserver/:serviceName/status	GET	Get specific server status

Example Usage

# Get server status
curl -H "Authorization: Bearer your-secret-token-here" \
  http://localhost:3000/api/status

# Start Minecraft server
curl -X POST -H "Authorization: Bearer your-secret-token-here" \
  http://localhost:3000/api/gameserver/start/minecraft

# Stop Minecraft server
curl -X POST -H "Authorization: Bearer your-secret-token-here" \
  http://localhost:3000/api/gameserver/stop/minecraft

# Get Minecraft server status
curl -H "Authorization: Bearer your-secret-token-here" \
  http://localhost:3000/api/gameserver/minecraft/status

Supported Game Servers

Minecraft

• Image: itzg/minecraft-server:latest
• Default Port: 25565
• Features: Vanilla Minecraft server with configurable settings

Valheim

• Image: lloesche/valheim-server:latest
• Default Ports: 2456-2457 (UDP)
• Features: Dedicated Valheim server with world persistence

Terraria

• Image: ryshe/terraria:latest
• Default Port: 7777
• Features: Terraria server with world management

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	3000
NODE_ENV	Environment mode	development
API_TOKEN	Authentication token	Required
LOG_LEVEL	Logging level	info
DOCKER_HOST	Docker socket path	unix:///var/run/docker.sock

Game Server Configuration

Game servers can be configured by modifying the environment variables in docker-compose.yml:

minecraft:
  environment:
    EULA: "TRUE"
    TYPE: "VANILLA"
    MEMORY: "2G"
    DIFFICULTY: "normal"
    MAX_PLAYERS: "20"

Security

• Authentication: All API endpoints require token authentication
• Docker Security: Containers run as non-root users where possible
• Network Isolation: Services run in isolated Docker networks
• Read-only Docker Socket: Docker socket is mounted read-only for security

Monitoring

The agent provides comprehensive monitoring capabilities:

• System Stats: Docker version, container counts, resource usage
• Port Monitoring: Active ports and their associated services
• Container Status: Real-time container health and uptime
• Logs: Structured logging with Winston

Development

Project Structure

src/
├── index.ts              # Main application entry point
├── middleware/
│   └── auth.ts          # Authentication middleware
├── routes/
│   ├── status.ts        # Status and monitoring routes
│   └── gameServer.ts    # Game server management routes
├── services/
│   └── dockerManager.ts # Docker container management
└── utils/
    └── logger.ts        # Logging configuration

Scripts

# Development
bun run dev          # Start development server with hot reload
bun run build        # Build the application
bun run start        # Start production server

# Docker
bun run docker:build # Build Docker image
bun run docker:run   # Run with Docker Compose

Docker Volumes

The following volumes are used for data persistence:

• minecraft-data: Minecraft world data and configuration
• valheim-data: Valheim world data and configuration
• terraria-data: Terraria world data and configuration
• ./logs: Application logs (mounted from host)

Optional Services

The Docker Compose file includes optional management services:

Portainer (Docker Management UI)

docker-compose --profile management up -d portainer

Access at: http://localhost:9000

Watchtower (Auto-updates)

docker-compose --profile management up -d watchtower

Troubleshooting

Common Issues

1. Permission Denied (Docker Socket)

   # Ensure Docker socket has proper permissions
   sudo chmod 666 /var/run/docker.sock
   

2. Port Already in Use

   # Check what's using the port
   netstat -tlnp | grep :3000
   

3. Container Start Failures

   # Check container logs
   docker logs gameserver-minecraft
   

Logs

Application logs are available in:

• ./logs/combined.log - All logs
• ./logs/error.log - Error logs only
• Console output (development mode)

License

This project is licensed under the MIT License.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the logs for error messages
3. Open an issue on GitHub with detailed informationall dependencies:

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.2.6. Bun is a fast all-in-one JavaScript runtime.