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: 3000, 8080, 51820/udp, 53
  • For production: a domain name and Cloudflare account (for SSL)

Quick Start (Development)

git clone https://github.com/RDG88/watchgrid.git
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 localhost:5000 Container images
WireGuard localhost:51820/udp VPN tunnel

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/ping

Expected response: {"status":"ok"}

Check the server logs for any issues:

docker compose logs -f server

What's Next