Install Sigmatic

The Sigmatic repository owns the supported single-product install. Its root Compose file starts identity, a gateway, PostgreSQL, PgBouncer, separate cache and queue Redis services, and Sigmatic’s backend, workers and frontend. Bring an existing OpenSearch 3.x cluster (tested 3.9.0); 2.x isn’t supported. Pull pagination uses the PIT _shard_doc tie-breaker. The stack doesn’t include OpenSearch. The 1.0 version-range decision tracks whether 2.x support will be added.

Before you start

You need Docker Engine with Compose, access to the Sigmatic repository and images, and an OpenSearch URL reachable from the containers. Use a dedicated OpenSearch credential with the minimum grants. It doesn’t need permission to write raw events into your source indices.

Note

Repositories and images are private for now. Clone with an account that has access, and authenticate Docker to GHCR before pulling private images. Private registry access covers that setup. CI and Dependabot use package Actions access grants; those grants don’t replace your own Docker credentials.

Install

git clone https://github.com/veltrosecurity/sigmatic.git
cd sigmatic
cp .env.example .env

Edit .env before starting. Set PUBLIC_BASE_URL to the public origin, VELTRO_BOOTSTRAP_ADMIN_EMAIL to your first admin, and OPENSEARCH_SEED_URL to your existing cluster. Every empty secret has a generator beside it. Keep SIGMATIC_ENCRYPTION_KEY stable: the app derives its Fernet key from that secret. Empty required values stop Compose before boot.

Supply OPENSEARCH_SEED_USERNAME and OPENSEARCH_SEED_PASSWORD if your cluster requires them. Certificate verification defaults to true. Set OPENSEARCH_SEED_VERIFY_CERTS=false only for a private test cluster.

docker compose up -d
docker compose logs identity

Only the gateway publishes a port. Put TLS in front of it when exposing it publicly. The public origin must agree with PUBLIC_BASE_URL.

Add your proxy’s exact address or CIDR as set_real_ip_from in docker/gateway/trusted-proxies.conf, and have the proxy overwrite X-Forwarded-For with the real client address. Restart the gateway after edits. No proxy is trusted by default. This keeps shipper IP allowlists working behind TLS without trusting forwarding headers from arbitrary clients.

Sign in

Identity logs the first-admin invite. Open that link, set a password and visit /sigmatic/. Identity serves sign-in at /; Sigmatic has no separate login. The first admin has access to Sigmatic. Grant other people their Sigmatic roles in Settings > Users.

The one-shot identity-init service prepares identity’s schema, signing keys, workload credential and TOTP keyring before runtime services start. Keep its persistent keyring and database volumes across restarts. Don’t remove the keyring to repair a startup failure: identity refuses to generate a replacement when the database already contains TOTP-encrypted data.

OpenSearch seeding happens only when no connection is stored. Later changes belong in Sigmatic Settings; editing the seed won’t overwrite your saved connection.

Send logs

Shippers use the gateway’s bearer-auth ingest API at /api/logs/. The dedicated ingest listener stays private. Send logs covers request formats and source tokens.

Normal push doesn’t index raw events into your source-pattern indices. Queued events persist in Redis Streams while workers process them. Matches retain event evidence inside Sigmatic-owned alert documents. Failed events can remain in the dead-letter stream, and shadow evaluation keeps bounded event snapshots. Send a separate copy to OpenSearch if you need a raw-event archive. See push storage for the full contract.

The Data Source trace test writes a marked probe into a source-matching index and suppresses alerts for it. It needs a separate source-write grant and isn’t a substitute for sending a push event.

Check the install

docker compose ps
docker compose logs identity-init
curl --fail "$PUBLIC_BASE_URL/sigmatic/api/health/ready"

Export PUBLIC_BASE_URL in your shell for the curl command. Readiness returns 200 only when PostgreSQL, cache Redis, queue Redis and configured OpenSearch are available; failures return 503. The old /health endpoint has a weaker contract and isn’t the install’s readiness check.

Both identity services use the same literal released identity:X.Y.Z image pin, starting at ghcr.io/veltrosecurity/identity:0.37.1. Dependabot proposes identity bumps alone, and the repository’s compose-boot check tests the checkout’s production images against that pin. Maintainers must grant veltrosecurity/sigmatic Actions read access on both the veltro-identity and identity GHCR packages. Don’t add a registry token for CI or Dependabot.

docker-compose.dev.yml and docker-compose.pull.yml are explicitly selected development/CI fixtures; neither starts identity. Use the root file for this install.

Existing Veltro suite installations continue to use the suite installer and its lifecycle commands. This product-owned install doesn’t change those stacks. For two or more products, see Install Veltro.