Quick Start

Get GroundWave running in under 5 minutes.

Prerequisites

Before you start, make sure the following are installed and available on your system:

• Docker — version 24 or later, with the Docker engine running (docs.docker.com/get-docker)
• Docker Compose — included with Docker Desktop; verify with docker compose version
• Git — to clone the repository
• 4 GB+ RAM — recommended minimum; 8 GB for comfortable tile pre-loading

Clone & Start

The fastest path to a running instance is Docker Compose. Follow these five steps:

1. Clone the repository

   git clone <repository-url> && cd groundwave

2. Start the stack

   Bring up all four containers — database, app server, tile server, and Nginx reverse proxy — in detached mode.

   docker compose up -d

   The first start will build the client image. Subsequent starts are fast.

3. Open the browser

   Navigate to https://localhost. Your browser will show a certificate warning because GroundWave generates a self-signed CA on first boot — click through the warning for now. The setup wizard will help you install the trusted certificate.

4. Complete the setup wizard

   Choose a callsign (your display name on the map), select a tile source — online tiles for development, or download and cache a region for offline use — and finish setup.

5. Allow location access

   The browser will request permission to read your GPS position. Allow it. Your marker will appear on the map and begin broadcasting to other connected clients in real time.

Release Archive Deployment

For field deployment where the target machine has no internet access, use a pre-built release archive. The archive bundles all Docker images, configuration, and the setup script into a single distributable tarball.

Download the latest release from the GitHub Releases page, copy it to the target machine, and run:

# Extract the release archive
tar -xzf groundwave-v1.0.0-linux-amd64.tar.gz
cd groundwave-release

# Run the setup script — loads Docker images from the bundled tarball
./setup.sh

The setup script detects the host architecture, loads the correct images from the bundled .tar files, writes a production docker-compose.yml, and starts the stack. No internet connection is required at any stage.

Registry Deployment

If the target machine has internet access, you can pull images directly from the GitHub Container Registry (GHCR) instead of bundling them in an archive.

# Pull images from GHCR and start the stack
./setup.sh --from-registry

This mode fetches the latest published images for the detected architecture and starts the stack. It is the fastest way to get a fresh install on hardware with a reliable connection.

First-Run Setup Wizard

On the very first boot GroundWave detects that setup has not been completed and redirects all traffic to the setup wizard. The wizard walks you through three stages:

1. Certificate installation — Download and install the auto-generated CA certificate into your browser or OS trust store so that HTTPS works without warnings. This is required for the Geolocation API to function (browsers restrict GPS to secure origins).
2. Tile source selection — Choose one of three options: use online tile sources (OpenStreetMap / ESRI / CartoDB), download a region by bounding box for offline use, or import a locally prepared .mbtiles file.
3. Completion — The server records setup as complete. The wizard will not appear again unless you reset the flag via the admin dashboard.

Connecting Clients

Any device on the same local network can connect to GroundWave — no app installation required. Simply open a browser and navigate to the server's IP address:

https://192.168.1.1   # replace with your server's LAN IP

The server IP is typically printed by the setup script. You can also find it with hostname -I on Linux.

Supported clients include Chrome, Firefox, Safari, and Edge on desktop and mobile. The interface is fully responsive and tested on iOS Safari and Android Chrome.