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>"

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

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