HydraNPS Runbook

Overview

HydraNPS is a session rating service for the Hydra streaming infrastructure. It receives a record for every streaming session that ends, whether the user rated it or not. This gives visibility into total sessions vs. rated sessions, with full session context (duration, body, district, ICE type, disconnect count).

Ratings use a 1-10 scale (half-star precision with 5 visual stars). Unrated sessions have score: null.

Infrastructure

• Server: hydranps.experiencenet.com (49.13.151.140, cax11 ARM64)
• Hetzner: hydraexperiencenet context
• Node: node-f8e5de4d
• Config: /root/.hydranps/config.yaml
• Data: /root/.hydranps/ratings.yaml
• Service: systemctl {start|stop|restart|status} hydranps
• Logs: journalctl -u hydranps -f

Health Check

curl https://hydranps.experiencenet.com/api/v1/health

Configuration

Config at ~/.hydranps/config.yaml:

server:
  domain: "hydranps.experiencenet.com"
  admin_token: "<secure-token>"

Dev mode:

server:
  listen: ":8080"
  admin_token: "dev-token"

API Endpoints

Method	Path	Auth	Description
POST	/api/v1/ratings	Bearer (admin)	Submit a session record
GET	/api/v1/ratings	Bearer (admin)	List all ratings (optional ?experience= filter)
GET	/api/v1/health	none	Health check
GET	/api/v1/runbook	none	Raw markdown runbook
GET	/admin	cookie	Ratings dashboard
GET	/docs	none	Documentation (redirect)
GET	/docs/{section}	none	Documentation viewer

POST /api/v1/ratings

Submit a session record. Called by hydraneckwebrtc workers at session end.

{
  "experience": "rupelmonde",
  "score": 7,
  "session_id": "abc123",
  "body_ip": "10.0.0.2",
  "district": "visit-flanders",
  "end_reason": "quit",
  "duration_ms": 342000,
  "ice_candidate_type": "relay",
  "disconnect_count": 0
}

• session_id is required
• score is optional (omit or null for unrated sessions). If present, must be 1-10
• end_reason values: quit (user clicked exit), timeout (idle timeout), error (process died), shutdown (worker restarting)
• Returns 201 with the created rating

GET /api/v1/ratings

List all session records. Optionally filter by experience:

curl -H "Authorization: Bearer <token>" \
  "https://hydranps.experiencenet.com/api/v1/ratings?experience=rupelmonde"

How It Works

1. User starts a streaming session via hydraneckwebrtc
2. During the stream, the user can optionally rate the experience (half-star widget, 1-10)
3. When the session ends (quit, timeout, error, or worker shutdown), the worker's OnSessionEnd callback fires
4. The callback builds an NPSRecord from the telemetry report and sends it to hydranps via POST /api/v1/ratings
5. hydranps stores the record in ratings.yaml with a unique ID and timestamp
6. The admin dashboard shows summary stats and per-session details

Data Flow

Browser --> hydraneckwebrtc worker --> session ends --> OnSessionEnd callback
    |                                                        |
    | (optional rating via star widget)                      v
    |                                                  POST /api/v1/ratings
    v                                                        |
telemetry.SetRating(id, score)                               v
                                                      hydranps stores record

Admin Dashboard

Access at https://hydranps.experiencenet.com/admin (requires login).

Shows:

• Summary stats: total sessions, rated sessions, average score, rating rate (%)
• Table: experience, score (half-stars or "not rated"), end reason, duration, body IP, district, ICE type, time
• Filter by experience dropdown

Troubleshooting

No records appearing

• Check hydraneckwebrtc worker has nps section in config with correct URL and token
• Verify hydraneckwebrtc is v1.10.0+ (the version that added NPS integration)
• Check hydraneckwebrtc worker logs for NPS errors: journalctl -u hydraneckwebrtc -f | grep nps
• Verify hydranps is reachable from the worker: curl https://hydranps.experiencenet.com/api/v1/health

Records missing score

• Score is nil when the user did not rate. This is expected behavior.
• If users are rating but scores are nil, check that the half-star widget is present in the stream overlay (hydraneckwebrtc inject.go)
• The rating is stored in telemetry during the session and sent with the NPS record at session end

Service not starting

• Check config exists: ls -la /root/.hydranps/config.yaml
• Verify admin_token is set in config
• Check systemd unit has Environment=HOME=/root
• View logs: journalctl -u hydranps -f

Logs

journalctl -u hydranps -f

# Key log prefixes
# [nps] - rating submissions (session ID, experience, score, end reason)

Releasing

1. Tag: git tag v<X.Y.Z>
2. Push: git push origin v<X.Y.Z>
3. CI builds linux-amd64 and linux-arm64 binaries
4. Uploads to GitHub Releases and releases.experiencenet.com
5. Running instances auto-update on next 6-hour check cycle