Operations

Operations

Hot Reload

Nvelox reloads its configuration without dropping active connections. The reload flow:

  1. Receive SIGHUP signal (or admin API reload request)
  2. Read and parse the new config file
  3. Validate the config — on failure, keep the old config and log an error
  4. Atomically swap to the new config
  5. Existing connections continue on the old config until they close
Trigger hot reload 
# Via signal
kill -HUP $(pidof nvelox)

# Via systemd
sudo systemctl reload nvelox

Admin API

The admin API provides runtime introspection and control. It binds to a separate address and should not be exposed publicly. Optionally protect it with an API key.

  • enabled — Enable the admin API
  • bind — Address to bind (e.g. "127.0.0.1:9091")
  • api_key — Optional API key for authentication
Admin API config 
admin:
  enabled: true
  bind: "127.0.0.1:9091"
  api_key: "your-secret-key"
Query admin API 
# Status
curl -H "X-API-Key: your-secret-key" \
  http://127.0.0.1:9091/api/v1/status

# Trigger reload
curl -X POST -H "X-API-Key: your-secret-key" \
  http://127.0.0.1:9091/api/v1/reload

Prometheus Metrics

Nvelox exposes a native Prometheus scrape endpoint. Configure the bind address and path in the metrics section.

  • enabled — Enable the metrics endpoint
  • bind — Address to bind (e.g. ":9090")
  • path — Scrape path (default: /metrics)
Metrics config 
metrics:
  enabled: true
  bind: ":9090"
  path: /metrics
Prometheus scrape config 
# prometheus.yml
scrape_configs:
  - job_name: nvelox
    static_configs:
      - targets: ['localhost:9090']
    metrics_path: /metrics

Docker Deployment

Run nvelox as a Docker container with the config file mounted as a volume. The official image supports amd64 and arm64 architectures.

docker-compose.yml 
version: "3.8"
services:
  nvelox:
    image: ghcr.io/nvelox/nvelox:latest
    ports:
      - "8080:8080"
      - "8443:8443"
      - "9090:9090"
    volumes:
      - ./nvelox.yaml:/etc/nvelox/nvelox.yaml:ro
      - ./tls:/etc/nvelox/tls:ro
    restart: unless-stopped

Systemd Unit

For bare-metal deployments, run nvelox as a systemd service. The example unit file includes automatic restart and SIGHUP-based reload.

/etc/systemd/system/nvelox.service 
[Unit]
Description=Nvelox Load Balancer
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nvelox --config /etc/nvelox/nvelox.yaml
Restart=always
RestartSec=5
LimitNOFILE=65535

# Reload config without restart
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target
Manage the service 
sudo systemctl enable nvelox
sudo systemctl start nvelox
sudo systemctl reload nvelox   # hot reload
sudo systemctl status nvelox
Home GitHub
Iris