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

```bash
# 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:

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:

```bash
# 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:

```javascript
// 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:

```nginx
# /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

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

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

### Log Management

```bash
# 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:

```bash
# 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:

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

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

## Backup Strategy

### Game Data Backup

```bash
# 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

```bash
# 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)**
```bash
# 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**
```bash
# 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**
```bash
# Check Docker logs
docker logs gameserver-minecraft

# Check system resources
docker system df
free -h
```

**4. API Not Responding**
```bash
# 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

```bash
# 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`:

```yaml
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