153 lines
3.7 KiB
Markdown
153 lines
3.7 KiB
Markdown
# 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 | |
|
|
| `RACKNERD_API_HASH` | Your RackNerd API hash | |
|
|
| `RACKNERD_VSERVER_ID` | Your VServer ID | |
|
|
| `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!
|