NoteDiscovery: a self-hosted markdown knowledge base you run with one docker run

The problem NoteDiscovery solves, and who it is actually for

Most note apps decide where your writing lives. NoteDiscovery takes the opposite position: your notes are markdown files in a directory you mount into a container, and the application is a browser interface over that directory. The README states the goal plainly, calling it a "lightweight, self-hosted note-taking application" that puts you in control of your knowledge base, and lists privacy-conscious users, developers who prefer markdown and local file storage, knowledge workers building a personal wiki, and teams wanting a self-hosted alternative to commercial apps.

That framing matters because it sets the boundary of the tool. If you want a hosted service where someone else handles backups, sync and uptime, this is the wrong shape entirely. If you already have a folder of markdown and want search, backlinks, a graph view, tags and a drawing editor on top of it without uploading anything, the pitch is coherent. The repository topics list Docker, FastAPI, Python, self-hosted, zettelkasten and second-brain, which is a fair summary of the intended audience.

How the container is built, and why the image has no CDN dependency

The Dockerfile is a multi-stage build and the stages explain most of the runtime behaviour. A node:20-alpine stage runs esbuild over frontend/app.js and frontend/sw.js and html-minifier-terser over frontend/index.html and frontend/login.html. A second stage runs scripts/vendor_assets.py against scripts/vendor_lock.json to download browser libraries into a /vendor directory. A third stage installs requirements.txt into a prefix, stripping __pycache__, .pyc files and test directories. The runtime image therefore ships minified frontend assets and local copies of every browser library.

That is the mechanism behind the README's claim that no CDN is required, which it says lets the app and its shared links work on air-gapped networks. It is a real design decision with a real cost: the image is larger than one that pulls a library from a public CDN at page load, and every vendored library has to be refreshed through scripts/vendor_lock.json rather than by whatever the CDN serves today. For an air-gapped or privacy-focused deployment that trade is the point, not a defect.

The backend is FastAPI with uvicorn, with python-multipart, markdown, pyyaml, aiofiles, cryptography, bcrypt, itsdangerous, slowapi and pydantic in the dependency list. The presence of bcrypt and itsdangerous is consistent with the optional password protection, and slowapi is a rate-limiting library, so the login path is rate-limited rather than open to unlimited attempts. The pyproject.toml classifies the project as Development Status 4 - Beta and requires Python 3.10 or newer.

Installing NoteDiscovery with docker run, then a first note

The README gives a Linux/macOS quick start. It creates a data directory, changes into it, and starts the container with that directory mounted at /app/data, publishing port 8000.

mkdir -p notediscovery/data && cd notediscovery
docker run -d --name notediscovery -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  ghcr.io/gamosoft/notediscovery:latest

After this, the container runs detached under the name notediscovery. Open http://localhost:8000 in a browser and you should see the interface. Anything you create in the app appears as a markdown file inside the data folder on the host, which is the whole point of the volume mount.

The repository also ships docker-compose.yml, which builds from the local Dockerfile instead of pulling the published image. It maps the same port, mounts ./data:/app/data, sets restart: unless-stopped, sets TZ=UTC, and defines a healthcheck that calls http://localhost:8000/health every 60 seconds with a 3 second timeout and 3 retries. The compose file comments note that the config, themes, plugins and locales mounts are optional and that the file or folder must exist with content before you uncomment them, which is a real trap: an empty bind-mounted config.yaml will not be populated for you.

docker compose up -d

The healthcheck path is worth knowing about if you put a reverse proxy in front of the container, because that is the endpoint the container itself uses to decide whether it is healthy.

Connecting an AI assistant through the bundled MCP server

NoteDiscovery ships an MCP server in the mcp_server/ directory, and the README describes it as letting AI assistants search, create, edit, organize and tag notes. The documented one-line setup for Cursor, Claude Desktop and other MCP-compatible clients runs the same image with python -m mcp_server and points it at a NoteDiscovery instance.

{
  "mcpServers": {
    "notediscovery": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTEDISCOVERY_URL=http://host.docker.internal:8000", "ghcr.io/gamosoft/notediscovery:latest", "python", "-m", "mcp_server"]
    }
  }
}

Two details in that snippet deserve attention. The client runs the MCP server in a throwaway container with --rm and -i, so each session starts fresh. And the NOTEDISCOVERY_URL value uses host.docker.internal, which is how a container reaches a service on the Docker host. On Linux that hostname is not available by default, so the README's example is written for Docker Desktop environments. The README points to documentation/MCP.md for the full tool list, and separately describes OLLAMA-STACK.md as a way to run NoteDiscovery plus Ollama plus Open WebUI with one command if you want the model local too.

Where NoteDiscovery is the wrong tool

The README does not document multi-user accounts, roles or permissions. Authentication is described as "optional" and "simple password protection for self-hosted deployments", which reads as a single shared gate in front of the whole instance rather than per-person access. A team that needs per-user permissions, audit trails or an approval flow will not find them described here.

There is also no documented sync protocol or mobile client. Notes are plain files, so you can sync the data directory yourself with whatever tool you already use, but NoteDiscovery does not manage that, and two people editing the same file through two running containers is not something the README addresses. The project's own classifier says Development Status 4 - Beta, and the release history shows frequent point releases in the v0.31.x line, so expect the interface and configuration surface to keep moving.

Finally, the compose file's warning that optional mounts must already exist with content means a misconfigured bind mount can silently shadow a file the image expects. If you customize config.yaml, verify the container is reading your file rather than falling back to a default.

How it differs from Obsidian and from a hosted wiki

Obsidian is the closest comparison and the one people search for. Both work on markdown files in a folder. The difference is where the application runs. Obsidian is a desktop application that opens a local vault, and its sync and publishing features are separate products. NoteDiscovery is a server you run, and the browser is the client, so any device on your network can reach the same instance without installing anything, and shared links are served by your own container.

Against a hosted wiki, the difference is custody. In NoteDiscovery the files sit in ./data on your machine, in markdown, with no proprietary format, which is what the README means by "no lock-in". The cost of that custody is operational: you own the container, the volume, the backups and the upgrades. There is no vendor to call. The docker-compose.yml restart policy and healthcheck are the extent of the resilience the project provides out of the box.

Licence, upgrades and what maintenance you are signing up for

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence, not a copyleft one, so it does not oblige you to publish changes you make. This is a description of the licence text, not legal advice.

The practical upgrade cost comes from the release cadence. Recent tags include v0.31.5 on 2026-09-04, v0.31.4 on 2026-08-25 and v0.31.3 on 2026-08-21, so point releases arrive within days of each other. The last push to the default branch was on 2026-09-10. Because your notes live in a mounted volume rather than inside the image, replacing the container does not touch your data, which makes upgrades cheap in the normal case: pull the new image, stop the old container, start the new one.

The parts that can break across versions are the ones that live outside the data volume: config.yaml, themes/, plugins/ and locales/ if you mounted them. Those are the files to diff against the repository before you upgrade, since the compose file treats them as optional overrides and the image carries its own defaults.

Editorial conclusion

Adopt NoteDiscovery if you want markdown files in a folder you control and are comfortable running a container. Skip it if you need real-time collaboration or a hosted service with no server to run. Before committing, verify three things yourself: that your notes appear under /app/data after the first run, that the optional password protection behaves the way you expect, and that the MCP server can reach your instance on port 8000 from wherever your AI client runs.

Frequently asked questions

Official sources

1. gamosoft/NoteDiscovery on GitHub
2. License: MIT
3. Project website
4. README
5. Releases