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)

Clone/download the files
Update the environment variables in docker-compose.yml with your RackNerd API credentials
Run:
```
docker-compose up -d
```

Using Docker

# 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

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

Add this to your Homepage services.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:

{
  "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

No data returned: Check API credentials and network connectivity
XML parsing errors: Verify API response format hasn't changed
Container won't start: Check environment variables and port conflicts
Homepage not updating: Verify URL and check service logs

Contributing

Feel free to submit issues and enhancement requests!

3.7 KiB Raw Blame History