Docker & Setup

Deploy GroundWave using Docker Compose on any 64-bit hardware.

Containers

GroundWave runs as four Docker containers orchestrated by Docker Compose. Only the Nginx reverse proxy exposes ports to the host network; all other containers communicate over a private internal Docker network named groundwave-net.

An optional fifth container is available for TAK interoperability. It is activated separately via a Docker Compose profile and does not start with the main stack by default.

Development Setup

The repository ships with a development Docker Compose override that builds images locally and enables hot reload for rapid iteration. No pre-built images or registry credentials are required.

1. Clone the repository

   git clone <repository-url>
   cd groundwave

2. Copy the environment template

   cp config/.env.example config/.env

   Edit config/.env with your desired settings before starting.
3. Start the stack

   docker compose up -d

   Docker Compose automatically merges docker-compose.yml with the dev override file, building local images for all services.
4. Access the app

   Open https://localhost in your browser. Accept the self-signed certificate on first load. The app server auto-restarts on file changes to server/src/. Client changes are served via Vite HMR.

Production Setup

The production docker-compose.yml references local image tags produced by the release build script. The intended deployment workflow is:

1. Build a release archive on your development machine:

   ./scripts/build-release.sh

   This script builds multi-stage Docker images for both linux/amd64 and linux/arm64, exports them as .tar archives, and bundles them with the Compose file, Nginx config, env template, and setup.sh into a self-contained distributable tarball.
2. Transfer the tarball to the target machine via USB drive, SCP, or any available transport — no internet connection is required on the target.
3. Extract and run the setup script:

   tar xzf groundwave-release-*.tar.gz
   cd groundwave-release
   ./setup.sh

The release build eliminates Node.js as a host dependency by using a multi-stage client Dockerfile: the first stage compiles the React application inside a Node.js builder image, and the second stage copies only the compiled static assets into the final Nginx image. The target machine needs only Docker.

Setup Script

setup.sh is the entry point for target-machine deployment. It handles everything from image loading to TLS certificate generation:

• Architecture detection — identifies x86_64 or aarch64 and loads the appropriate image tarball.
• Docker image loading — calls docker load on each bundled .tar file. No registry or internet access required.
• Environment configuration — prompts for required settings if config/.env does not exist, then writes the file.
• TLS certificate generation — creates a private Certificate Authority and a server certificate signed by that CA. Nginx is configured to use these certificates automatically.
• Container startup — runs docker compose up -d to start all services.

Registry Mode

When internet connectivity is available on the target machine, you can skip the image tarball entirely and pull directly from the GitHub Container Registry:

./setup.sh --from-registry

This mode uses docker-compose.registry.yml as an overlay, which references GHCR image tags instead of local image names. Architecture selection is handled automatically by Docker's manifest list — the correct image variant is pulled based on the host's CPU architecture.

Environment Variables

All configuration is provided through environment variables defined in config/.env. The following table lists the most important variables:

Multi-Architecture Builds

GroundWave ships pre-built images for two CPU architectures, covering the full range of supported deployment targets:

The GitHub Actions CI workflow builds both variants on every tagged release using Docker Buildx with QEMU emulation for cross-compilation. The multi-stage Dockerfile for the client ensures Node.js is only present in the builder stage — the final Nginx image contains only compiled static assets, keeping the production image lean.

Registry Deployment

Pre-built images are published to the GitHub Container Registry (GHCR) as part of the CI release workflow. This provides an alternative to the bundled-tarball deployment method when WAN connectivity is available on the target machine.

The docker-compose.registry.yml override file replaces local image references with GHCR image tags. Use it with the standard Compose override mechanism:

docker compose -f docker-compose.yml -f docker-compose.registry.yml up -d

Or use the setup script shorthand, which applies the override automatically:

./setup.sh --from-registry

Docker pulls the correct image variant automatically based on the host architecture — no manual architecture selection is needed.

Health Checks

GroundWave exposes two health endpoints for monitoring and orchestration:

Docker Compose restart policies (restart: unless-stopped) provide automatic container recovery. If the application container crashes, Docker restarts it within seconds without requiring administrator intervention. Combined with the basic health check, this creates a resilient self-healing deployment suitable for unattended field operation.