First

node/README.md

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