Development

meilisearch-cdc is written in Go with a dashboard in plain ES modules (Preact and htm, no build step), embedded in the binary. Tests range from unit tests to a full browser suite against every source.

Build from source

You need Go 1.27.3 or newer (see go.mod). The build is pure Go (no cgo), so it cross-compiles for every platform.

git clone https://github.com/ja7ad/meilisearch-cdc.git
cd meilisearch-cdc
make build                    # bin/meilisearch-cdc
./bin/meilisearch-cdc version # prints "dev"
make run                      # build and run

Release builds set the version with -ldflags "-X github.com/ja7ad/meilisearch-cdc/internal/version.Version=v1.2.3". cmd/meilisearch-cdc/default.pgo is used automatically for profile-guided optimisation (see PGO).

Repository layout

Path	Contents
`cmd/meilisearch-cdc`	The entry point (service, `version`, `admin`).
`internal/source/*`	One package per source, behind a common interface (`Open → Schema → CurrentPosition → Snapshot → Stream → Ack → Close`).
`internal/engine`, `internal/sink`, `internal/transform`	Task supervision and pipelines, the Meilisearch writer, the row-to-document mapping.
`internal/indexmgr`, `internal/diff`	Index settings, drift, shadow rebuilds; schema check and diff.
`internal/api`, `internal/auth`, `internal/mcpserver`, `internal/alerts`, `internal/notify`	REST API, accounts, MCP, alert rules, email/Telegram/webhook delivery.
`internal/admincli`, `internal/adminops`	The operator CLI and the admin socket.
`web/`	The dashboard.
`deploy/`	The demo Compose stack and the full end-to-end environment.
`test/`	End-to-end, load (`bench`), integration and Playwright UI tests.
`docs/`	This website (GitHub Pages), `api.md`, `cli.md`, `e2e.md`, `performance.md`.

Tests

Target	What it runs	Needs
`make test`	Unit tests (`make test-race` with the race detector)	Go
`make lint`	`gofmt` and `go vet` for every build tag	Go
`make integration`	Engine, API, auth, alerts, MCP, connectors and destinations against real services (`-tags integration`)	Docker
`make e2e`	Builds the binary and syncs PostgreSQL, MySQL, MariaDB, MongoDB, DynamoDB and Kafka end to end (`-tags e2e`)	Docker
`make ui-test`	Playwright dashboard tests against a mock API	Node.js
`make ui-real`	Playwright against the real service: single instance (`MEILI_URL`) and multi-instance destinations	Node.js, Docker
`make bench`	Micro benchmarks (transform, batching, encoder, writer)	Go
`make load`	End-to-end load tests with CPU and memory profiles (`BENCH_ROWS=…`)	Docker
`make e2e-env` / `make ui-full`	The full GUI end-to-end environment and suite, below	Docker, Node.js

CI runs make lint with go test -race ./..., make integration, make e2e and make ui-test on every push and pull request.

The full end-to-end environment

deploy/e2e/docker-compose.yml starts every supported source, two Meilisearch instances and a mail catcher. It is used by the full browser suite and is handy for trying the service by hand.

Container	Host port	Notes
PostgreSQL 16	15432	`wal_level=logical`
MySQL 8.4 / MariaDB 11	13306 / 13307	binlog `ROW` + `FULL`
MongoDB 7	27018	replica set `rs0`
DynamoDB Local	18000	streams
CouchDB 3	15984	admin / secret
SQL Server 2022	11433	Agent on, CDC enabled by the lab
CockroachDB 24.3	26258	insecure, rangefeeds enabled by the lab
Redpanda (Kafka)	19092
Redis 7	16379
Meilisearch ×2	17700, 17701	key `e2e-master-key`
Mailpit	SMTP 11025, UI 18025	catches every email

make e2e-env                                   # start and wait for every container
go run ./test/ui/lab serve -seed               # seed 300 products everywhere; :8799 changes data for the tests
make build
(set -a; . deploy/e2e/cdc.env; ./bin/meilisearch-cdc)   # http://127.0.0.1:8780, no MEILI_URL
make ui-full                                   # or: cd test/ui && SLOWMO=150 npx playwright test -c playwright.full.config.mjs --headed

The admin account and other test values are in deploy/e2e/cdc.env. deploy/e2e/reset.sh returns to a clean state (stop the service first): it removes the service data, the e2e_* indexes, inactive replication slots and Mailpit messages, and re-seeds every source. make e2e-env-down removes the containers and volumes.

The suite covers destinations, every source (snapshot of 300 rows, then insert, update and delete), email, members and roles (including the API's 403s), MCP, alerts, every page and tab, the task options (modes, mapping, DLQ, delete guard, resyncs, diff and repair, batch actions, import and export) and every Meilisearch index setting. With REAL_SMTP=1 ALERT_EMAIL=you@example.com the email and alert specs send real mail through the SMTP server saved in Settings. Details: docs/e2e.md.

This documentation

The guide is plain HTML in docs/guide/. Each page's content is its <article class="doc">; the head, navigation, breadcrumbs, pager, search index and sitemap-pages.json are regenerated from docs/guide/assets/nav.js by:

node docs/guide/build-search-index.mjs

Run it after adding or editing a page (add new pages to nav.js first). It needs Node.js 18 or newer and no dependencies.