Homelab/Services/racknerd-converter

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:

   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

Homepage Widget Configuration

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

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!