Install the binary

meilisearch-cdc is one static binary. Install it, give it a data directory that only its own user can read, and let your init system keep it running.

What the service needs

A data directory (CDC_DATA_DIR, default ./data). It holds cdc.db (the state database), secret.key (unless you set CDC_SECRET_KEY) and, while the service runs, the admin socket admin.sock. The service creates it with mode 0700.
One HTTP port (CDC_LISTEN, default :8080) for the dashboard, the REST API, /metrics and /mcp.
Outbound access to your sources and Meilisearch instances.
A single instance per data directory. The state database is locked by the running process, so run exactly one replica per data directory.

Download and verify the archive for your platform as described in the quick start. All settings are optional; see the configuration reference.

Linux with systemd

Install the binary and create a user

VERSION=1.2.3 ARCH=amd64
NAME=meilisearch-cdc_${VERSION}_linux_${ARCH}
tar -xzf ${NAME}.tar.gz
sudo install -m 0755 ${NAME}/meilisearch-cdc /usr/local/bin/meilisearch-cdc

# A system user without a login shell, and its data directory.
sudo useradd --system --home-dir /var/lib/meilisearch-cdc --shell /usr/sbin/nologin meilisearch-cdc
sudo install -d -o meilisearch-cdc -g meilisearch-cdc -m 0700 /var/lib/meilisearch-cdc
sudo install -d -o root -g meilisearch-cdc -m 0750 /etc/meilisearch-cdc

Environment file

Keep settings in an environment file readable only by root and the service group:

# /etc/meilisearch-cdc/cdc.env  (chmod 0640, owner root:meilisearch-cdc)
CDC_DATA_DIR=/var/lib/meilisearch-cdc
CDC_LISTEN=127.0.0.1:8080
CDC_LOG_FORMAT=json
# Behind an HTTPS reverse proxy (see the reverse proxy page):
CDC_PUBLIC_URL=https://cdc.example.com
CDC_TRUST_PROXY=true
CDC_COOKIE_SECURE=true

Secrets can be kept out of the environment with the *_FILE variants, for example CDC_SECRET_KEY_FILE=/etc/meilisearch-cdc/secret-key. See Secrets and *_FILE.

Unit file

# /etc/systemd/system/meilisearch-cdc.service
[Unit]
Description=meilisearch-cdc: change data capture into Meilisearch
Documentation=https://meilicdc.javad.dev/guide/
Wants=network-online.target
After=network-online.target

[Service]
User=meilisearch-cdc
Group=meilisearch-cdc
EnvironmentFile=/etc/meilisearch-cdc/cdc.env
ExecStart=/usr/local/bin/meilisearch-cdc
Restart=on-failure
RestartSec=5
# SIGTERM drains running tasks for CDC_STOP_TIMEOUT (20s), then the
# service allows 10 more seconds to shut down: keep this above the sum.
TimeoutStopSec=45
UMask=0077
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/meilisearch-cdc

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now meilisearch-cdc
sudo systemctl status meilisearch-cdc
journalctl -u meilisearch-cdc -f

The service stops cleanly on SIGTERM or SIGINT: running tasks flush and confirm pending batches for up to CDC_STOP_TIMEOUT, and anything unconfirmed is replayed from the checkpoint on the next start.

Using the admin CLI on the server

Run the admin CLI as the service user with the same environment, so it finds the same data directory and key:

sudo -u meilisearch-cdc env $(sudo grep -v '^#' /etc/meilisearch-cdc/cdc.env | xargs) \
  meilisearch-cdc admin users list

macOS

There is no Homebrew formula; install the release binary and run it with launchd. Use darwin_arm64 on Apple silicon and darwin_amd64 on Intel Macs.

VERSION=1.2.3 ARCH=arm64
NAME=meilisearch-cdc_${VERSION}_darwin_${ARCH}
tar -xzf ${NAME}.tar.gz
sudo install -m 0755 ${NAME}/meilisearch-cdc /usr/local/bin/meilisearch-cdc
# Downloaded with a browser? Remove the quarantine flag:
sudo xattr -d com.apple.quarantine /usr/local/bin/meilisearch-cdc 2>/dev/null || true
mkdir -p "$HOME/Library/Application Support/meilisearch-cdc" "$HOME/Library/Logs"

A per-user launch agent that starts at login and restarts on failure:

<?xml version="1.0" encoding="UTF-8"?>
<!-- ~/Library/LaunchAgents/com.github.ja7ad.meilisearch-cdc.plist -->
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.github.ja7ad.meilisearch-cdc</string>
  <key>ProgramArguments</key>
  <array><string>/usr/local/bin/meilisearch-cdc</string></array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>CDC_DATA_DIR</key><string>/Users/you/Library/Application Support/meilisearch-cdc</string>
    <key>CDC_LISTEN</key><string>127.0.0.1:8080</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
  <key>ExitTimeOut</key><integer>45</integer>
  <key>StandardOutPath</key><string>/Users/you/Library/Logs/meilisearch-cdc.log</string>
  <key>StandardErrorPath</key><string>/Users/you/Library/Logs/meilisearch-cdc.log</string>
</dict>
</plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.ja7ad.meilisearch-cdc.plist
launchctl kickstart -k gui/$(id -u)/com.github.ja7ad.meilisearch-cdc   # restart
launchctl bootout gui/$(id -u)/com.github.ja7ad.meilisearch-cdc        # stop and unload

Keep the data directory path short

The admin socket lives at <data-dir>/admin.sock, and Unix socket paths are limited to about 100 characters. With a longer path the service logs a warning and runs without the socket. In our tests on macOS the CLI then also failed while the service was stopped (connect: invalid argument), so prefer a short absolute path such as /usr/local/var/meilisearch-cdc, or run the CLI from inside the data directory with CDC_DATA_DIR=..

Windows

Unzip the archive and run meilisearch-cdc.exe from a terminal. The data directory defaults to .\data next to where you start it, so set it explicitly:

$env:CDC_DATA_DIR = "C:\ProgramData\meilisearch-cdc"
$env:CDC_LISTEN = "127.0.0.1:8080"
& "C:\Program Files\meilisearch-cdc\meilisearch-cdc.exe"

Run as a Windows service

The binary does not implement the Windows Service Control Manager protocol, so sc.exe create alone would time out when starting it (error 1053). Use a service wrapper such as NSSM, which starts the executable and stops it on service shutdown:

nssm install meilisearch-cdc "C:\Program Files\meilisearch-cdc\meilisearch-cdc.exe"
nssm set meilisearch-cdc AppEnvironmentExtra CDC_DATA_DIR=C:\ProgramData\meilisearch-cdc CDC_LISTEN=127.0.0.1:8080
nssm set meilisearch-cdc AppStdout C:\ProgramData\meilisearch-cdc\service.log
nssm set meilisearch-cdc AppStderr C:\ProgramData\meilisearch-cdc\service.log
nssm set meilisearch-cdc AppStopMethodConsole 45000
nssm start meilisearch-cdc

Restrict C:\ProgramData\meilisearch-cdc to the service account and administrators: it contains the encryption key. On Windows the admin CLI has no hidden password prompt; use --generate or --password-file.

Check that it runs

curl -s http://127.0.0.1:8080/healthz
# ok
curl -s http://127.0.0.1:8080/api/v1/health
# {"meilisearch":{"error":"no Meilisearch destination is configured: add one first","status":"unconfigured"},"status":"ok"}

/healthz answers ok as long as the process serves HTTP, which suits liveness probes. /api/v1/health also reports the default Meilisearch destination. Both need no authentication.

Reverse proxy and TLS before exposing the dashboard.
Backups and upgrades.