# 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!