mddb / docs

Appearance

Installation ​

The installer is the supported path on Linux and macOS. Windows uses a release archive. Developers build from source.

Install the user service on Linux or macOS ​

The installer downloads the latest stable release, verifies its SHA-256 checksum, and starts mddb as a user service:

bash
curl -fsSL https://raw.githubusercontent.com/maruel/mddb/main/contrib/install.sh -o /tmp/install-mddb.sh
bash /tmp/install-mddb.sh

The installer takes no arguments. It supports amd64 and arm64. It requires curl, tar, install, and sha256sum or shasum. On Linux it also requires a running systemd user manager. mddb itself requires git on PATH.

ItemPath
Executable~/.local/bin/mddb
Configuration~/.config/mddb/config.toml, or $XDG_CONFIG_HOME/mddb/ if set
Data~/mddb/data
Linux servicesystemd user unit mddb.service
macOS servicelaunchd agent com.maruel.mddb, logs in ~/Library/Logs/mddb/

The installer writes the example config.toml only when no configuration exists. It never changes config.toml, settings.json, or the data directory. If ~/.local/bin is not on your PATH, the installer tells you.

On Linux, a user service stops when you log out. Keep it running on a server with:

bash
loginctl enable-linger "$USER"

Updates install automatically ​

Run the installer again to update immediately. Each run replaces the executable and the service file.

Stable releases also check for updates every day at 04:50 local time, with up to five minutes of random delay. mddb installs the update and restarts gracefully. Set auto_update = "" in config.toml to turn this off. Development, modified, and prerelease builds never update themselves.

Use a release archive on Windows ​

GitHub Releases publishes mddb_<os>_<arch> archives for linux, darwin, and windows on amd64 and arm64, with a checksums.txt file. Linux and macOS archives are .tar.gz files. Windows archives are .zip files with mddb.exe, LICENSE, and the example config.toml.

On Windows:

  1. Download the zip for your architecture.
  2. Extract it into a directory that your account owns.
  3. Copy config.toml to %USERPROFILE%\.config\mddb\config.toml and edit it.
  4. Make sure Git is on PATH.
  5. Run mddb.exe from the directory that should hold data.

mddb resolves the default data directory against the working directory. The installer and the Windows steps do not register a Windows service.

Build from source ​

With a Go toolchain, install the server:

bash
go install github.com/maruel/mddb/backend/cmd/mddb@latest

The module embeds a prebuilt web app, so this command needs only Go. To build the web app yourself, clone the repository. This path requires Node.js 26 and pnpm 12:

bash
git clone https://github.com/maruel/mddb.git
cd mddb
make build

make build installs mddb and notion-import into your Go binary directory.

When you start mddb in a terminal and no config.toml exists, a setup wizard asks for the base URL and optional OAuth credentials. It writes config.toml with mode 0600.

Check the installation ​

bash
mddb -version

Open http://localhost:8080 and create an account. The first account becomes the server administrator. Next, review the configuration and the service commands.