flatnotes: a self-hosted markdown note app with no database

The problem flatnotes picks: notes you can walk away with

Most note apps put your writing in a database or a proprietary store. Export exists, but it is a second step, and the export is rarely the same thing the app reads. flatnotes inverts that. The README states the design principle directly: "Your notes are just markdown files." There is no database, no proprietary formatting, and no nested folder structure. If you stop using flatnotes, you move the files and open them somewhere else.

The audience is narrow and specific. It is for someone who already thinks in markdown, wants a web interface they host themselves, and does not want a folder tree to maintain. The README is explicit that there are "No folders, notebooks or anything like that." Everything is one collection, and you find things through search and tags instead of hierarchy. That is a real design position, and it is also the first thing that will annoy a certain kind of user.

How the flat folder and the search index actually fit together

The storage layer is a directory of markdown files. In the Docker image the environment variable FLATNOTES_PATH defaults to /data, and the compose example mounts ./data onto it. The container declares VOLUME /data, so that path is the thing you back up.

The only thing flatnotes caches, according to the README, is the search index, and it is "incrementally synced on every search (and when flatnotes first starts)." That single sentence explains the whole concurrency story. You can add, edit or delete markdown files outside flatnotes while it is running, and the next search picks up the change. The compose example shows where that index lives by default, with a commented line mapping ./index to /data/.flatnotes if you want it elsewhere. Search itself is Whoosh, a pure Python search engine, listed in pyproject.toml as whoosh==2.7.4.

The server side is FastAPI with uvicorn, and the client is Vue 3 built by Vite. The Dockerfile is a two-stage build: node:24-alpine compiles the client, then python:3.13-slim-trixie runs the server with dependencies installed by uv from uv.lock. The Python requirement is pinned tightly, requires-python = ">=3.13,<3.14", so flatnotes is not a project you can drop onto an arbitrary Python install and expect to work. Use the container.

Installing flatnotes with Docker and writing your first note

The README recommends Docker for self-hosting. The run command below is copied from it. It sets the process user and group, turns on password authentication, and mounts the current directory's data folder as the note store.

docker run -d \
  -e "PUID=1000" \
  -e "PGID=1000" \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e 'FLATNOTES_PASSWORD=changeMe!' \
  -e "FLATNOTES_SECRET_KEY=aLongRandomSeriesOfCharacters" \
  -v "$(pwd)/data:/data" \
  -p "8080:8080" \
  dullage/flatnotes:latest

After the container starts, the web interface is on port 8080. Log in with the username and password you passed in. Change both the password and the secret key before this touches anything you care about; the README's values are placeholders, not defaults to keep.

If you prefer compose, the README gives this file. The commented volume is the optional relocation of the search index.

version: "3"

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "aLongRandomSeriesOfCharacters"
    volumes:
      - "./data:/data"
    ports:
      - "8080:8080"
    restart: unless-stopped

Once you are in, create a note and save it. Then look at ./data on the host: your note is a .md file sitting directly in that directory, with no subfolder created for you. That is the whole storage model, and it is worth confirming on your own disk before you migrate anything into it. For the full list of settings, the README points to the Environment Variables article in the project wiki.

Authentication choices and what each one exposes

flatnotes lists four authentication modes: none, read-only, username/password, and 2FA. The mode is selected with FLATNOTES_AUTH_TYPE, and the README's examples use password. The 2FA path pulls in pyotp and qrcode, which is how the server generates and verifies one-time codes.

The mode you pick decides who can write to a folder that is also a normal directory on your filesystem. With auth set to none, anyone who can reach port 8080 has the same access as the process running the container, which is PUID and PGID from your environment. Read-only mode is the sensible setting when you are publishing notes rather than editing them, but the README does not spell out the exact behaviour of every mode; the wiki article it links to is where that detail lives, and you should read it rather than infer from the variable names.

The PUID and PGID variables matter more than they look. They decide which user owns the files flatnotes writes into /data. If they do not match the account you use to edit those markdown files directly, you will end up with files you cannot open without sudo, which defeats the point of keeping them as plain files.

Where the flat model and the search index break down

The absence of folders is the feature and the limitation at the same time. If you have thousands of notes and you rely on directory structure to keep projects apart, flatnotes gives you tags and search instead. The README frames this as a principle, and it is honest about the trade: no folders, no notebooks. If your mental model is a filing cabinet, this is the wrong tool, and no amount of tagging will make it feel like one.

The search index is the second boundary. It is a cache, and the README says it is synced on every search and at startup. That means external edits eventually appear, but it also means search results are only as current as the last sync. If you edit files on disk and immediately search, expect the index to catch up rather than be instant.

The roadmap section is worth reading before you plan a migration. The maintainer states an intent to keep flatnotes "as simple and distraction-free as possible which means limiting new features." Feature requests are welcome, but the project's stated direction is to stay small. If your adoption depends on a capability the README does not list, that is a reason to wait rather than a reason to file an issue and assume it will land.

Finally, the README documents no native mobile app. The interface is described as mobile responsive, which is a browser experience, not an installed client. Search data shows people looking for a flatnotes Android or iOS app; the README describes neither.

flatnotes against Obsidian and other markdown editors

The closest comparison in the search data is against Obsidian, and the difference is architectural rather than cosmetic. Obsidian is a local desktop application that opens a folder of markdown files on your machine; flatnotes is a server that serves a web interface over a folder on the server. With flatnotes, the folder lives where the container runs, and any device with a browser can reach it. With a desktop editor, the folder lives on each device, and keeping two machines in step is a separate problem you solve with something else.

That distinction sets the honest expectation. flatnotes is not a sync service. It is one server holding one folder, which several browsers can reach. If you want offline editing on a laptop and a phone, you are back to picking a sync layer yourself.

Against a database-backed wiki, the difference is the recovery story. With flatnotes, restoring your notes means restoring a directory of markdown files, and the search index regenerates from them. The README's claim that you are "free at any point to just move the files elsewhere" is the whole argument, and it is one you can verify by opening the data folder in any text editor.

Editorial conclusion

Adopt flatnotes if your notes are already markdown, you want a browser editor over a folder you keep on your own disk, and you accept that the folder is flat. Do not adopt it if you need nested directories, a native Android or iOS client, or a built-in sync service, none of which the README describes. Before you commit, verify the environment variable names in the wiki against your chosen version, and confirm that a backup of the /data volume is enough to restore your notes, because the search index can be rebuilt from the markdown files.

Frequently asked questions

Official sources

1. dullage/flatnotes on GitHub
2. Issues
3. License: MIT
4. README
5. Releases