Configuration

The configuration is one JSONC file: JSON, with // comments and trailing commas allowed. Unknown keys are refused when the server starts, so a typo never goes unnoticed. The example, src/mdNotebook.server/config.example.jsonc, has every setting with a comment.

The server

Setting Default What it does
listen http://+:8180/ The address to listen on.
stateDirectory (required) Where the server keeps tokens.json, the logged-in devices. Keep it apart from the configuration and the notebooks.
maxFileBytes 104857600 (100 MB) The largest file that can be uploaded.
webClientDirectory none The web app's files, served at /. Without it, / is a short home page.
docsDirectory the docs that come with the server This documentation, served at /docs/.
downloadsDirectory none The app files offered at /downloads/. They're found by name: mdNotebook-1.2.0-android.apk, mdn-1.2.0-linux-x64.tar.gz (the command line).

Logins: auth

Users log in once on each device, which then keeps a token (the password isn't stored on the device). Users can come from the configuration file, an LDAP directory, or both.

  • local: enabled, and a list of users, each with username, password and groups. The passwords are in plain text, so keep the file private.
  • ldap: enabled, serverHost, serverPort, useStartTls; a service account (bindDn, bindPassword) that searches baseDn with userSearchFilter ({username} is replaced by the username); and where groups come from (groupMembershipAttribute, and extractCnFromGroupDn to use just each group's name).
  • cacheSeconds (300): how long a successful password check is remembered, in memory.
  • lockout: after maxFailures (5) failed logins within minutes (15), that username and that address are refused for that many minutes. Devices already logged in aren't affected.
  • tokens.expireUnusedDays (180): a device not seen for this long is logged out.
  • trustedProxies: addresses or ranges (172.18.0.0/16) of reverse proxies whose X-Forwarded-For header is believed.

If neither local nor ldap is enabled, everyone can edit everything, with any password. The server logs a loud warning when it starts like that. It's only meant for trying it out.

Notebooks

Each entry in notebooks is one notebook:

Setting Default What it does
name (required) Its short name, used in URLs, e.g. myDiary.
title the name The name people see.
directory (required) Where it is on disk. It must exist.
kind notebook diary gives the apps a "New entry for today" button.
bin.directory .bin in the notebook Where deleted things go. It can be anywhere, even another disk.
bin.keepDays 90 How long deleted things are kept before they're gone for good.
auth everyone can read and edit Who can read and edit it, below.
hook off A command to run after changes: see Hooks.

Who can read and edit

auth has a read rule and an edit rule. Each has a default of allow or deny, and lists of usersList and groupsList that are the exceptions to it. Anyone the edit rule allows can edit (and read); otherwise anyone the read rule allows can read. For example, only Andrew edits, and the family group reads:

"auth": {
	"read": { "default": "deny", "usersList": [], "groupsList": ["family"] },
	"edit": { "default": "deny", "usersList": ["andrew"], "groupsList": [] }
}

Add "allowGuest": true to the read rule to let anyone read without logging in. Guests can never edit, and only editors see drafts, conflict copies and the bin.