Quick start #

Four supported install paths. Pick one — all four accept the same environment variables and end up at the same /v1/graphql endpoint.

Prerequisites #

• A reachable PostgreSQL 13+ instance. The bootstrap SQL uses gen_random_uuid() from pgcrypto, which is in the contrib package.
• Redis is optional. Husaria probes it at startup and silently falls back to an in-memory LRU cache when unreachable.
• For the pre-built binary path: curl and tar. The binary is statically linked (CGO_ENABLED=0) so the host's libc version doesn't matter at runtime.
• For Docker Compose: a working Docker daemon and docker compose v2.
• For Helm: a Kubernetes cluster (any version supported by your cloud) and Helm 3.
• For the from-source path: Go 1.25+, plus pnpm@10.26.2 and node:22 for the embedded console build.

Path 1 — Pre-built binary #

The fastest path. Download the latest GitHub Release archive for your OS / arch, extract it, and run.

Step 1. Download #

# resolves the latest tag from GitHub and pulls the right archive for
# uname -s / uname -m (Linux + macOS, amd64 + arm64).
TAG=$(curl -fsSL https://api.github.com/repos/lukaszraczylo/husaria/releases/latest \
  | sed -n 's/.*"tag_name": "\([^"]*\)".*/\1/p')
curl -fsSL "https://github.com/lukaszraczylo/husaria/releases/download/${TAG}/husaria_${TAG#v}_$(uname -s)_$(uname -m).tar.gz" | tar xz

The archive expands to ./husaria (the engine), ./husaria-migrate (the migration tool), README.md, LICENSE, CHANGELOG.md, and the bundled configs/ + migrations/.

Windows is shipped as a .zip on the same release page — grab husaria_<version>_Windows_x86_64.zip directly from https://github.com/lukaszraczylo/husaria/releases/latest.

Step 2. Set the minimum environment #

export HUSARIA_DB_HOST=localhost
export HUSARIA_DB_USER=husaria
export HUSARIA_DB_PASSWORD=changeme
export HUSARIA_ADMIN_SECRET=admin-secret-key-change-me
export HUSARIA_ENABLE_CONSOLE=true

The example above sets HUSARIA_ADMIN_SECRET, so the engine boots in SECURED MODE. If you leave the secret unset, the engine refuses to start unless you also set HUSARIA_ALLOW_OPEN_MODE=true, which puts it in OPEN MODE where every caller is admin. Open mode is fine for local dev or internal-only deployments; never for the public internet. Read more in Authentication.

Step 3. Run #

./husaria

The server listens on HUSARIA_HOST:HUSARIA_PORT (default 0.0.0.0:8080). On first boot it bootstraps the husaria_data schema in your Postgres (roles, table_permissions, migrations tracker). Subsequent boots are idempotent.

Path 2 — Docker Compose #

Suitable for evaluation, demos, or development environments where you want a one-command stack.

Step 1. Write a docker-compose.yml #

services:
  husaria:
    image: ghcr.io/lukaszraczylo/husaria:latest
    ports:
      - "8080:8080"
    environment:
      HUSARIA_DB_HOST: postgres
      HUSARIA_DB_USER: husaria
      HUSARIA_DB_PASSWORD: changeme
      HUSARIA_ADMIN_SECRET: admin-secret-key-change-me
      HUSARIA_ENABLE_CONSOLE: "true"
      ENVIRONMENT: production
    depends_on: [postgres]

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: husaria
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: husaria
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Step 2. Bring it up #

docker compose up -d

The Husaria image is multi-arch (linux/amd64 + linux/arm64), distroless, runs as uid:gid 65532:65532, and ships no shell — health checks delegate to the orchestrator.

Path 3 — Helm #

Suitable for production deployments on Kubernetes.

Step 1. Add the chart repo #

helm repo add husaria https://lukaszraczylo.github.io/husaria/charts
helm repo update

Step 2. Install with overrides #

helm install husaria husaria/husaria \
  --namespace husaria --create-namespace \
  --set admin.secret=admin-secret-key-change-me \
  --set console.enabled=true \
  --set database.host=postgres.databases.svc.cluster.local \
  --set environment=production

The chart provisions a Deployment, Service, optional Ingress, and ConfigMap of non-secret env. Secrets are referenced via admin.existingSecret / database.existingSecret against an externally-managed Secret object — pass the secret name, not the value.

Step 3. Verify #

kubectl -n husaria get pods
kubectl -n husaria port-forward svc/husaria 8080:8080

Path 4 — From source #

Reach for this when you want to run a local patch, target an unsupported architecture, or pin to a specific commit ahead of the next release.

Step 1. Build #

git clone https://github.com/lukaszraczylo/husaria.git
cd husaria
make build
# -> ./build/husaria  (statically linked, CGO_ENABLED=0)

Requires Go 1.25+. The console SPA is bundled at build time, so you'll also need pnpm@10.26.2 and node:22 on PATH (make build invokes pnpm install && pnpm build inside internal/console/web/ before linking the binary).

Step 2. Set the minimum environment #

Same env as the pre-built binary path above (HUSARIA_DB_* + HUSARIA_ADMIN_SECRET + HUSARIA_ENABLE_CONSOLE=true).

Step 3. Run #

./build/husaria

Endpoints (all four paths) #

First request #

Hit the discovery endpoint to confirm the server is up:

curl -s http://localhost:8080/v1/graphql \
  -H "X-Husaria-Admin-Secret: admin-secret-key-change-me"

If you set HUSARIA_ENABLE_CONSOLE=true, open http://localhost:8080/console and use the GraphQL tab. Operations resolve against your real Postgres schema — try a simple query against one of your tables.

Next steps #

• Configuration to tune the rest of the env-var surface.
• Authentication before exposing the engine to anything other than 127.0.0.1.
• Permissions & RLS to scope what each role can see.
• Read-only replicas when you're ready to scale reads.