DMARC Analyzer

Open-source, self-hosted DMARC monitoring for agencies. Point it at the mailbox your rua= reports arrive in and it collects, parses and charts them — unlimited domains, many clients, no per-domain pricing, and the report data never leaves your infrastructure.

Documentation · Install guide · Configuration · Kubernetes

Built with:

• ASP.NET Core + Carter (src/api)
• React + Vite (src/web)
• PostgreSQL (for local/dev and container deployments)

Quick Start (prebuilt image)

Run the analyzer from the published image — no build, no account, your data stays on your machine. Requires Docker.

mkdir dmarc-analyzer && cd dmarc-analyzer
curl -fsSL -o compose.yml https://raw.githubusercontent.com/dmarc-analyzer-net/DmarcAnalyzerApp/main/deploy/compose.yml
# generate the key that encrypts mailbox credentials at rest
echo "DMARC_ENCRYPTION_KEY=$(openssl rand -base64 32)" > .env
docker compose up -d

Then open http://localhost:8080 and create the first admin account (registration is locked after this first-run bootstrap).

What you get: the console on port 8080 and a background loop polling your mailboxes for DMARC reports, both in one container (APP_MODE=all), plus PostgreSQL. Two containers.

Two overlays sit next to that file if the defaults do not fit — they need Compose v2.24 or newer:

Instead of the bundled database or the single container
Use a Postgres you already run	-f compose.yml -f compose.external-db.yml
Run the worker separately	-f compose.yml -f compose.split.yml
Both	add both -f flags

Set COMPOSE_FILE=compose.yml:compose.split.yml in .env and day-to-day use stays docker compose up -d. Every combination reads the same environment variables.

• Image: ghcr.io/dmarc-analyzer-net/dmarc-analyzer, for linux/amd64 + linux/arm64. Mirrored to Docker Hub as dmarcanalyzernet/dmarc-analyzer; GHCR is recommended because it has no anonymous pull rate limits.
• Tags: latest is the most recent release (what the compose file uses), or pin a version such as 0.15.0. edge tracks main and is unreleased — useful for trying a fix early, not for production.
• Next steps: add a client, a domain, and a report source (the inbox your rua= reports arrive in) — see docs/ops/mailbox-sync.md.
• Upgrading: docker compose pull && docker compose up -d (schema migrations run automatically on startup via Database__MigrateOnStartup).

One-Click Deploy

Provider	Deploy	Notes
Render		Provisions the app + a managed Postgres and wires them together automatically via DATABASE_URL — see render.yaml.
Railway		Same shape as Render: a Postgres plugin plus the app image, wired together via DATABASE_URL.
Coolify		Import deploy/compose.yml directly — Coolify runs Compose files natively.
Dokploy		Same file — Dokploy also imports Compose services as-is.

Coolify and Dokploy both need DMARC_ENCRYPTION_KEY and a Postgres connection set the same way as the Quick Start above — see docs/ops/configuration.md for every variable and where it applies.

Repository Layout

• src/api - backend app (api / worker / all modes via APP_MODE)
• src/web - frontend app
• docs/planning - roadmap, backlog, architecture, API contract, and data model
• docs/planning/adr - architecture decision records

Run Locally (Recommended for Development)

Run API and frontend directly for fast iteration and hot reload.

Prerequisites:

• .NET SDK 10
• Node.js 22+

Terminal 1 - API (hot reload):

APP_MODE=api dotnet watch --project src/api

Terminal 2 - Frontend (hot reload):

cd src/web
npm install
npm run dev

App URLs:

• Frontend: http://localhost:5173
• API status: http://localhost:5076/api/v1/system/status

Vite is configured to proxy /api to the local ASP.NET API in development.

Run with Docker Compose

Build and run the single image in two modes (api, worker) plus PostgreSQL:

# once per clone — the key that encrypts mailbox credentials at rest is not in
# the repo, so compose refuses to start until you generate your own
echo "DMARC_ENCRYPTION_KEY=$(openssl rand -base64 32)" > .env
docker compose up -d --build

Keep that key once you have added a report source: changing it makes every stored mailbox password undecryptable.

If the build fails during dotnet restore with NU1004, packages.lock.json does not match the project's package references. The image build restores in locked mode deliberately — a stale lockfile should stop the build rather than silently resolve different transitive versions into the image — so regenerate it and commit the change:

dotnet restore src/api/DmarcAnalyzer.Api.csproj --force-evaluate

Services:

• API: http://localhost:8080
• Postgres: localhost:5432
• Worker: same image, APP_MODE=worker

Stop:

docker compose down

Single-Image Runtime Model

The same container image (dmarc-analyzer-net:dev) runs in three modes:

• APP_MODE=api - serves API + static React build (wwwroot)
• APP_MODE=worker - runs background worker host
• APP_MODE=all - both in one process; the simplest way to self-host on a single machine
• APP_MODE=migrate - applies pending migrations and exits; for orchestrators that need the schema settled before any app pod starts

Any other value fails startup rather than falling back to api, so a typo cannot leave you with a container that serves the console and ingests nothing.

Useful Commands

From repo root:

dotnet build DmarcAnalyzerApp.slnx

From src/web:

npm run build

API Request File (.http)

Use http/api.http with VS Code REST Client or JetBrains HTTP client to run API requests quickly during development.

• File: http/api.http
• Default base URL: http://localhost:5076

Key API Endpoints

Everything lives under /api/v1; full contract in docs/planning/api-contract.md. A sample to get oriented:

• GET /api/v1/system/status — health/version
• GET /api/v1/domains, GET /api/v1/clients — the core resources
• GET /api/v1/analytics/summary — dashboard-level pass/fail totals
• GET /api/v1/analytics/domains/{domainId}/sources — per-domain sending sources
• GET /api/v1/alerts — configured alert rules
• GET /api/v1/mailbox-health, GET /api/v1/mailbox-sync-runs, POST /api/v1/report-sources/{id}/sync — mailbox ingestion status/trigger

Try these against a running instance with http/api.http (see above).

Mailbox Sync Monitoring

Key operational endpoints:

• GET /api/v1/mailbox-health
• GET /api/v1/mailbox-sync-runs
• POST /api/v1/report-sources/{id}/sync (manual trigger)

Ops runbook:

• docs/ops/configuration.md — every environment variable, and the same set in every deployment shape. Kept true by ConfigurationContractTests.
• docs/ops/migrating-a-running-instance.md — bringing a running instance onto a newer image, including why a green healthcheck does not prove the schema is current.
• docs/ops/upgrading-postgresql.md — the PostgreSQL 17 → 18 migration. A major version cannot upgrade in place; this is the dump-and-restore window.
• docs/ops/aws-rds-iam.md — Postgres on AWS with no database password: IAM tokens, which CA to verify against (RDS endpoint vs RDS Proxy), and the Compose and Helm recipe.
• docs/ops/mailbox-sync.md
• docs/ops/oidc-zitadel.md — and the per-provider guides it links, including docs/ops/oidc-entra.md, which Microsoft Entra ID needs rather than merely benefits from.
• docs/ops/release.md

Planning Docs

Start here before implementation details:

• docs/planning/architecture.md
• docs/planning/api-contract.md
• docs/planning/data-model.md
• docs/planning/roadmap.md

Contributing

Pull requests are welcome, and there is no CLA to sign — see CONTRIBUTING.md for how work gets merged and what review will ask of you. AGENTS.md is the orientation map for the codebase itself.

Found a security problem? Do not open a public issue — see SECURITY.md.