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

docker pull tradik/mddb:latest

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

curl http://localhost:11023/health

Docker Compose

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

docker-compose up -d

docker-compose logs -f

docker-compose down

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

---

Linux

Ubuntu / Debian

Server:

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
sudo systemctl enable mddbd

sudo systemctl status mddbd

Client:

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

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

mddb-cli --help
man mddb-cli

RHEL / CentOS / Fedora

Server:

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

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

sudo systemctl start mddbd
sudo systemctl enable mddbd

sudo systemctl status mddbd

Client:

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

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

mddb-cli --help

Arch Linux (Manual)

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/
sudo chmod +x /usr/local/bin/mddbd

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:

sudo useradd -r -s /bin/false mddb
sudo mkdir -p /var/lib/mddb
sudo chown mddb:mddb /var/lib/mddb

sudo systemctl daemon-reload
sudo systemctl enable mddbd
sudo systemctl start mddbd

sudo journalctl -u mddbd -f

---

macOS

Homebrew (Coming Soon)

brew tap tradik/mddb
brew install mddbd mddb-cli

mddbd

brew services start mddbd

Manual Installation

Intel Mac (amd64):

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

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

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

mddbd

Apple Silicon (arm64):

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

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

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

mddbd

Client (CLI):

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/

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/

mddb-cli --help

---

FreeBSD

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

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

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

mddbd

---

Windows (WSL2)

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

Install WSL2

wsl --install

Install MDDB in WSL2

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

git clone https://github.com/tradik/mddb.git
cd mddb

cd services/mddbd
go build -o mddbd .

cd ../mddb-cli
go build -o mddb-cli .

cd ../mddbd
./mddbd

Using Makefile

git clone https://github.com/tradik/mddb.git
cd mddb

make build

make build-cli
make install-all

make run

make install-dev-tools
make dev

make test

make fmt

make lint

Generate gRPC Code (if modifying proto files)

make install-grpc-tools

make generate-proto

---

Post-Installation

Verify Installation

curl http://localhost:11023/health


curl http://localhost:11023/v1/stats

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

MDDB_EMBEDDING_PROVIDER=openai
MDDB_EMBEDDING_API_KEY=sk-...
MDDB_EMBEDDING_MODEL=text-embedding-3-small
MDDB_EMBEDDING_DIMENSIONS=1536

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

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

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:

cp /var/lib/mddb/mddb.db /var/lib/mddb/mddb.db.backup

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/

sudo systemctl restart mddbd

---

Troubleshooting

Port Already in Use

sudo lsof -i :11023

export MDDB_HTTP_PORT=12023
mddbd

Permission Denied

ls -l /var/lib/mddb/

sudo chown -R mddb:mddb /var/lib/mddb/

Service Won't Start

sudo journalctl -u mddbd -n 50 --no-pager

sudo systemctl status mddbd

sudo systemctl restart mddbd

Binary Not Found

echo $PATH

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 →