Running a server

The server is a single program, best run in Docker. It needs a configuration file, a directory for its own state, and one directory per notebook.

Installing with Docker

  1. Get the source, which includes the Dockerfile and an example Compose file, compose.example.yml. It uses a git submodule for Bulma (the pages' stylesheet), so clone it with git clone --recurse-submodules, or run git submodule update --init in an existing copy.

  2. Copy src/mdNotebook.server/config.example.jsonc to config.jsonc and edit it: at least the users and the notebooks (see Configuration). Each notebook's directory is where it's mounted inside the container, e.g. /data/notebooks/myDiary.

  3. Copy compose.example.yml to compose.yml, and change the paths on the left of each volume to your own. Set MDN_UID and MDN_GID to the owner of those directories: the server runs as that user, never root.

  4. Start it:

    docker compose -f compose.yml up -d --build
    docker logs mdnotebook
    

The log lists each notebook, and warns about anything in a notebook that breaks its rules (for example a loose file in a section). Those things are left alone and not shown to the apps until you fix them.

Running it without Docker

Build it with the .NET SDK (dotnet publish src/mdNotebook.server -c Release -o out), then run dotnet out/mdNotebook.server.dll. It reads ./config.jsonc, then /etc/mdnotebook/config.jsonc, or the path given as its first argument.

Behind a reverse proxy

The server speaks plain HTTP, and every request carries a login, so always put a reverse proxy that does TLS (Traefik, nginx, Caddy) in front of it. Two things to set on the proxy:

  • The upload size limit. Attached files can be large: raise the proxy's limit to at least the server's maxFileBytes (nginx: client_max_body_size 100m;).
  • The client's address. The server limits failed logins per address. Add the proxy to auth.trustedProxies, so the server believes the proxy's X-Forwarded-For header.

What to back up

  • Each notebook's directory. That's all the content, including drafts, conflict copies and the bin.
  • The state directory (tokens.json). Losing it only logs every device out.
  • config.jsonc.

The server keeps nothing else: no database, no caches on disk.

Logging every device out

Each user can see and log out their own devices from the apps. To log everyone out, stop the server, delete tokens.json from the state directory, and start it again.