Skip to content

Getting Started

This guide walks you through installing Watchgrid, logging in for the first time, and configuring your server.

Prerequisites

  • Docker and Docker Compose (v2+)
  • A Linux host (Ubuntu 22.04+ recommended) or macOS for development
  • Ports available on the server: 3000 (frontend), 8080 (API), 51820/udp (WireGuard), 53/udp+tcp (Magic DNS), 5432 (PostgreSQL, optional for external access)
  • For production: a domain name and Cloudflare account (for SSL)

Quick Start (Development)

From a checkout of the Watchgrid repository:

cd watchgrid
docker compose up -d

This starts the full stack:

Service URL / Port Purpose
Frontend http://localhost:3000 Web dashboard
API Server http://localhost:8080 REST API
PostgreSQL localhost:5432 Database
Docker Registry registry.wg:5000 (via VPN) Container images
WireGuard localhost:51820/udp VPN tunnel

Registry is VPN-only by default

In the default docker-compose.yml the registry port is not exposed to the host. It is reachable only inside the Docker network and, once devices join, via WireGuard at registry.wg:5000. See Docker Registry for pushing images from your workstation.

First Login

  1. Open http://localhost:3000 in your browser
  2. Log in with the default credentials:
  3. Username: admin
  4. Password: watchgrid
  5. You'll land on the Dashboard — your real-time fleet overview

Change the default password

Go to System → Users → Change My Password immediately after first login.

Environment Variables

Configure Watchgrid by setting environment variables in your docker-compose.yml or .env file:

Required

Variable Default Description
WG_SERVER_ENDPOINT — Your server's public IP and WireGuard port (e.g., 203.0.113.50:51820)
JWT_SECRET — Secret key for JWT signing. Generate with openssl rand -hex 32
POSTGRES_PASSWORD watchgrid PostgreSQL database password
ADMIN_USERNAME admin Initial admin username
ADMIN_PASSWORD watchgrid Initial admin password

Optional

Variable Default Description
FRONTEND_HOST localhost Domain name for SSL (production only)
SERVER_LATITUDE — Server location latitude (for map display)
SERVER_LONGITUDE — Server location longitude (for map display)
REGISTRY_USERNAME — Docker registry authentication username
REGISTRY_PASSWORD — Docker registry authentication password
WATCHGRID_MAGIC_TLD wg Top-level domain for Magic DNS
WATCHGRID_DEV_MODE false Enable development mode (relaxed security)

WireGuard Endpoint

The WG_SERVER_ENDPOINT variable is critical. It must be the IP address (or domain) and port that devices can reach from the internet:

# Example: server on a VPS with public IP
WG_SERVER_ENDPOINT=203.0.113.50:51820

# Example: server behind a NAT with port forwarding
WG_SERVER_ENDPOINT=your-domain.com:51820

If devices can't connect to the VPN, this is usually the first thing to check.

Verifying the Installation

After starting the stack, confirm all services are healthy:

docker compose ps

You should see all containers running. Then verify the API:

curl http://localhost:8080/api/version

Expected response (exact version numbers will vary):

{"server":"1.24.0","agent":"1.25.2"}

Check the server logs for any issues:

docker compose logs -f server

What's Next