Pre‑launch checklist for a self‑hosted Nighthawk streaming server

If you’re about to put a self‑hosted Nighthawk server in front of real encoders and viewers, use this checklist to lock in the essentials: ports, feature toggles, ingest and playback controls, recording uploads, and event webhooks. Where applicable, this article calls out concrete failure behavior so you can verify end‑to‑end before launch.

See /server-docs for installation, configuration, and protocol context.

1) Environment and networking: bind only what you plan to use

• Confirm protocol ports and firewall rules
• RTMP ingest (TCP 1935)
• SRT ingest (UDP 10080)
• HTTP for HLS/HTTP‑FLV and WebRTC signaling (TCP 8080)
• WebRTC media (UDP 8000)
• RTSP ingest for IP cameras (TCP 8554)

These endpoints are configurable via environment variables in the Docker Compose file; keep only the protocols you intend to expose open at your perimeter.

• Cross‑check Server Docs sections you’ll rely on
• Installation & Updates
• Configuration & Ports
• Publishing & Playback
• Recording & Features
• Management APIs
• Licensing
• Troubleshooting

Tip: Stage with the same port map you will run in production to avoid last‑minute surprises when encoders or firewalls are pinned to specific ports.

2) Feature license awareness: know what the runtime enables (and disables)

Nighthawk’s startup sequence disables blocks that aren’t licensed so you don’t depend on features that won’t run at launch. Specifically:

• SRT and WebRTC services are turned off when those features aren’t present.
• DVR/Recording is turned off when neither DVR nor Recording is licensed.

Plan validation around the features you’ve licensed; if a block is disabled at startup, dependent workflows (e.g., recordings or SRT ingest) will not be available.

3) Ingest control: require a publish password (stream authentication)

• Set NH_PUBLISH_PASSWORD in the environment. On startup, Nighthawk enables stream authentication.
• Update your encoders to append the password to the stream key as a query parameter (e.g., mychannel?password=YOUR_PASSWORD). Viewers are not prompted for this; it applies to ingest only.
• Failure behavior to expect in tests: publishes without the correct password are rejected during on_publish handling.

4) Viewer access: enforce signed playback URLs

If you need viewer‑side access control, enable signed playback and issue per‑viewer tokens from your backend.

• Set NH_PLAYBACK_SECRET in the environment. On startup, Nighthawk enforces token checks on playback requests and ensures HLS sessions trigger validation.
• Token format and signing: the included helper signs the stream key and an expiry timestamp using HMAC‑SHA256 and appends token/expiry as query parameters.
• Failure behavior to expect in tests: missing, invalid, or expired tokens cause playback to be rejected.

Note: Expiry choices, secret storage, and URL distribution are your responsibilities. Keep tokens short‑lived and scoped to the specific stream (or ABR variant) you intend.

5) Recording uploads to object storage: prerequisites and failure modes

If you want finished recordings uploaded to object storage:

• Set NH_S3_BUCKET, NH_S3_ACCESS_KEY, and NH_S3_SECRET_KEY. If credentials are missing while NH_S3_BUCKET is set, the server disables upload at startup and logs an error.
• Region defaults to us‑east‑1 unless you set NH_S3_REGION. For S3‑compatible stores, configure the appropriate endpoint per your environment.
• Uploader behavior:
• Performs a single signed PUT per attempt.
• Retries up to three times on errors.
• If all attempts fail, the local file is kept.
• Local deletion happens only after a successful upload and only when NH_S3_DELETE_LOCAL is explicitly enabled.
• Safety checks: the local control plane only accepts recording paths beneath the recordings directory and validates simple, safe filenames before touching the filesystem.

If DVR/Recording features are disabled at startup, no recordings are produced and there is nothing to upload.

6) Lifecycle webhooks: enable, integrate, and design for loss

Forward stream lifecycle events to your systems for automation (e.g., publish attempts, playback validations, recording completion):

• Set NH_EVENT_WEBHOOK to an http:// or https:// URL and restart. On startup the server enables forwarding to that endpoint.
• Delivery model: fire‑and‑forget with a short (5‑second) timeout and no retries. If the endpoint is slow or unreachable, events may be lost. Keep your handler fast and queue long work internally.
• Request format: JSON POST with an X‑Nighthawk‑Event header naming the event type.

7) Adaptive Bitrate (ABR): enable only when licensed and use supported variants

• Enabling: Set NH_ABR=on. ABR is disabled if the license does not include it; the runtime logs that a Professional or Enterprise license is required.
• Variants: Only known presets are accepted (1080p, 720p, 480p, 360p, 240p). Unknown variants are skipped.
• Internal playback checks: when ABR is actually enabled, internal loopback requests by the transcoder are exempted from signed playback checks to avoid blocking internal pulls.

8) Pre‑launch verification checklist (actionable)

Run these steps end‑to‑end before you go live:

• Networking and ports
• Confirm only required ports are exposed and reachable from encoders/viewers.
• Verify UDP paths if you plan to use SRT and/or WebRTC.

• Feature gates
• Start the server and confirm SRT/WebRTC/DVR states match your license. If disabled, adjust plans or configuration before launch.

• Ingest authentication
• Attempt a publish without the password (expect rejection).
• Attempt a publish with the correct ?password=… stream key (expect success).

• Signed playback
• Try an unsigned playback (expect rejection).
• Generate a signed URL with a short TTL; play successfully.
• Wait for expiry and confirm the same URL is rejected.

• Recording uploads
• Produce a short recording; confirm a single upload attempt per retry with at most three retries.
• Temporarily break network or credentials to observe failure and retention of the local file.
• Re‑enable and verify uploads succeed; if NH_S3_DELETE_LOCAL is enabled, confirm local deletion after success.

• Webhooks
• Point NH_EVENT_WEBHOOK to a fast handler; trigger on_publish, on_play, and on_dvr and confirm JSON delivery and X‑Nighthawk‑Event header.
• Simulate a slow or failing endpoint and confirm that events may be dropped due to fire‑and‑forget with timeout.

• ABR (if licensed)
• Enable supported variants only and verify they appear as expected; ensure no unknown variants are silently required by your player.

9) Final notes on rollout and references

• Keep environment variables and secrets in your orchestrator (Docker/Compose/Kubernetes) and restart to apply changes.
• Treat hook payloads as untrusted; your handlers should validate and sanitize inputs.
• For plan and licensing decisions, see /#pricing. For installation and deeper configuration context, see /server-docs.