rtcstats-server: IT Specifications and Requirements

This page answers the questions an IT, infrastructure, or security review asks before rtcstats-server is allowed into an environment. When you are ready to actually deploy, the step-by-step path is the Requirements & Operations Guide.

What you are deploying

rtcstats-server is a WebSocket collector that receives WebRTC telemetry from browsers and applications running rtcstats-js, writes each session to a file, and uploads that file to your own object storage while recording metadata in your own database.

Deployment model	Self-hosted. Runs entirely inside your infrastructure.
Licence	Open source, MIT, in the rtcstats monorepo.
Runtime	Node.js service, single process per container or VM, multi-process in production.
Data controller	You. No session data leaves your infrastructure unless you explicitly enable forwarding.
Third-party SaaS required	None.

Runtime requirements

Requirement	Value
Operating system	Linux, x86_64 or arm64
Node.js	22 (the project Dockerfile builds on node:22-alpine)
Container support	Yes, a Dockerfile ships in the repository
NODE_ENV	Must be production. Outside production the server runs a single process and installs no uncaughtException or unhandledRejection handlers.
Configuration	YAML file or the NODE_CONFIG environment variable
Filesystem	Read/write access to two working directories on local disk

Hardware sizing

Tier	vCPU	Memory	Local disk	Intended use
Pilot / staging	1	2 GB	20 GB	Validation, low traffic
Production node	2	4 GB	50 GB	Standard node in a cluster of 2 or more

Plan for roughly 1,000 concurrent sessions per production node and confirm the real figure with a load test on your own hardware. Session weight varies widely and there is no universal sessions-per-vCPU constant.

Disk is sized for sessions in flight, not for retention: concurrent sessions x average dump size x safety factor. Files are deleted after upload by default.

Network requirements

Inbound

Port	Protocol	Source	Notes
8080 (default, configurable)	WebSocket over plain HTTP	Load balancer only	The instance must not be internet-facing. Place it in a private subnet or VPC.
8080	HTTP POST	Load balancer only	Optional. Only active when server.httpUploadPath is set. Disabled by default.
8080	HTTP GET /healthcheck	Load balancer, monitoring	Unauthenticated. Every other GET path returns 404.

Clients connect over WSS. TLS terminates at the load balancer; rtcstats-server does not handle TLS or certificates. Certificate issuance and rotation are entirely a load balancer concern.

Outbound

Destination	Port	Required	Purpose
Your PostgreSQL database	5432 (typical)	Yes	Session metadata and the storage pointer
Your S3-compatible endpoint	443	Yes	Dump file upload
api.rtcstats.com	443	Optional	Only if you enable forwarding to rtcstats.com. Off by default.
download.maxmind.com	443	Optional	GeoIP database download. Build or deploy time only, never at runtime.

External dependencies

Dependency	Required	Notes
PostgreSQL-compatible database	Yes	Default table name internals. TLS supported, including a CA path and verify-full.
S3-compatible object storage	Yes	AWS S3, Supabase and other compatible APIs. forcePathStyle is available for endpoints that need it.
MaxMind GeoLite2	Optional	Local .mmdb file for country and city enrichment. No network calls at runtime.
rtcstats.com account	Optional	Only for optional forwarding.

Provisioning, sizing, backup and high availability of the database and object storage are yours and are out of scope for rtcstats-server.

High availability

rtcstats-server supports high availability by running two or more instances behind a load balancer.

• Stateless between sessions. All durable state lives in the database and the object storage, so a new instance can be started at any time.
• Session affinity is required. One session holds one WebSocket to one instance for its entire life, so the load balancer must be sticky.
• Health-check-driven removal. An unhealthy instance stops receiving new connections once the load balancer's HTTP health check fails it.
• Planned maintenance. Remove the instance from the load balancer targets, wait for its existing WebSocket connections to drain, then stop it.
• Scale out, not up. Prefer more, smaller machines to limit blast radius. Add instances as a node approaches 1,000 concurrent connections or sustained CPU or memory above 70 to 80 percent.

Cluster requirements in full: Horizontally scale rtcstats-server.

Serviceability

rtcstats-server exposes a single health endpoint.

Endpoint	GET /healthcheck
Response	200 OK
Authentication	None
Every other GET path	404

Use an HTTP health check at the load balancer, not TCP. A TCP check only proves the port is open.

Run each instance with --host-identifier <string>. The value is stored with every dump and is the only way to attribute a dump back to the instance that received it once you run a cluster.

Monitoring

The health check is the entire surface the server exposes. Everything else is monitored from the outside.

Signal	Source
Instance health	/healthcheck via the load balancer
CPU, memory, free disk	Your standard instance monitoring
Concurrent connections	Load balancer connection counts
Upload, storage and database errors	The runtime logs. The server logs to stdout and stderr.
Dumps actually landing	Object counts in the bucket, row counts in the database

Security

Control	Specification
Transport, client to load balancer	WSS. TLS terminated at the load balancer.
Transport, load balancer to instance	Plain WebSocket on a private network. Restrict ingress to the load balancer.
Client authorization	JWT signed with an HMAC shared secret, passed as the rtcstats-token query parameter at connect. Claims: user, session, conference.
Invalid token	The WebSocket is closed with policy-violation, code 1008.
No secret configured	If authorization.jwtSecret is unset, no authorization is performed at all. Anyone who reaches the URL can post data.
Recommended secret strength	At least 256 bits, with a rotation process that needs no downtime. Token expiry of 6 to 24 hours.
Secrets delivery	Injected as encrypted environment variables through NODE_CONFIG or a production.yaml. On AWS, an instance role removes the S3 credentials entirely.

Data protection and privacy

Where session data is stored	Your object storage and your database, in your infrastructure.
Data residency	Determined entirely by where you provision those two services.
IP addresses	server.obfuscateIpAddresses defaults to true. IPs are masked before dumps are written, so stored files carry no IP-level PII.
Geolocation	Optional. Runs before anonymization and is deliberately kept at coarse granularity.
User, conference and session identifiers	Supplied by you in the JWT claims. Do not put names or email addresses in them. Hash them or use random UUIDs.
Forwarding to rtcstats.com	Off by default. Requires a token you set explicitly. Forwarded files are anonymized.
Verification	Inspect a stored dump for IP addresses and URLs rather than assuming.

Related: Configure rtcstats-server for privacy and Data privacy and compliance.

Known limitations

• An instance going down loses the sessions it was collecting. There is no recovery path for in-flight data. A cluster limits the blast radius to one instance's worth of sessions.
• A severed WebSocket ends collection for that session. The client does not resume into another instance.
• No SIGTERM handler. The server does not drain on its own, so draining is a load balancer responsibility. A hard stop is the same event as an instance failure.
• No metrics surface. Monitoring is external, as stated above.
• Managed platform idle timeouts. Some platforms enforce a request idle timeout that long WebRTC sessions can hit. Validate against your real session lengths.

Updates and support

Release model	No numbered releases. The current source on main is the current version, and bugs are fixed there.
Recommended cadence	At least every 6 months, never less than once a year.
Autodeploy	Turn it off. A push to main should not redeploy your production.
Upgrade method	Rolling. Drain one instance out of the load balancer, replace it, return it, then move to the next.
Dump file format	Version 3. Versions 1 and 2 came from the legacy server and are not supported.
Support	The GitHub repository for open source users, or premium support for a ticket system, an SLA, or a shared Slack channel.

When you open a support request, the list of what to send with the first message is in the Requirements & Operations Guide.

Sources

• rtcstats-server: Requirements & Operations Guide, the deployment procedure behind these specifications
• Horizontally scale rtcstats-server in a cluster
• Authenticate clients with rtcstats-server
• Configure rtcstats-server for privacy
• Enrich rtcstats-server with GeoIP data