Running from source

This is not how you deploy Shepherd. It manages Alloy collectors in a Kubernetes cluster and belongs in one — see the Quickstart. This page is for changing Shepherd itself, when you want the binary under your own debugger.

Start Postgres, build the binary, run migrations, and serve.

# 1. Start Postgres
docker run -d --name shepherd-pg \
  -e POSTGRES_DB=shepherd -e POSTGRES_USER=shepherd -e POSTGRES_PASSWORD=shepherd \
  -p 5432:5432 postgres:16-alpine

# 2. Build
make build

# 3. Configure. Export rather than inline: a `VAR=x cmd1 && cmd2` prefix applies
#    to cmd1 only, so `serve` would start with no config and exit.
#    KEEP THE ENCRYPTION KEY. It encrypts git credentials and the OIDC client
#    secret at rest; a new key cannot decrypt what the old one wrote.
export SHEPHERD_DATABASE_URL=postgres://shepherd:shepherd@localhost:5432/shepherd
export SHEPHERD_SECURITY_ENCRYPTION_KEY=$(openssl rand -base64 32)
#    The first administrator, created on first boot while the users table is
#    empty. Leave the password unset and you get admin/admin, which can do
#    nothing until it is changed.
export SHEPHERD_BOOTSTRAP_ADMIN_LOGIN=admin
export SHEPHERD_BOOTSTRAP_ADMIN_PASSWORD=choose-a-password

# 4. Run
./bin/shepherd migrate up
./bin/shepherd serve          # http://localhost:8080

Sign in at http://localhost:8080 with the login and password you exported. Then mint an agent token and point a collector at it.

Stage 2’s alloy validate runs only when SHEPHERD_VALIDATE_ALLOY_BINARY points at an alloy binary (the chart sets /usr/local/bin/alloy). Unset, that check is reported as skipped, never as a pass; the in-process syntax and wiring checks still run.

The full dev stack

make dev boots a whole environment in Docker — PostgreSQL, a seeded database, a mock Microsoft Graph for group search, a git server, and live Alloy collectors already polling Shepherd at localhost:8080 with admin/admin. It is the fastest way to see the product working without a cluster, and the environment the full-stack browser suite (make test-fullstack) runs against. For a single sign-on login locally, use make dev-kind, whose mock identity provider is declared in the chart values.

make dev         # bring it all up
make dev-reset   # stop it and drop the volumes

Testing against a real cluster

make e2e-k8s creates a kind cluster, installs the chart into it, and asserts the rendered objects and the simulator’s containment from inside a running cluster. That is the suite to run when you have changed anything under deploy/helm/shepherd/.

Useful targets