arc-frp/node/README.md

# 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**
   ```bash
   git clone <repository-url>
   cd home-server-agent
   ```

2. **Install dependencies**
   ```bash
   bun install
   # or
   npm install
   ```

3. **Set up environment**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. **Start development server**
   ```bash
   bun run dev
   # or
   npm run dev
   ```

### Production Deployment

1. **Build and start with Docker Compose**
   ```bash
   docker-compose up -d
   ```

2. **Or start with just the agent for testing**
   ```bash
   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:

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

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

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

```bash
# 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)
```bash
docker-compose --profile management up -d portainer
```
Access at: http://localhost:9000

### Watchtower (Auto-updates)
```bash
docker-compose --profile management up -d watchtower
```

## Troubleshooting

### Common Issues

1. **Permission Denied (Docker Socket)**
   ```bash
   # Ensure Docker socket has proper permissions
   sudo chmod 666 /var/run/docker.sock
   ```

2. **Port Already in Use**
   ```bash
   # Check what's using the port
   netstat -tlnp | grep :3000
   ```

3. **Container Start Failures**
   ```bash
   # 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:

```bash
bun install
```

To run:

```bash
bun run index.ts
```

This project was created using `bun init` in bun v1.2.6. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.