Skip to content

Installation

The simplest way to try Sparrow. No clone, no secrets, no .env needed:

Terminal window
curl -O https://raw.githubusercontent.com/sarathsp06/sparrow/main/deploy/docker-compose.yml
docker compose up -d

[!NOTE] This Compose file is for local evaluation – open API, a well-known encryption key, and the port bound to 127.0.0.1 only. For a real deployment, see Production Deployment.

Endpoint URL
Web UI http://localhost:8080
REST API http://localhost:8080

If port 8080 is taken, SPARROW_PORT=8090 docker compose up -d publishes the server on http://localhost:8090 instead.

Open the web UI first. Registering event types and webhooks, pushing test events and inspecting deliveries can all be done there, and it is the quickest way to see how Sparrow works. The Quickstart walks through the same steps in the UI and with curl.

To stop:

Terminal window
docker compose down # stop containers
docker compose down -v # stop and delete data
  • Go 1.27.4+ (the version in go.mod)
  • Node.js 22+ (for web UI)
  • PostgreSQL 15+
Terminal window
make build-with-ui
Terminal window
echo "DATABASE_URL=postgres://sparrow:sparrow@localhost:5432/sparrow?sslmode=disable" > .env
# 32 cryptographically random bytes, hex-encoded as 64 chars
echo "SPARROW_ENCRYPTION_KEYS=main=$(openssl rand -hex 32)" >> .env
echo "SPARROW_ENCRYPTION_PRIMARY_KEY_ID=main" >> .env
make migrate # apply schema
make run # go run ./cmd/server, SPARROW_SERVE_UI=true; loads .env automatically

No local Postgres yet? make dev-db starts one (Docker) on the DATABASE_URL above. Without a .env, make run and make migrate default to that database and a dev-only all-zeros keyring; anything set in the shell or .env takes precedence.

For UI hot reload, run make run in one terminal and make run-web (cd web && npm run dev, served at localhost:5173) in another.

To run the full stack in containers instead, rebuilding from source on every change:

Terminal window
make docker-dev # docker compose -f docker-compose.dev.yml up -d --build
make docker-purge # tear down, including volumes

Every release ships cross-compiled binaries on the GitHub releases page — no Go toolchain required. Download the archive for your platform, extract it, and run:

Binaries are built for macOS and Linux (amd64 + arm64) and Windows (amd64). --version prints the version of sparrow-server, sparrow-sinks and sparrow-sources. Each release also carries checksums.txt with a keyless cosign bundle (checksums.txt.sigstore.json), an SPDX SBOM per archive, and the openapi.yaml/openapi.json of that version. Verify the checksums file with:

Terminal window
cosign verify-blob --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github.com/sarathsp06/sparrow/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
sha256sum --check --ignore-missing checksums.txt

vX.Y.Z-rc.N tags are published as pre-releases and never move the latest image tag.

To build from source instead:

Terminal window
make build-all

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry:

Latest Docker release: ghcr.io/sarathsp06/sparrow:latest.

Terminal window
docker pull ghcr.io/sarathsp06/sparrow:latest

The Dockerfile uses a 3-stage build:

  1. Frontend (node:24-alpine): Builds the SvelteKit UI
  2. Backend (golang:1.27.4-alpine): Compiles Go binaries with embedded UI
  3. Runtime (distroless/static-debian12:nonroot): Minimal production image