End-to-end walkthrough for bringing a new venue from cold to streaming. Each step links to the component-specific runbook for full detail; this doc is the orchestration order.
Use this when adding any new venue — partner-managed (Citymesh, telco, ISP) or HYDRA-managed (Omada, MikroTik NeckAir, Linux VM gateway).
Collect before you start:
cloud-seven, rupelmonde, museum-x).bxl1 → Brussels hub at hydraguard.experiencenet.com).citymesh (partner MikroTik), omada (HYDRA TP-Link), linuxvm (cloud VM gateway), gateway (on-prem WireGuard gateway). See partner vs HYDRA-managed terminology footnote.Read Site Types to decide partner-managed vs HYDRA-managed. The choice determines who installs the WireGuard endpoint at the venue (the partner installs on a MikroTik they own, or we install on an Omada/MikroTik/Linux gateway we control).
CIDR allocation rules are in Address Ranges. For most venues hydraguard's auto-assignment is fine (10.10.X.1/32 tunnel, 10.0.X.0/24 LAN). Override only when the partner requires a specific range — pass --lan <cidr> on hydraguard venue add.
On the district hub (ssh ubuntu@hydraguard.experiencenet.com for Brussels):
hydraguard venue add <venue-name> --location <district> --guard <guard-type> [--lan <cidr>]
hydraguard apply
The add command generates a WireGuard keypair (private key printed once to stdout — save it if you need to recreate the config later). apply regenerates wg0.conf on the hub and hot-reloads without disrupting existing peers.
Then take the branch that matches the guard type — each has its own full runbook:
| Guard type | Full runbook |
|---|---|
citymesh (partner MikroTik) |
hydraguard/docs/runbooks/citymesh-venue.md |
omada (HYDRA TP-Link) |
hydraguard/docs/runbooks/omada-venue.md |
linuxvm / gateway |
hydraguard runbook.md "Add a Venue" section |
citymesh)Export the partner config and hand it off:
hydraguard venue config <venue-name> > /tmp/<venue-name>.partner.conf
Send to the partner — bundle and copy-pasteable email template are in hydraguard/docs/runbooks/citymesh-venue.md Step 3:
.partner.conf file (peer profile to install on their MikroTik).hydraguard.experiencenet.com:51820/udp — their MikroTik needs outbound UDP/51820 reach.:443 preferred, legacy binary on :8729 acceptable).Capture the handover date in the reference table in citymesh-venue.md.
omada)Configure WireGuard on the Omada controller via its API. Full step-by-step is in hydraguard/docs/runbooks/omada-venue.md including: creating the WG interface (six required fields — name, status, mtu, listenPort, privateKey, localIp), adding the hub as a peer, verifying handshake.
linuxvm / gateway)Bare WireGuard on a Linux VM. See HydraGuard CLOUD.md or GATEWAY.md per topology.
From the hub, regardless of guard type:
hydraguard status # <venue> row shows "Xs ago" handshake
wg show wg0 | grep -A6 <venue-pubkey> # endpoint + transfer bytes
ping <venue-LAN-gateway> # e.g. 10.0.X.1
Each Body machine maintains its own independent WireGuard tunnel to the hub, regardless of whether the venue has a site tunnel. This means bodies stay reachable even if the site tunnel is down.
Two paths:
hydraguard-air role in hydracluster admin UI; provisioning runs end-to-end via recipe. Full flow in Body Provisioning.hydraguard air add + Windows WireGuard install steps.Add Windows firewall rule on each body:
netsh advfirewall firewall add rule name="HydraGuard WG" dir=in action=allow remoteip=10.10.0.0/16 enable=yes
Once bodies are on the mesh, they should appear in hydracluster admin. Assign appropriate roles (hydrabody, hydraguard-air). The hydranode agent picks up role assignments on its next poll and installs/starts the body software.
Verify:
# From hydracluster admin UI: body shows "online" with handshake recent
# Or via API:
curl -sk https://hydracluster.experiencenet.com/api/v1/nodes/<node-id>
Heads (kiosk displays) are the visitor-facing devices. For each head:
head_id + cluster URL + bearer token in ~/.hydraheadflatscreen/config.yaml. See hydraheadflatscreen/docs/runbooks/runbook.md.hydraheadsamsungtv once shipped.Register each head in hydracluster admin with type flatscreen (or samsungtv once available), assign district/venue, generate bearer token.
Verify: head's status PUT shows up in the cluster log every 30s with status:idle.
If hydraneck is not yet a mesh peer for this district, do the one-time enrollment first — see Mesh Participation.
The venue must exist in the HydraVenues API before hydraneck can scan it. Check first:
curl -s https://hydravenues.experiencenet.com/api/v1/venues | jq '.[].id'
If missing, create it:
curl -s https://hydravenues.experiencenet.com/api/v1/venues \
-X POST \
-H "Authorization: Bearer <hydravenues-admin-token>" \
-H "Content-Type: application/json" \
-d '{"id":"<venue-name>","name":"<Display Name>","district_id":"bxl1","organization_id":"visit-flanders","status":"active"}'
The admin token is in ~/.hydravenues/config.yaml on the hydravenues server.
Edit /root/.hydraneck/config.yaml on hydraneck.experiencenet.com. The routers: block is keyed by venue ID:
routers:
<venue-name>:
- name: mikrotik-<venue-name>
type: mikrotik
address: "10.10.X.1:8729" # WG tunnel IP:port — NOT public WAN. Port is required.
username: <readonly-user-from-partner>
protocol: api # binary protocol on 8728/8729 — use this when partner opens API-SSL
# protocol: rest # default; HTTPS+JSON on :443; requires RouterOS v7.1+
tier: partner
wan_interface: ether1 # the WAN-facing interface name on the MikroTik
Protocol selection:
rest (default) — HTTPS + JSON on port 443. Requires RouterOS v7.1+.api — binary protocol on port 8728 (plain) or 8729 (TLS). Use when the partner's MikroTik is on RouterOS v6, or when they only open API/API-SSL ports rather than HTTPS 443.Address format: always host:port (e.g. 10.10.2.1:8729). The port is required for the api protocol; without it the dial fails with missing port in address.
Never put the password inline in config.yaml. Add it to /root/.hydraneck/secrets.yaml (mode 0600) keyed by <venue>/<router-name>:
secrets:
<venue-name>/mikrotik-<venue-name>:
password: '<password-from-partner>'
Before restarting hydraneck, confirm the API port is actually reachable from hydraneck:
ssh root@hydraneck.experiencenet.com
ping -c3 10.10.X.1 # ICMP must work first (proves WG tunnel)
nc -zv -w5 10.10.X.1 8729 # TCP port must also be reachable
If ping works but TCP times out — the MikroTik has a two-layer access control problem. Both must allow the connection:
/ip firewall filter INPUT chain — needs a rule allowing TCP from 10.10.100.14 (hydraneck's WG IP) to port 8728/8729./ip service settings — API/API-SSL service must not restrict available-from in a way that excludes the WG interface.Ask the partner to check both layers. Diagnostic command for them to run from MikroTik terminal:
/ip service print
/ip firewall filter print chain=input
ssh root@hydraneck.experiencenet.com "systemctl restart hydraneck && hydraneck scan <venue-name>"
A working scan shows non-zero clients and the router status as live rather than unreachable.
A new venue is "live" when all of the following pass:
hydraguard status shows recent handshake for the venue peer and every body's air peer.ping <venue-LAN-gateway> succeeds.online, no agent-down./admin/venues/<venue-name> correlation table green for all bodies, bandwidth chart populating.hydraguard.experiencenet.com:51820/udp outbound, and that the public key in our mesh.yaml matches what they have installed.HydraGuard WG rule (Step 4) is the most common omission./root/.hydraneck/config.yaml should use 10.10.X.1-style addresses for partner venues./ip service settings are also restricting access. Ask them to check both /ip firewall filter print chain=input and /ip service print. See Step 7d above.address: field in routers: config is missing the port. Must be host:port format, e.g. 10.10.2.1:8729.GET /api/v1/heads/{id} for a stale stream block.partner vs citymesh — current hydraguard CLI requires --guard citymesh. The partner design doc uses the generic partner. Use citymesh in commands today.