Initial commit of Docker files

2025-08-18 00:26:57 +12:00
commit 05297cf246
29 changed files with 2517 additions and 0 deletions
--- a/racknerd-converter/README.md
+++ b/racknerd-converter/README.md
@@ -0,0 +1,152 @@
+# RackNerd KVM API Converter
+
+A Python Flask service that converts RackNerd KVM XML API responses to JSON format for Homepage widgets.
+
+## Features
+
+- Converts RackNerd XML API responses to clean JSON format
+- Caches data to reduce API calls (configurable interval, default 30 minutes)
+- RESTful API endpoints for Homepage integration
+- Docker containerized for easy deployment
+- Health checks and error handling
+- Automatic background data updates
+
+## API Endpoints
+
+- `GET /api/kvm` - Get cached KVM data in JSON format
+- `GET /api/kvm/raw` - Get fresh data (bypass cache)
+- `GET /api/kvm/status` - Service status and metadata
+- `GET /health` - Health check endpoint
+
+## Quick Start
+
+### Using Docker Compose (Recommended)
+
+1. Clone/download the files
+2. Update the environment variables in `docker-compose.yml` with your RackNerd API credentials
+3. Run:
+   ```bash
+   docker-compose up -d
+   ```
+
+### Using Docker
+
+```bash
+# Build the image
+docker build -t racknerd-api-converter .
+
+# Run the container
+docker run -d \
+  -p 5000:5000 \
+  -e RACKNERD_API_KEY=your_api_key \
+  -e RACKNERD_API_HASH=your_api_hash \
+  -e RACKNERD_VSERVER_ID=your_vserver_id \
+  -e UPDATE_INTERVAL=1800 \
+  --name racknerd-converter \
+  racknerd-api-converter
+```
+
+### Manual Python Setup
+
+```bash
+pip install -r requirements.txt
+export RACKNERD_API_KEY=your_api_key
+export RACKNERD_API_HASH=your_api_hash
+export RACKNERD_VSERVER_ID=your_vserver_id
+python app.py
+```
+
+## Configuration
+
+Configure via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RACKNERD_API_KEY` | Your RackNerd API key | A0ZJA-FSJXW-QXV7R |
+| `RACKNERD_API_HASH` | Your RackNerd API hash | fce545debdab0edf2565788277d3670e1afd8823 |
+| `RACKNERD_VSERVER_ID` | Your VServer ID | 476515 |
+| `RACKNERD_BASE_URL` | RackNerd API base URL | https://nerdvm.racknerd.com/api/client/command.php |
+| `UPDATE_INTERVAL` | Cache update interval (seconds) | 1800 (30 minutes) |
+| `HOST` | Server host | 0.0.0.0 |
+| `PORT` | Server port | 5000 |
+
+## Homepage Widget Configuration
+
+Add this to your Homepage `services.yaml`:
+
+```yaml
+- KVM Server:
+    icon: server
+    href: http://your-server:5000
+    ping: http://your-server:5000
+    widget:
+      type: customapi
+      url: http://your-server:5000/api/kvm
+      refreshInterval: 30000
+      mappings:
+        - field: hostname
+          label: Hostname
+        - field: status
+          label: Status
+        - field: uptime
+          label: Uptime
+        - field: cpu_usage
+          label: CPU Usage
+          suffix: "%"
+        - field: memory_usage
+          label: Memory
+          suffix: "%"
+```
+
+## API Response Format
+
+The service converts XML responses to JSON. Example response:
+
+```json
+{
+  "vserver": {
+    "hostname": "your-server",
+    "status": "online",
+    "uptime": "15 days",
+    "cpu_usage": 25.5,
+    "memory": {
+      "total": "4096MB",
+      "used": "2048MB",
+      "free": "2048MB"
+    },
+    "bandwidth": {
+      "used": "150GB",
+      "total": "1000GB"
+    }
+  },
+  "_metadata": {
+    "last_updated": "2024-01-15T10:30:00Z",
+    "source": "racknerd_api",
+    "vserver_id": "476515"
+  }
+}
+```
+
+## Monitoring
+
+- Check service health: `GET /health`
+- Monitor logs: `docker logs racknerd-api-converter`
+- Service status: `GET /api/kvm/status`
+
+## Security Notes
+
+- Keep your API credentials secure
+- Consider using Docker secrets for production
+- The service runs as a non-root user
+- Network access is limited to necessary ports
+
+## Troubleshooting
+
+1. **No data returned**: Check API credentials and network connectivity
+2. **XML parsing errors**: Verify API response format hasn't changed
+3. **Container won't start**: Check environment variables and port conflicts
+4. **Homepage not updating**: Verify URL and check service logs
+
+## Contributing
+
+Feel free to submit issues and enhancement requests!