Configuration reference

Every setting is optional: with none, the service listens on :8080, stores its state in ./data and is configured in the dashboard. Settings come from environment variables and command-line flags; a flag wins over its variable.

All settings

Environment variable	Flag	Default	Description
`CDC_LISTEN`	`-listen`	`:8080`	HTTP listen address for the dashboard, API, `/metrics` and `/mcp`.
`CDC_DATA_DIR`	`-data-dir`	`./data`	Directory of the state database `cdc.db`, the generated `secret.key` and the admin socket `admin.sock`. Created with mode `0700`.
`MEILI_URL`	`-meili-url`	empty	Pins the service to this Meilisearch instance (single-instance mode). Leave it empty to manage destinations in the dashboard.
`MEILI_API_KEY` (falls back to `MEILI_MASTER_KEY`)	`-meili-api-key`	empty	API key of the `MEILI_URL` instance. Secret: also `MEILI_API_KEY_FILE`.
`MEILI_GZIP`	`-meili-gzip`	`true`	Gzip request bodies sent to the `MEILI_URL` instance.
`MEILI_TIMEOUT`	`-meili-timeout`	`30s`	Request timeout for the `MEILI_URL` instance.
`CDC_ADMIN_TOKEN`	`-admin-token`	empty	Static bearer token with the admin role, for scripts, Prometheus and webhook pushers (details). Only its hash is kept in memory. Secret: also `CDC_ADMIN_TOKEN_FILE`.
`CDC_SECRET_KEY`	`-secret-key`	generated in `secret.key`	Key that encrypts stored credentials: a base64 string of exactly 32 bytes is used as the AES-256 key, anything else is a passphrase stretched with argon2id. Secret: also `CDC_SECRET_KEY_FILE`.
`CDC_SECRET_KEY_PREVIOUS`	none	empty	An older key that can still decrypt; used for key rotation. Secret: also `CDC_SECRET_KEY_PREVIOUS_FILE`.
`CDC_TASKS_FILE`	`-tasks`	empty	YAML or JSON file of tasks applied at startup (declarative tasks); `${VAR}` is expanded from the environment.
`CDC_ADMIN_EMAIL`	none	empty	With `CDC_ADMIN_PASSWORD`, creates the first admin at startup when no user exists (instead of the setup page). Its name is `Administrator`.
`CDC_ADMIN_PASSWORD`	none	empty	Password of that first admin (8 to 128 characters). Secret: also `CDC_ADMIN_PASSWORD_FILE`.
`CDC_PUBLIC_URL`	`-public-url`	empty	Dashboard base URL used in emailed links. The URL saved in Settings → Email takes precedence; without both, the request's origin is used.
`CDC_COOKIE_SECURE`	`-cookie-secure`	`false`	Always set the `Secure` flag on the session cookie (behind a TLS-terminating proxy).
`CDC_TRUST_PROXY`	`-trust-proxy`	`false`	Trust `X-Forwarded-For` and `X-Forwarded-Proto` from a reverse proxy.
`CDC_LOG_LEVEL`	`-log-level`	`info`	`debug`, `info`, `warn` or `error`.
`CDC_LOG_FORMAT`	`-log-format`	`text`	`text` or `json`. Logs go to standard error.
`CDC_DISABLE_UI`	`-disable-ui`	`false`	Do not serve the dashboard; the API, metrics and MCP keep working.
`CDC_STOP_TIMEOUT`	`-stop-timeout`	`20s`	How long a stopping task may drain pending batches before they are aborted (and replayed on the next start). The whole shutdown waits up to this plus 10 seconds.
`CDC_PPROF`	`-pprof`	`false`	Expose `/debug/pprof/` to signed-in users (pprof).
`CDC_ALERT_INTERVAL`	`-alert-interval`	`5s`	How often alert rules are evaluated.

Value formats

Booleans accept 1, t, true, 0, f, false (any case). An unparsable value is ignored and the default applies.
Durations use Go syntax: 500ms, 30s, 2m, 1h30m. An unparsable value is ignored and the default applies.
Flags use one or two dashes: -listen :9000 and --listen=:9000 are the same.

Output of `meilisearch-cdc --help`

Usage of meilisearch-cdc:
  -admin-token string
    	bearer token protecting the API and UI (CDC_ADMIN_TOKEN)
  -alert-interval duration
    	how often alert rules are evaluated (CDC_ALERT_INTERVAL) (default 5s)
  -cookie-secure
    	always set the Secure cookie flag (CDC_COOKIE_SECURE)
  -data-dir string
    	directory of the state database (CDC_DATA_DIR) (default "./data")
  -disable-ui
    	do not serve the dashboard (CDC_DISABLE_UI)
  -listen string
    	HTTP listen address (CDC_LISTEN) (default ":8080")
  -log-format string
    	text or json (CDC_LOG_FORMAT) (default "text")
  -log-level string
    	debug, info, warn, error (CDC_LOG_LEVEL) (default "info")
  -meili-api-key string
    	Meilisearch API key (MEILI_API_KEY)
  -meili-gzip
    	gzip request bodies sent to Meilisearch (MEILI_GZIP) (default true)
  -meili-timeout duration
    	Meilisearch request timeout (MEILI_TIMEOUT) (default 30s)
  -meili-url string
    	pin the service to this Meilisearch instance (MEILI_URL); leave empty to manage destinations in the dashboard
  -pprof
    	expose /debug/pprof to admins (CDC_PPROF)
  -public-url string
    	dashboard base URL used in emailed links (CDC_PUBLIC_URL)
  -secret-key string
    	passphrase encrypting stored credentials (CDC_SECRET_KEY)
  -stop-timeout duration
    	how long a stopping task may drain (CDC_STOP_TIMEOUT) (default 20s)
  -tasks string
    	YAML/JSON file of tasks applied at startup (CDC_TASKS_FILE)
  -trust-proxy
    	trust X-Forwarded-For/Proto from a reverse proxy (CDC_TRUST_PROXY)

The defaults shown are the effective values, so a variable already set in the environment appears as the default. meilisearch-cdc version (also -version, --version) prints the version, and meilisearch-cdc admin … runs the admin CLI.

Secrets and `*_FILE`

Five settings are secrets. Each can be read from a file whose path is in <NAME>_FILE, which is how Docker and Kubernetes mount secrets. Trailing \r and \n are removed. When the variable <NAME>_FILE is set and the file is readable, it wins over <NAME>.

Secret	File variant
`CDC_SECRET_KEY`	`CDC_SECRET_KEY_FILE`
`CDC_SECRET_KEY_PREVIOUS`	`CDC_SECRET_KEY_PREVIOUS_FILE`
`MEILI_API_KEY`	`MEILI_API_KEY_FILE`
`CDC_ADMIN_TOKEN`	`CDC_ADMIN_TOKEN_FILE`
`CDC_ADMIN_PASSWORD`	`CDC_ADMIN_PASSWORD_FILE`

MEILI_MASTER_KEY (the fallback for MEILI_API_KEY) has no file variant.

Credentials you enter in the dashboard (connector passwords, DynamoDB secret keys, Meilisearch API keys, the SMTP password, the Telegram bot token) are stored encrypted in cdc.db with AES-256-GCM and never returned by the API. See Secrets encryption.

Single-instance mode vs. destinations in the dashboard

meilisearch-cdc can write to many Meilisearch instances (destinations). How they are managed depends on MEILI_URL:

	`MEILI_URL` unset (default)	`MEILI_URL` set
Destinations	Created, edited and deleted in the dashboard or the API. The first one becomes the default.	One destination with the id `default`, marked `managedByEnv`. Its URL and key come from the environment and are refreshed at every start.
Other stored destinations	Visible and usable.	Hidden.
Creating, deleting or switching destinations	Allowed (admin).	Refused with `409`: `single instance mode: MEILI_URL is set, so the service writes only to that Meilisearch instance; unset it to manage destinations in the dashboard`.
Dashboard	Destinations page with add/edit.	`GET /api/v1/auth/config` reports `"singleDestination": true` and the UI hides destination management.

The service logs single instance mode: writing only to MEILI_URL at startup. To switch back to managed destinations, unset MEILI_URL and restart; the destinations stored earlier reappear.

Logging

Logs are structured (Go log/slog) and written to standard error. Every line carries the version attribute.

time=2026-10-26T23:41:57.571+03:30 level=INFO msg=listening version=v1.2.3 addr=127.0.0.1:8080 meilisearch=""

With CDC_LOG_FORMAT=json each line is a JSON object, convenient for Loki, Elasticsearch or CloudWatch. Per-task activity (snapshot started, streaming from a position, retries, holds) is also kept in memory, the last 1,000 entries per task, and shown on the task's Logs tab and streamed live.

pprof

With CDC_PPROF=true the Go profiler is served at /debug/pprof/ (index, profile, trace, symbol, cmdline). It requires authentication like the API: a session cookie or the admin token.

curl -H "Authorization: Bearer $CDC_ADMIN_TOKEN" -o cpu.pprof \
  "http://127.0.0.1:8080/debug/pprof/profile?seconds=30"
go tool pprof -http=:0 cpu.pprof

Who can read profiles

The flag's help text says "admins", but the route is registered as a read (GET) route, and reads are allowed to every signed-in role, viewers included. Enable pprof only while you need it.

Metrics

Prometheus metrics are always served at /metrics and need authentication. The metric names and labels are listed under Monitoring.

Other environment variables

Variable	Effect
`GOMEMLIMIT`	Go runtime soft memory limit, e.g. `400MiB`. Set it to about 80% of a container's memory limit. See Performance.
`GOGC`	Garbage collector target (default 100). Higher values trade memory for less GC CPU.
`AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_PROFILE`, …	Used by DynamoDB connectors that leave the region or keys empty (the default AWS credential chain).
Any variable named in a tasks file	Expanded as `${VAR}` in `CDC_TASKS_FILE`.

Configuration reference

All settings

Value formats

Output of meilisearch-cdc --help

Secrets and *_FILE

Single-instance mode vs. destinations in the dashboard

Logging

pprof

Metrics

Other environment variables

Output of `meilisearch-cdc --help`

Secrets and `*_FILE`