HydraVenues

District and venue registry managing physical locations and their organizational ownership.

Infrastructure

Operations

Check status

ssh root@91.98.117.16 systemctl status hydravenues

Or via the health endpoint:

curl -s https://hydravenues.experiencenet.com/api/v1/health

View logs

ssh root@91.98.117.16 journalctl -u hydravenues -f

Show last 100 lines:

ssh root@91.98.117.16 journalctl -u hydravenues -n 100 --no-pager

Restart

ssh root@91.98.117.16 systemctl restart hydravenues

Update

Updates happen automatically. The service polls releases.experiencenet.com for new versions and applies them. To check the current version:

ssh root@91.98.117.16 hydravenues version

Never manually deploy -- always use the release pipeline (tag + push to trigger CI, release server distributes, service auto-updates).

Create district (API)

Districts are infrastructure-level entities with no owner. They represent physical regions or areas.

curl -X POST https://hydravenues.experiencenet.com/api/v1/districts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "District Name",
    "region": "eu-west"
  }'

Create venue (API)

Venues belong to an organization (managed via HydraOrganization) and are located within a district.

curl -X POST https://hydravenues.experiencenet.com/api/v1/venues \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Venue Name",
    "district_id": "<district-id>",
    "organization_id": "<organization-id>"
  }'

List districts (API)

curl -s https://hydravenues.experiencenet.com/api/v1/districts \
  -H "Authorization: Bearer <token>" | jq .

List venues (API)

curl -s https://hydravenues.experiencenet.com/api/v1/venues \
  -H "Authorization: Bearer <token>" | jq .

Delete venue (API)

curl -X DELETE https://hydravenues.experiencenet.com/api/v1/venues/<id> \
  -H "Authorization: Bearer <token>"

Delete district (API)

Districts can only be deleted when no venues reference them.

curl -X DELETE https://hydravenues.experiencenet.com/api/v1/districts/<id> \
  -H "Authorization: Bearer <token>"

Admin dashboard (web UI)

Browse to https://hydravenues.experiencenet.com/admin and log in with the admin token. The dashboard shows all districts and their venues. Clicking a venue opens the venue topology view: floors, spaces, and installed gear. Live status for render nodes (bodies) is fetched from HydraCluster automatically if cluster.url and cluster.token are set in the config.

Editing the layout: click Edit Layout on the venue page to enter edit mode. In edit mode:

• Space names and types are editable inline; the floor selector moves a space to a different floor
• Asset rows become editable (label, type, model, notes); the space selector moves an asset to a different space; the ✕ button removes it
• + Add asset appears at the bottom of each space to create a new asset
• + Add space appears at the bottom of each floor
• Save Changes persists all edits; Discard reloads without saving

Discovered devices (requires HydraNeck): when HydraNeck is configured, a collapsible Discovered devices panel appears below the network scan bar. It lists every unmanaged client seen on the venue network (name, IP, MAC, online status). Devices whose MAC address appears in any asset's notes field are shown as "placed" with their space name. Unplaced devices have an Add to room button:

1. Click Add to room on any unplaced device.
2. Select the target space from the dropdown.
3. The type is guessed from the device name (e.g. access-point for AP hostnames, intercom for 2N devices) — adjust if needed.
4. Label and notes are pre-filled with the device name and IP · MAC.
5. Click Add to layout — the asset is saved immediately without entering edit mode.

To prevent duplicates, store the MAC address in the asset's notes field (e.g. 12.0.2.150 · 70:B3:D5:D3:C9:C9). The discovery panel uses the MAC to detect whether a device is already placed.

File attachments: a Files button is available at the venue level, on each space, and on each asset row (camera icon). Clicking it opens an upload panel — on mobile this triggers the native camera/photos/files sheet. Attachments are stored at:

/root/.hydravenues/venues/<venue-id>/attachments/<scope>/<entity-id>/

where scope is venue, space, or asset.

Manage venue layout (floors, spaces, assets)

Each venue has an optional layout.yaml file at:

/root/.hydravenues/venues/<venue-id>/layout.yaml

Structure:

floors:
  - id: ground
    name: Ground Floor
    spaces:
      - id: main-room
        name: Main Room
        type: room          # free text: room | corridor | outdoor | studio | booth | control-room
        assets:
          - id: body-1
            type: body
            label: Render Node 1
            cluster_node_id: node-abc123  # live status from HydraCluster
          - id: screen-1
            type: screen
            label: Welcome Display
            model: Samsung 55"
            notes: "rack position, IP, etc."

The layout is editable through the web UI (see above) or via the raw YAML editor at the bottom of the venue page. To write via the API:

curl -X PUT https://hydravenues.experiencenet.com/api/v1/venues/<id>/layout \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @layout.json

Read the layout:

curl -s https://hydravenues.experiencenet.com/api/v1/venues/<id>/layout \
  | jq .

HydraCluster integration (live body status)

Add to /root/.hydravenues/config.yaml:

cluster:
  url: "https://hydracluster.experiencenet.com"
  token: "<cluster-admin-token>"

Restart the service after changing config. When configured, the admin venue detail page shows live online/offline status for any asset with a cluster_node_id field in its layout.

HydraNeck integration (live network status + device discovery)

Add to /root/.hydravenues/config.yaml:

neck:
  url: "https://hydraneck.experiencenet.com"
  token: "<neck-admin-token>"

Restart the service. When configured:

• Assets with a cluster_node_id get their status from HydraNeck (which already correlates nodes against the router scan) rather than calling HydraCluster directly — this eliminates duplicate API calls.
• Assets with a neck_router_id matching a HydraNeck router name show live router status (online/offline, firmware version, client count).
• The Discovered devices panel appears on each venue page, listing all unmanaged network clients. Use the Add to room button to place devices into spaces without YAML editing.

To link an asset to a HydraNeck router, set neck_router_id in the layout to the router's name as known to HydraNeck (e.g. mikrotik-cloud7).

Key Concepts

• Districts vs Venues: districts are infrastructure-level groupings with no owner. They represent physical regions or areas. Venues are concrete locations that belong to an organization and are placed within a district.
• Organization ownership: every venue must reference a valid organization from HydraOrganization. The organization_id links venues to their owning customer or agency.
• YAML store: index file plus per-entity YAML files in /root/.hydravenues/. Separate stores for districts and venues. No database required.
• REST API with bearer token auth: all mutating endpoints require a valid bearer token issued by hydraauth.
• SSE events via hydramonitor: venue and district changes are broadcast as server-sent events, consumed by HydraPipeline and other services.
• Auto-updates from releases.experiencenet.com: the service checks for new releases and updates itself without manual intervention.

Troubleshooting

YAML corruption

If the YAML store becomes corrupted (partial writes, disk issues):

1. Stop the service: systemctl stop hydravenues
2. Check the data directory: ls -la /root/.hydravenues/
3. Look for malformed YAML files -- inspect the index and individual entity files
4. Restore from backup if needed, or manually fix the YAML syntax
5. Start the service: systemctl start hydravenues

Service won't start

1. Check logs for the error: journalctl -u hydravenues -n 50 --no-pager
2. Verify config exists and is valid: cat /root/.hydravenues/config.yaml
3. Check if the port is already in use: ss -tlnp | grep <port>
4. Verify the binary exists and is executable: ls -la $(which hydravenues)
5. Try running manually to see output: hydravenues serve

Auth token issues

1. Verify the token by calling hydraauth directly: curl -s https://hydraauth.experiencenet.com/api/v1/verify -H "Authorization: Bearer <token>"
2. Check that hydraauth is reachable from the venues server: ssh root@91.98.117.16 curl -s https://hydraauth.experiencenet.com/api/v1/health
3. If tokens are consistently rejected, check clock sync: ssh root@91.98.117.16 date -- token validation may fail if the server clock is skewed

Discovery panel disappears after clicking Scan Now

If the Discovered devices panel is visible, a user clicks Scan Now, and the panel is gone after the page reloads:

1. Check hydravenues logs for network errors from the neck integration:

   journalctl -u hydravenues -n 50 --no-pager | grep fetchNeckVenueData
   

   Errors like network endpoint returned 404 or network call: context deadline exceeded point to a transient hydraneck connectivity issue.

2. If the panel disappeared without errors, the scan may have completed but hydraneck's /api/v1/venues/{id} returned scan: null momentarily (mid-scan race). The page reload happening 1.2 seconds after the scan response may have landed during that window. Reload the venue page manually -- the panel should reappear once hydraneck's store is stable.

3. If the panel stays gone after a manual reload, verify hydraneck is reachable from the venues server and that the venue name matches exactly:

   curl -s https://hydraneck.experiencenet.com/api/v1/venues/<venue-id>/network \
     -H "Authorization: Bearer <neck-token>" | jq .unmanaged_clients | length
   

   A 404 here means the venue is not registered in hydraneck under that name.

Login redirects to /admin instead of the original page

External links into the admin UI (e.g. "view in venues" from hydraneck) require an active session. On login, the user is sent to the originally requested page via the ?next= query parameter.

If a user lands on /admin instead of the intended venue page:

• Check that hydravenues is running hydrawebcomponents >= v0.6.1 (introduced ?next= support).
• The next parameter must be a relative path -- absolute URLs are rejected to prevent open redirect.

Venue references invalid organization

If a venue's organization_id points to a deleted organization:

1. List venues to identify the affected entries: curl -s https://hydravenues.experiencenet.com/api/v1/venues -H "Authorization: Bearer <token>" | jq .
2. Update or delete the venue as appropriate
3. Check HydraOrganization to confirm the organization state

Backup & Recovery

What is backed up

Hetzner automated daily server snapshots are enabled on hydravenues (91.98.117.16), context hydraexperiencenet. Backup window: 02:00–06:00 UTC, 7-day retention.

The snapshot covers the entire server disk, including all venue YAML files.

Restore procedure

1. In the Hetzner Cloud Console (hydraexperiencenet project), open Servers → hydravenues → Backups.
2. Power off the server, restore the snapshot, then power on.
3. Verify:

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