MDDB Deployment Guide

Production Deployment

System Requirements

Minimum:

  • CPU: 1 core
  • RAM: 512 MB
  • Disk: 1 GB + data storage
  • OS: Linux, macOS, or Windows

Recommended:

  • CPU: 2+ cores
  • RAM: 2 GB
  • Disk: SSD with 10 GB+ free space
  • OS: Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+)

Building for Production

cd services/mddbd
go build -ldflags="-s -w" -o mddbd . make build GOOS=linux GOARCH=amd64 go build -o mddbd-linux .

Systemd Service

Create /etc/systemd/system/mddb.service:

[Unit]
Description=MDDB Markdown Database Server
After=network.target [Service]
Type=simple
User=mddb
Group=mddb
WorkingDirectory=/opt/mddb
Environment="MDDB_ADDR=:11023"
Environment="MDDB_MODE=wr"
Environment="MDDB_PATH=/var/lib/mddb/mddb.db"
ExecStart=/opt/mddb/mddbd
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mddb NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mddb [Install]
WantedBy=multi-user.target

Enable and start:

sudo useradd -r -s /bin/false mddb
sudo mkdir -p /opt/mddb /var/lib/mddb
sudo chown mddb:mddb /var/lib/mddb sudo cp mddbd /opt/mddb/
sudo chown mddb:mddb /opt/mddb/mddbd
sudo chmod +x /opt/mddb/mddbd sudo systemctl daemon-reload
sudo systemctl enable mddb
sudo systemctl start mddb sudo systemctl status mddb

Docker Deployment

Create Dockerfile:

FROM golang:1.26-alpine AS builder WORKDIR /build
COPY services/mddbd/go.mod services/mddbd/go.sum ./
RUN go mod download COPY services/mddbd/ ./
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o mddbd . FROM alpine:latest RUN apk --no-cache add ca-certificates
RUN addgroup -S mddb && adduser -S mddb -G mddb WORKDIR /app
COPY --from=builder /build/mddbd . RUN mkdir -p /data && chown mddb:mddb /data
USER mddb EXPOSE 11023
VOLUME ["/data"] ENV MDDB_ADDR=":11023"
ENV MDDB_MODE="wr"
ENV MDDB_PATH="/data/mddb.db" CMD ["./mddbd"]

Build and run:

docker build -t mddb:latest . docker run -d \ --name mddb \ -p 11023:11023 \ -v mddb-data:/data \ --restart unless-stopped \ mddb:latest docker logs -f mddb

Docker Compose

Create docker-compose.yml:

services: mddb: build: . container_name: mddb ports: - "11023:11023" volumes: - mddb-data:/data environment: - MDDB_ADDR=:11023 - MDDB_MODE=wr - MDDB_PATH=/data/mddb.db restart: unless-stopped healthcheck: test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:11023/v1/search"] interval: 30s timeout: 10s retries: 3 start_period: 40s volumes: mddb-data:

Run:

docker-compose up -d

Reverse Proxy Setup

Nginx

upstream mddb { server localhost:11023;
} server { listen 80; server_name mddb.example.com; # Redirect to HTTPS return 301 https://$server_name$request_uri;
} server { listen 443 ssl http2; server_name mddb.example.com; ssl_certificate /etc/letsencrypt/live/mddb.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mddb.example.com/privkey.pem; # Security headers add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; # Rate limiting limit_req_zone $binary_remote_addr zone=mddb_limit:10m rate=10r/s; limit_req zone=mddb_limit burst=20 nodelay; location / { proxy_pass http://mddb; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Timeouts proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; }
}

Caddy

mddb.example.com { reverse_proxy localhost:11023 # Rate limiting rate_limit { zone dynamic { key {remote_host} events 100 window 1m } }
}

Backup Strategy

Automated Backups

#!/bin/bash BACKUP_DIR="/backups/mddb"
RETENTION_DAYS=30
DATE=$(date +%Y-%m-%d-%H%M%S) mkdir -p ${BACKUP_DIR} curl -s "http://localhost:11023/v1/backup?to=${BACKUP_DIR}/backup-${DATE}.db" find ${BACKUP_DIR} -name "backup-*.db" -mtime +1 -exec gzip {} \; find ${BACKUP_DIR} -name "backup-*.db.gz" -mtime +${RETENTION_DAYS} -delete echo "$(date): Backup completed - backup-${DATE}.db" >> /var/log/mddb-backup.log

Add to crontab:

0 2 * * * /opt/mddb/backup.sh

Offsite Backup

#!/bin/bash
aws s3 sync /backups/mddb s3://my-bucket/mddb-backups/ \ --storage-class STANDARD_IA \ --exclude "*" \ --include "backup-*.db.gz" rsync -avz /backups/mddb/ backup-server:/backups/mddb/

Monitoring

Health Check Script

#!/bin/bash ENDPOINT="http://localhost:11023/v1/search"
TIMEOUT=5 response=$(curl -s -o /dev/null -w "%{http_code}" --max-time ${TIMEOUT} \ -X POST ${ENDPOINT} \ -H 'Content-Type: application/json' \ -d '{"collection":"_health","limit":1}') if [ "$response" = "200" ] || [ "$response" = "400" ]; then echo "OK" exit 0
else echo "FAIL: HTTP $response" exit 1
fi

Prometheus Metrics (Future)

scrape_configs: - job_name: 'mddb' static_configs: - targets: ['localhost:11023']

Performance Tuning

OS Tuning

echo "mddb soft nofile 65536" >> /etc/security/limits.conf
echo "mddb hard nofile 65536" >> /etc/security/limits.conf cat >> /etc/sysctl.conf <<EOF
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
EOF sysctl -p

Database Optimization

curl -X POST http://localhost:11023/v1/truncate \ -H 'Content-Type: application/json' \ -d '{"collection":"blog","keepRevs":10,"dropCache":true}'

Security Hardening

Firewall Rules

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable iptables -A INPUT -p tcp --dport 22 -j ACCEPT
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -j DROP

API Authentication (Nginx)

location / { # Basic auth auth_basic "MDDB API"; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://mddb;
}

Create password file:

htpasswd -c /etc/nginx/.htpasswd admin

Troubleshooting

Check Logs

sudo journalctl -u mddb -f docker logs -f mddb tail -f /var/log/mddb.log

Common Issues

Database locked:

ps aux | grep mddbd sudo systemctl stop mddb

High memory usage:

ls -lh /var/lib/mddb/mddb.db curl -X POST http://localhost:11023/v1/truncate \ -H 'Content-Type: application/json' \ -d '{"collection":"blog","keepRevs":5}'

Slow queries:

  • Add metadata indices
  • Use pagination
  • Optimize filters
  • Consider caching layer

Scaling

Vertical Scaling

  • Increase CPU/RAM
  • Use SSD storage
  • Optimize OS settings

Horizontal Scaling

  • Read replicas (file-based replication)
  • Load balancer for reads
  • Single write instance
  • Consider sharding by collection

Read Replicas

0 */6 * * * curl "http://localhost:11023/v1/backup?to=/replication/mddb.db" */5 * * * * rsync -avz primary:/replication/mddb.db /var/lib/mddb/mddb.db

Run replicas in read-only mode:

MDDB_MODE="read" MDDB_ADDR=":11024" ./mddbd