First

node/DEPLOYMENT.md

@@ -0,0 +1,380 @@
+# 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