Networking

GroundWave is network-agnostic. The application works identically on local Wi-Fi, over the internet, or through a VPN.

Network-Agnostic Design

GroundWave makes no assumptions about the underlying network. The application binds to a port and accepts TCP connections — it has no knowledge of whether those connections come from a device sitting one meter away on a local hotspot or a user connecting through a VPN from 100 miles away.

The networking layer — Wi-Fi access point, router, DHCP server, firewall, and any VPN or WAN uplink — is entirely external to GroundWave. It is provided by the hardware the server is running on, or by infrastructure already present at the deployment site. GroundWave integrates with any of these configurations without modification.

This separation of concerns means that the same Docker Compose stack and the same application code serves all deployment scenarios. Operators choose the networking topology that fits their mission; GroundWave runs identically in all of them.

Deployment Scenarios

The three scenarios below cover the most common field deployments. They are not mutually exclusive — a single server can operate in all three modes simultaneously if the infrastructure supports it.

Local-Only

The most common field deployment. A router or the server hardware itself creates a Wi-Fi access point with no internet uplink. All clients — phones, tablets, laptops — join that Wi-Fi network and connect to GroundWave via the server's local IP address (typically something in the 192.168.x.x range assigned by the router's DHCP server).

Everything works without internet: map tiles are served from local MBTiles/PMTiles archives, positions are tracked in real time, and all chat and coordination features operate normally. This is the zero-dependency baseline that GroundWave is designed around.

• No internet required at any point after initial setup
• Range is limited to the Wi-Fi coverage of the access point — typically 50–150m outdoors
• LoRa/Meshtastic bridge can extend effective range over radio when Wi-Fi is insufficient
• Multiple access points can be wired together with Ethernet to extend coverage

Internet-Accessible

When the deployment site has an internet uplink, remote users can connect to GroundWave over the public internet. This requires the GroundWave port (443) to be reachable from the outside, which can be achieved in several ways:

• Static public IP: Forward port 443 from the router's WAN interface to the GroundWave server. Share the public IP or a DNS name with remote users.
• Dynamic DNS (DDNS): Use a DDNS service to map a hostname to the server's dynamic public IP. Many consumer routers include DDNS client support.
• VPN tunnel: Remote users connect to a VPN that places them on the same logical network as the server. No port forwarding required. WireGuard works well on low-power hardware.
• Reverse proxy / tunnel: Services like Cloudflare Tunnel or ngrok can expose the server without router configuration, at the cost of routing traffic through a third-party infrastructure.

Multi-Site Federation

Two or more independent GroundWave servers can share data bidirectionally over a WAN connection. Each server maintains its own local users, data, and map tiles — federation only synchronizes the operational picture (positions, markers, and chat) across sites.

Federation uses Socket.IO connections between servers authenticated by pre-shared API keys. Each server acts as both a client (connecting to remote peers) and a server (accepting inbound connections from configured peers). Data flows through a last-write-wins conflict resolver and an event deduplication log to prevent echo loops.

Federated users appear on the map with a distinct visual indicator so operators know which contacts are local versus remote. See the Server Federation page for full configuration details.

TLS & Certificates

GroundWave serves all traffic over HTTPS. On first run, the server generates two things:

1. A private Certificate Authority (CA) certificate and key, stored in a persistent Docker volume. This CA is unique to each GroundWave installation.
2. A server TLS certificate signed by that CA, issued for the server's IP address and hostname. This is the certificate Nginx presents to browsers.

Because the CA is not in any operating system's or browser's root trust store, browsers will show a certificate warning when clients first connect. Clients that install the CA certificate get a fully trusted, green-padlock HTTPS experience.

Why HTTPS Matters in the Field

HTTPS is not optional for GroundWave's position tracking feature. Modern mobile browsers — Chrome for Android, Safari on iOS — refuse to expose the Geolocation API to pages served over plain HTTP. Without HTTPS, the client cannot read device GPS. Installing the CA certificate on field devices is therefore a required step in any deployment where position tracking is used.

Distributing the CA Certificate

The CA certificate can be downloaded without authentication from the server:

GET /api/ca-cert

This endpoint returns the PEM-encoded CA certificate. The setup wizard displays a QR code linking to this URL so field users can scan it with their phone and install the certificate in a few taps.

Installing on Client Devices

• Android: Download the .pem file, open Settings → Security → Install from storage. Then enable the cert under "User certificates" in Chrome's trusted CAs.
• iOS / iPadOS: Open the certificate link in Safari. iOS prompts to install a profile. After installing, go to Settings → General → About → Certificate Trust Settings and enable full trust.
• Windows: Double-click the .pem file and import into the "Trusted Root Certification Authorities" store.
• macOS: Double-click to add to Keychain, then set trust to "Always Trust" for SSL.
• Linux: Copy to /usr/local/share/ca-certificates/ and run update-ca-certificates.

Port Reference

The table below lists all ports relevant to a GroundWave deployment. Only port 80 and 443 need to be reachable from clients. All other ports are internal to the Docker network and should not be exposed on the host.