Skip to main content

Getting Started

This guide gets you from zero to a running Consul Guardian instance with Git-backed KV history and a web dashboard.

Prerequisites​

  • Go 1.22+ (for building from source)
  • Docker (optional, for running Consul locally or using the Guardian container)
  • A running Consul agent (or we'll start one below)
  • Git (installed on the host -- the Docker image includes it)
  • Node.js 18+ (for building the frontend, not needed with Docker)

Installation​

Build from source​

git clone https://github.com/consul-guardian/consul-guardian.git
cd consul-guardian
go build -o consul-guardian .

# Build the frontend
cd frontend && npm install && npm run build && cd ..

The binary is now at ./consul-guardian. Move it to your $PATH if you want:

sudo mv consul-guardian /usr/local/bin/

Docker​

docker pull ghcr.io/consul-guardian/consul-guardian:latest

The image includes Git and SSH client. It runs as a non-root guardian user.

Quick start​

1. Start a local Consul (if you don't have one)​

docker run -d --name consul -p 8500:8500 hashicorp/consul:1.18 agent -dev -client=0.0.0.0

2. Load some test data​

consul kv put config/database/host "db.example.com"
consul kv put config/database/port "5432"
consul kv put config/cache/ttl "300"
consul kv put feature-flags/dark-mode "true"
consul kv put feature-flags/new-checkout "false"

If you don't have the consul CLI, use curl:

curl -X PUT -d 'db.example.com' http://localhost:8500/v1/kv/config/database/host
curl -X PUT -d '5432' http://localhost:8500/v1/kv/config/database/port
curl -X PUT -d '300' http://localhost:8500/v1/kv/config/cache/ttl

3. Start Guardian with the dashboard​

./consul-guardian dashboard \
  --consul-addr http://localhost:8500 \
  --prefix "config/,feature-flags/" \
  --git-repo ./consul-backup \
  --static-dir ./frontend/dist \
  --listen :9090

You'll see output like:

  Consul Guardian Dashboard: http://localhost:9090
  Watching: [config/ feature-flags/]
  Git repo: ./consul-backup

4. See changes in Git​

Open a second terminal:

cd consul-backup
git log --oneline

You should see an initial commit with all existing keys. Now make a change:

consul kv put config/cache/ttl "600"

Within seconds, Guardian detects the change and commits it:

git log --oneline -5
# abc1234 consul-guardian: 1 keys changed
# def5678 consul-guardian: 5 keys changed
git diff HEAD~1
# -300
# +600

5. Open the dashboard​

Navigate to http://localhost:9090. You'll see:

  • Overview -- KPI cards and a live activity feed
  • KV Store -- Browse all watched keys
  • Change History -- Timeline of every change Guardian has recorded

Next steps​