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