arc-frp/node/DEPLOYMENT.md

Home Server Agent Deployment Guide

This guide will help you deploy the Home Server Agent on your home server with Docker.

Prerequisites

• Docker and Docker Compose installed on your home server
• At least 4GB of RAM (for running game servers)
• Open ports for the game servers you want to run
• Basic understanding of Docker and networking

Quick Deployment

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd home-server-agent

# Create environment configuration
cp .env.example .env

# Edit the .env file with your settings
nano .env

2. Configure Environment

Edit .env file:

# IMPORTANT: Change this to a secure token
API_TOKEN=your-very-secure-token-here

# Server configuration
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

# Docker socket (usually default)
DOCKER_HOST=unix:///var/run/docker.sock

# Game server settings (optional)
MINECRAFT_MEMORY=2G
VALHEIM_SERVER_NAME=Your Valheim Server
VALHEIM_WORLD_NAME=YourWorld
VALHEIM_SERVER_PASS=your-secure-password

3. Deploy with Docker Compose

# Start all services (agent + game servers)
docker-compose up -d

# Or start just the agent for testing
docker-compose -f docker-compose.dev.yml up -d

# Check status
docker-compose ps

Port Configuration

The following ports will be used:

Service	Port	Protocol	Purpose
Agent API	3000	TCP	REST API
Minecraft	25565	TCP	Minecraft server
Valheim	2456-2457	UDP	Valheim server
Terraria	7777	TCP	Terraria server
Portainer	9000	TCP	Docker management UI

Firewall Configuration

Ubuntu/Debian:

# Allow agent API
sudo ufw allow 3000/tcp

# Allow game server ports
sudo ufw allow 25565/tcp  # Minecraft
sudo ufw allow 2456:2457/udp  # Valheim
sudo ufw allow 7777/tcp  # Terraria

# Optional: Portainer
sudo ufw allow 9000/tcp

CentOS/RHEL:

# Allow agent API
sudo firewall-cmd --permanent --add-port=3000/tcp

# Allow game server ports
sudo firewall-cmd --permanent --add-port=25565/tcp
sudo firewall-cmd --permanent --add-port=2456-2457/udp
sudo firewall-cmd --permanent --add-port=7777/tcp

sudo firewall-cmd --reload

VPS Integration

To allow your VPS to control the home server agent:

1. Secure the API Token

Use a strong, unique API token:

# Generate a secure token
openssl rand -hex 32

# Or use UUID
uuidgen

2. VPS Configuration

On your VPS app, configure it to make requests to your home server:

// Example VPS integration
const HOME_SERVER_URL = 'https://your-home-server.com:3000';  // Use HTTPS in production
const API_TOKEN = 'your-secure-token-here';

// Start a game server from VPS
const startGameServer = async (serverName) => {
  const response = await fetch(`${HOME_SERVER_URL}/api/gameserver/start/${serverName}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.json();
};

3. Network Setup

Option A: Port Forwarding

• Forward port 3000 on your router to your home server
• Consider using a non-standard port for security

Option B: VPN/Tunnel

• Use a VPN to connect your VPS to your home network
• More secure but requires additional setup

Option C: Reverse Proxy

• Use nginx or Apache to proxy requests
• Can add SSL termination and additional security

SSL/HTTPS Setup

For production use, enable HTTPS:

Using nginx as reverse proxy:

# /etc/nginx/sites-available/home-server-agent
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/your/certificate.pem;
    ssl_certificate_key /path/to/your/private.key;
    
    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

Monitoring and Management

Docker Management with Portainer

# Enable Portainer
docker-compose --profile management up -d portainer

# Access at http://your-server:9000

Log Management

# View agent logs
docker-compose logs -f home-server-agent

# View specific game server logs
docker-compose logs -f minecraft

# View all logs
docker-compose logs -f

Health Monitoring

Set up monitoring with the included health check scripts:

# Linux health check
./health-check.sh health

# Windows health check
./health-check.ps1 -CheckType health

# Check specific game server
./health-check.sh gameserver minecraft

Automatic Updates

Enable Watchtower for automatic updates:

# Enable Watchtower
docker-compose --profile management up -d watchtower

# Or manually update
docker-compose pull
docker-compose up -d

Backup Strategy

Game Data Backup

# Backup game data volumes
docker run --rm -v minecraft-data:/data -v $(pwd):/backup ubuntu tar czf /backup/minecraft-backup.tar.gz /data

# Restore game data
docker run --rm -v minecraft-data:/data -v $(pwd):/backup ubuntu tar xzf /backup/minecraft-backup.tar.gz -C /

Configuration Backup

# Backup configuration
cp .env .env.backup
cp docker-compose.yml docker-compose.yml.backup

# Backup logs
tar czf logs-backup.tar.gz logs/

Security Checklist

• Changed default API token
• Configured firewall rules
• Enabled SSL/HTTPS (production)
• Restricted Docker socket access
• Set up log rotation
• Configured backup strategy
• Tested health monitoring
• Documented port assignments

Troubleshooting

Common Issues

1. Permission Denied (Docker Socket)

# Add user to docker group
sudo usermod -aG docker $USER

# Or adjust socket permissions
sudo chmod 666 /var/run/docker.sock

2. Port Already in Use

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

# Stop conflicting service
sudo systemctl stop <service-name>

3. Game Server Won't Start

# Check Docker logs
docker logs gameserver-minecraft

# Check system resources
docker system df
free -h

4. API Not Responding

# Check agent status
docker-compose ps

# Check agent logs
docker-compose logs home-server-agent

# Test local connectivity
curl http://localhost:3000/health

Log Analysis

# Follow all logs
docker-compose logs -f

# Search for errors
docker-compose logs | grep -i error

# Check specific timeframe
docker-compose logs --since=1h

Performance Optimization

Resource Limits

Add resource limits to docker-compose.yml:

services:
  minecraft:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2.0'
        reservations:
          memory: 1G
          cpus: '1.0'

System Requirements

Minimum:

• 2GB RAM
• 2 CPU cores
• 20GB storage

Recommended:

• 8GB RAM
• 4 CPU cores
• 100GB storage
• SSD storage for better performance

Production Checklist

Before deploying to production:

• Secure API token configured
• Firewall rules applied
• SSL/HTTPS enabled
• Monitoring configured
• Backup strategy implemented
• Resource limits set
• Documentation updated
• Testing completed
• Network security reviewed
• Access controls verified

Support

For issues:

1. Check the troubleshooting section
2. Review logs for error messages
3. Check Docker and system status
4. Verify network connectivity
5. Open an issue with detailed information