Skip to main content

Self-Hosted Installation

dbmazz is the open-source CDC daemon that powers EZ-CDC. You can run it standalone for custom deployments.

Overview​

PostgreSQLServer / ContainerConfigurationConnection strings, credentialsdbmazz CDC DaemonStarRocksLogical ReplicationStream Load

Requirements​

System Requirements​

ComponentMinimumRecommended
CPU1 core2+ cores
Memory256 MB512+ MB
Disk1 GB5+ GB
OSLinux (x86_64)Ubuntu 22.04+

Rust Toolchain (for building)​

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version  # Should be 1.70+
cargo --version

Installation Methods​

Option 1: Build from Source​

# Clone the repository
git clone https://github.com/dbmazz/dbmazz.git
cd dbmazz

# Build release binary
cargo build --release

# Binary location
ls -la target/release/dbmazz

Option 2: Download Pre-built Binary​

# Download latest release
curl -L https://github.com/dbmazz/dbmazz/releases/latest/download/dbmazz-linux-x86_64 \
  -o /usr/local/bin/dbmazz

# Make executable
chmod +x /usr/local/bin/dbmazz

# Verify
dbmazz --version

Option 3: Docker​

# Pull image
docker pull ghcr.io/dbmazz/dbmazz:latest

# Run with environment variables
docker run -d \
  --name dbmazz \
  -e SOURCE_URL="postgres://user:pass@postgres:5432/db" \
  -e SINK_URL="http://starrocks:8040" \
  -e SINK_DATABASE="analytics" \
  -e TABLES="public.orders,public.customers" \
  ghcr.io/dbmazz/dbmazz:latest

Basic Setup​

1. Configure Environment​

Create a configuration file:

# /etc/dbmazz/config.env
SOURCE_URL="postgres://cdc_user:password@postgres.example.com:5432/mydb?sslmode=require"
SOURCE_SLOT_NAME="dbmazz_slot"
SOURCE_PUBLICATION_NAME="dbmazz_pub"

SINK_URL="http://starrocks.example.com:8040"
SINK_PORT="9030"
SINK_DATABASE="analytics"
SINK_USER="root"
SINK_PASSWORD=""

TABLES="public.orders,public.customers"
FLUSH_SIZE="10000"
FLUSH_INTERVAL_MS="5000"

GRPC_PORT="50051"

2. Start the Daemon​

# Load environment and run
source /etc/dbmazz/config.env
dbmazz

Or with Docker:

docker run -d \
  --name dbmazz \
  --env-file /etc/dbmazz/config.env \
  -p 50051:50051 \
  ghcr.io/dbmazz/dbmazz:latest

3. Verify Operation​

# Check health via gRPC
grpcurl -plaintext localhost:50051 dbmazz.HealthService/Check

# Expected output
{
  "status": "SERVING",
  "stage": "STAGE_CDC",
  "stageDetail": "Replicating"
}

Systemd Service​

Create a systemd unit file for production:

# /etc/systemd/system/dbmazz.service
[Unit]
Description=dbmazz CDC Daemon
After=network.target

[Service]
Type=simple
User=dbmazz
Group=dbmazz
EnvironmentFile=/etc/dbmazz/config.env
ExecStart=/usr/local/bin/dbmazz
Restart=always
RestartSec=5

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Enable and start:

# Create user
sudo useradd -r -s /bin/false dbmazz

# Set permissions
sudo chown root:dbmazz /etc/dbmazz/config.env
sudo chmod 640 /etc/dbmazz/config.env

# Enable service
sudo systemctl daemon-reload
sudo systemctl enable dbmazz
sudo systemctl start dbmazz

# Check status
sudo systemctl status dbmazz
sudo journalctl -u dbmazz -f

Directory Structure​

Recommended production layout:

/usr/local/bin/
└── dbmazz              # Binary

/etc/dbmazz/
├── config.env          # Configuration
└── ssl/                # SSL certificates (if needed)
    ├── ca.crt
    ├── client.crt
    └── client.key

/var/log/dbmazz/
└── dbmazz.log          # Logs (if file logging enabled)

/var/lib/dbmazz/
└── checkpoints/        # Checkpoint storage (optional)

Verification​

Check Logs​

# Systemd logs
journalctl -u dbmazz -f

# Expected startup sequence
INFO Starting dbmazz CDC daemon
INFO Source: postgres://...@postgres.example.com:5432/mydb
INFO Sink: StarRocks @ starrocks.example.com
INFO Tables: orders, customers
INFO Creating publication dbmazz_pub
INFO Creating replication slot dbmazz_slot
INFO Starting CDC stream from LSN 0/1A3E5F8
INFO Processing events...

Check gRPC API​

# Health check
grpcurl -plaintext localhost:50051 dbmazz.HealthService/Check

# Get status
grpcurl -plaintext localhost:50051 dbmazz.CdcStatusService/GetStatus

# Stream metrics
grpcurl -plaintext -d '{"interval_ms": 2000}' \
  localhost:50051 dbmazz.CdcMetricsService/StreamMetrics

Check Replication​

-- On PostgreSQL: Check slot
SELECT slot_name, active, restart_lsn
FROM pg_replication_slots
WHERE slot_name = 'dbmazz_slot';

-- On StarRocks: Check data
SELECT COUNT(*) FROM orders;
SELECT MAX(_cdc_updated_at) FROM orders;

Troubleshooting Installation​

Binary won't run​

# Check dependencies
ldd /usr/local/bin/dbmazz

# Common fix: Install OpenSSL
sudo apt install libssl-dev

Permission denied​

# Check file permissions
ls -la /usr/local/bin/dbmazz

# Fix permissions
sudo chmod +x /usr/local/bin/dbmazz

Service fails to start​

# Check logs
journalctl -u dbmazz -n 50

# Verify config
cat /etc/dbmazz/config.env

# Test manually
sudo -u dbmazz /usr/local/bin/dbmazz

Next Steps​