Development Setup

The repository uses mise for Go, Node, pnpm, and repository commands.

Install dependencies

brew install mise
mise trust
mise install
mise run deps
docker compose up -d postgres
cp .env.example .env

Generate a storage capability key and paste the value into WOODSTAR_STORAGE_CAPABILITY_KEY in .env:

openssl rand -hex 32

Set up the development hostname and certificate

The development URL is https://woodstar:8443. Add the hostname to /etc/hosts:

127.0.0.1 woodstar

Generate and trust the certificate on the development Mac:

mise run dev-tls
mise run dev-tls-trust

The files are stored under .local/tls/ and ignored by Git.

For a UTM client VM, map woodstar to the host at 192.168.64.1. Clients connecting to this development server must also trust .local/tls/ca/rootCA.pem.

Create an account

Create a local account after PostgreSQL is running:

WOODSTAR_DATABASE_URL='postgres://woodstar:woodstar@localhost:5432/woodstar?sslmode=disable' \
  mise exec -- go run ./cmd/woodstar user create \
  --email you@example.com \
  --name "Your Name" \
  --role admin

The command prompts for a password and runs pending migrations.

Start the server

mise run dev

This starts the Go backend through Air and the React frontend through Vite. The backend loads .env; Vite proxies /api to https://woodstar:8443.

Open https://woodstar:8443 for the embedded app or http://localhost:5173 for the Vite server. Browser sessions through Vite require WOODSTAR_SESSION_COOKIE_SECURE=false. OIDC through Vite also requires:

WOODSTAR_OIDC_REDIRECT_URL=http://localhost:5173/api/auth/sso/callback

Run either side separately with:

mise run dev-backend
mise run //web:dev

Development client trust

The certificate generated by mise run dev-tls is local to this checkout. Clients must trust .local/tls/ca/rootCA.pem before connecting.

Client	Setting or method
Orbit package	fleetctl package ... --fleet-certificate=.local/tls/ca/rootCA.pem
osquery	--tls_server_certs=/path/to/woodstar-ca.pem
Munki	Install the CA with a certificate profile
Santa	Install the CA with a certificate profile
MDP worker	WOODSTAR_MDP_SERVER_CA_FILE=/path/to/woodstar-ca.pem

mise run dev-tls-trust affects only the development Mac. The command does not install the certificate authority in a VM or on another Mac.