Installation Guide

Complete installation instructions for MDDB on all supported platforms.

Docker (Recommended)

The easiest way to run MDDB is with Docker.

Pull and Run

# Pull latest version
docker pull tradik/mddb:latest

# Run server
docker run -d \
  --name mddb \
  -p 11023:11023 \
  -p 11024:11024 \
  -v mddb-data:/data \
  tradik/mddb:latest

# Test it
curl http://localhost:11023/health

Docker Compose

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/tradik/mddb/main/docker-compose.yml

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Hub: https://hub.docker.com/r/tradik/mddb

---

Linux

Ubuntu / Debian

Server:

# Download .deb package
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb

# Install
sudo dpkg -i mddbd-latest-linux-amd64.deb

# Start service
sudo systemctl start mddbd
sudo systemctl enable mddbd

# Check status
sudo systemctl status mddbd

Client:

# Download CLI
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb

# Install
sudo dpkg -i mddb-cli-latest-linux-amd64.deb

# Test
mddb-cli --help
man mddb-cli

RHEL / CentOS / Fedora

Server:

# Download .rpm package
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.rpm

# Install
sudo rpm -i mddbd-latest-linux-amd64.rpm

# Start service
sudo systemctl start mddbd
sudo systemctl enable mddbd

# Check status
sudo systemctl status mddbd

Client:

# Download CLI
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.rpm

# Install
sudo rpm -i mddb-cli-latest-linux-amd64.rpm

# Test
mddb-cli --help

Arch Linux (Manual)

# Download tarball
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.tar.gz

# Extract
tar xzf mddbd-latest-linux-amd64.tar.gz

# Install binary
sudo mv mddbd-latest-linux-amd64/mddbd /usr/local/bin/
sudo chmod +x /usr/local/bin/mddbd

# Run manually or create systemd service (see below)
mddbd

systemd Service (Manual Setup)

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

[Unit]
Description=MDDB - Markdown Database Server
After=network.target

[Service]
Type=simple
User=mddb
Group=mddb
WorkingDirectory=/var/lib/mddb
ExecStart=/usr/local/bin/mddbd
Restart=on-failure
RestartSec=5s

Environment=MDDB_DB_PATH=/var/lib/mddb/mddb.db
Environment=MDDB_HTTP_PORT=11023
Environment=MDDB_GRPC_PORT=11024

[Install]
WantedBy=multi-user.target

Enable and start:

# Create user and directory
sudo useradd -r -s /bin/false mddb
sudo mkdir -p /var/lib/mddb
sudo chown mddb:mddb /var/lib/mddb

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable mddbd
sudo systemctl start mddbd

# Check logs
sudo journalctl -u mddbd -f

---

macOS

Homebrew (Coming Soon)

brew tap tradik/mddb
brew install mddbd mddb-cli

# Run server
mddbd

# Or as service
brew services start mddbd

Manual Installation

Intel Mac (amd64):

# Download
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-darwin-amd64.tar.gz

# Extract
tar xzf mddbd-latest-darwin-amd64.tar.gz

# Install
sudo mv mddbd-latest-darwin-amd64/mddbd /usr/local/bin/
sudo chmod +x /usr/local/bin/mddbd

# Run
mddbd

Apple Silicon (arm64):

# Download
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-darwin-arm64.tar.gz

# Extract
tar xzf mddbd-latest-darwin-arm64.tar.gz

# Install
sudo mv mddbd-latest-darwin-arm64/mddbd /usr/local/bin/
sudo chmod +x /usr/local/bin/mddbd

# Run
mddbd

Client (CLI):

# Intel
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-darwin-amd64.tar.gz
tar xzf mddb-cli-latest-darwin-amd64.tar.gz
sudo mv mddb-cli-latest-darwin-amd64/mddb-cli /usr/local/bin/

# Apple Silicon
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-darwin-arm64.tar.gz
tar xzf mddb-cli-latest-darwin-arm64.tar.gz
sudo mv mddb-cli-latest-darwin-arm64/mddb-cli /usr/local/bin/

# Test
mddb-cli --help

---

FreeBSD

# Download
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-freebsd-amd64.tar.gz

# Extract
tar xzf mddbd-latest-freebsd-amd64.tar.gz

# Install
sudo mv mddbd-latest-freebsd-amd64/mddbd /usr/local/bin/
sudo chmod +x /usr/local/bin/mddbd

# Run
mddbd

---

Windows (WSL2)

MDDB works best on Windows with WSL2 (Windows Subsystem for Linux).

Install WSL2

# In PowerShell (admin)
wsl --install

Install MDDB in WSL2

# Inside WSL2 Ubuntu
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb
sudo dpkg -i mddbd-latest-linux-amd64.deb
sudo systemctl start mddbd

Access from Windows: http://localhost:11023

See also: MCP Configuration for setting up MDDB MCP on WSL

---

Build from Source

Prerequisites

• Go 1.26+ - Download
• Make - Optional, for Makefile commands
• Git - For cloning repository

Clone and Build

# Clone repository
git clone https://github.com/tradik/mddb.git
cd mddb

# Build server
cd services/mddbd
go build -o mddbd .

# Build CLI
cd ../mddb-cli
go build -o mddb-cli .

# Run server
cd ../mddbd
./mddbd

Using Makefile

# Clone repository
git clone https://github.com/tradik/mddb.git
cd mddb

# Build all binaries
make build

# Build and install CLI + man page
make build-cli
make install-all

# Run server
make run

# Run in development mode with hot reload
make install-dev-tools
make dev

# Run tests
make test

# Format code
make fmt

# Run linter
make lint

Generate gRPC Code (if modifying proto files)

# Install protoc and Go plugins
make install-grpc-tools

# Generate code
make generate-proto

---

Post-Installation

Verify Installation

# Check server is running
curl http://localhost:11023/health

# Expected output:
# {"status":"ok","timestamp":1709395200}

# Get statistics
curl http://localhost:11023/v1/stats

# Test CLI
mddb-cli stats

Configure

Environment Variables:

Create /etc/mddb/mddb.env:

MDDB_DB_PATH=/var/lib/mddb/mddb.db
MDDB_HTTP_PORT=11023
MDDB_GRPC_PORT=11024
MDDB_GRAPHQL_ENABLED=true
MDDB_EXTREME=true

# Vector search (optional)
MDDB_EMBEDDING_PROVIDER=openai
MDDB_EMBEDDING_API_KEY=sk-...
MDDB_EMBEDDING_MODEL=text-embedding-3-small
MDDB_EMBEDDING_DIMENSIONS=1536

# Authentication (optional)
MDDB_AUTH_ENABLED=true
MDDB_JWT_SECRET=your-secret-key-here

CLI Configuration:

Create ~/.mddb-cli.yaml:

server_url: http://localhost:11023
grpc_address: localhost:11024
api_mode: rest  # or graphql
token: ""
api_key: ""

Firewall Rules

# Ubuntu/Debian
sudo ufw allow 11023/tcp comment 'MDDB HTTP API'
sudo ufw allow 11024/tcp comment 'MDDB gRPC API'

# CentOS/RHEL/Fedora
sudo firewall-cmd --permanent --add-port=11023/tcp
sudo firewall-cmd --permanent --add-port=11024/tcp
sudo firewall-cmd --reload

Upgrade

Docker:

docker pull tradik/mddb:latest
docker-compose down
docker-compose up -d

Debian/Ubuntu:

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb
sudo dpkg -i mddbd-latest-linux-amd64.deb
sudo systemctl restart mddbd

RHEL/CentOS/Fedora:

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.rpm
sudo rpm -Uvh mddbd-latest-linux-amd64.rpm
sudo systemctl restart mddbd

Manual:

# Backup database first!
cp /var/lib/mddb/mddb.db /var/lib/mddb/mddb.db.backup

# Download new binary
wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.tar.gz
tar xzf mddbd-latest-linux-amd64.tar.gz
sudo mv mddbd-latest-linux-amd64/mddbd /usr/local/bin/

# Restart service
sudo systemctl restart mddbd

---

Troubleshooting

Port Already in Use

# Check what's using the port
sudo lsof -i :11023

# Kill the process or change MDDB port
export MDDB_HTTP_PORT=12023
mddbd

Permission Denied

# Check file permissions
ls -l /var/lib/mddb/

# Fix ownership
sudo chown -R mddb:mddb /var/lib/mddb/

Service Won't Start

# Check logs
sudo journalctl -u mddbd -n 50 --no-pager

# Check status
sudo systemctl status mddbd

# Restart service
sudo systemctl restart mddbd

Binary Not Found

# Check PATH
echo $PATH

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
source ~/.bashrc

---

Uninstall

Docker:

docker-compose down -v
docker rmi tradik/mddb

Debian/Ubuntu:

sudo systemctl stop mddbd
sudo systemctl disable mddbd
sudo dpkg -r mddbd mddb-cli
sudo rm -rf /var/lib/mddb

RHEL/CentOS/Fedora:

sudo systemctl stop mddbd
sudo systemctl disable mddbd
sudo rpm -e mddbd mddb-cli
sudo rm -rf /var/lib/mddb

Manual:

sudo systemctl stop mddbd
sudo systemctl disable mddbd
sudo rm /usr/local/bin/mddbd
sudo rm /usr/local/bin/mddb-cli
sudo rm -rf /var/lib/mddb
sudo rm /etc/systemd/system/mddbd.service
sudo systemctl daemon-reload

---

← Back to README | Next: Quick Start →