flatnotes

Self-hosted note-taking, honestly reviewed. No marketing fluff, just what you get when you run it on your own server.

TL;DR

• What it is: A self-hosted, database-less note-taking web app that stores your notes as a flat folder of plain markdown files — nothing proprietary, nothing locked in [README].
• Who it’s for: Solo founders, developers, and power users who want Notion-style web access to their notes without a monthly subscription, vendor lock-in, or a database to maintain [README].
• Cost savings: Notion charges $10–16/mo per user. Obsidian Sync runs $10/mo. flatnotes self-hosted runs on a $5–6/mo VPS with unlimited notes and no per-user pricing [README].
• Key strength: The design principle is genuinely rare — your notes are just markdown files. You can edit them with any text editor, move them to another app, or sync them with rsync while flatnotes is running. No migration required if you ever leave [README].
• Key weakness: No folders, no nested notebooks. That’s intentional, but it’s a dealbreaker if your note-taking system depends on hierarchy. Also: 2,826 GitHub stars as of this review — small project, one primary maintainer. Long-term support is a real question [README].

---

What is flatnotes

flatnotes is a web interface for a folder of markdown files. That’s the entire product, stated plainly. You point it at a directory, spin up a Docker container, and you get a clean browser-based editor with full-text search, tagging, and wikilink support. The notes themselves are .md files sitting on disk — no database, no proprietary format, no vendor schema [README].

The project is built by a single developer (GitHub handle: dullage) and has accumulated 2,826 stars and 168 forks. It’s not backed by a company, not venture-funded, and not trying to compete with Notion or Obsidian on feature count. The README’s stated design principle is worth reading literally: “Another key design principle is not to take your notes hostage. Your notes are just markdown files.” [README]

What that means in practice: the search index is the only thing flatnotes generates that isn’t a markdown file, and that index is rebuilt incrementally on every search. If you delete flatnotes tomorrow, you still have all your notes. If you add or edit files directly on disk while flatnotes is running, the app picks them up on the next search. That level of transparency is unusual in note-taking apps, where vendors routinely add proprietary block formats, database dependencies, or sync-locked storage [README].

The tech stack is Python on the backend (FastAPI, with Whoosh for full-text search), Vue.js on the frontend, and TOAST UI Editor for the markdown editing experience [README]. The whole thing ships as a single Docker image.

---

Why people choose it

There’s no shortage of self-hosted note-taking options. flatnotes doesn’t win because it has the most features — it wins because it solves a specific, narrow problem well: I want a web UI for my markdown files, I want full-text search, and I don’t want to set up a database or give a SaaS vendor my notes.

Versus Notion. The Notion comparison is the most common trigger for people discovering flatnotes. Notion’s free tier is capped (limited blocks, limited file uploads), the paid tier starts at $10/mo per user, and your notes live in Notion’s proprietary block database — not in files you control. Moving out of Notion requires an export step that produces inconsistent markdown. flatnotes has no per-user pricing and your notes are already files [README].

Versus Obsidian. Obsidian is the darling of the personal knowledge management crowd, and it uses local markdown files too — but it’s a desktop app, not a web app. If you want access from multiple devices or a browser, you need Obsidian Sync ($10/mo) or a third-party sync solution. flatnotes runs as a web service you access from any browser, on any device, with no sync subscription [README].

Versus Joplin. Joplin is another popular self-hosted option, but it requires a database and its markdown export isn’t always clean. flatnotes has zero database dependency — the markdown files are the storage layer [README].

Versus Standard Notes. Standard Notes offers end-to-end encryption and a polished client, but it’s a full product with a commercial sync service ($9.99/mo for extended features). flatnotes is simpler and cheaper, though it doesn’t offer E2E encryption — authentication is handled at the app level (password or 2FA) [README].

The flat-structure tradeoff. The deliberate absence of folders will put some people off immediately. If your current note system depends on a hierarchy of nested notebooks — project folders, sub-folders, category trees — flatnotes isn’t built for that mental model. The bet it makes is that full-text search plus tags is a better retrieval mechanism than folder navigation, which is a defensible position but not a universal one [README].

---

Features

Based on the README and repository:

Editor:

• Raw markdown mode and WYSIWYG mode — switch per note or set a default [README]
• TOAST UI Editor, which handles GitHub Flavored Markdown cleanly [README]
• Wikilink support: type [[My Other Note]] to link between notes, auto-completing on existing note titles [README]

Search and organization:

• Full-text search powered by Whoosh (Python) [README]
• Keyboard shortcut / from anywhere in the app triggers search [README]
• Note tagging — add tags, filter by tag [README]
• Search index is incremental: synced on startup and on every search, so edits made outside the app show up immediately [README]

Interface:

• Mobile-responsive web UI [README]
• Light and dark themes [README]
• Customizable home page [README]
• No folders, notebooks, or hierarchy — intentional design decision [README]

Authentication:

• Four modes: none (open access), read-only (anyone can read, no writes), username/password, username/password + TOTP 2FA [README]
• This is per-instance, not per-user — there’s no user management system. One set of credentials per instance [README]

Access:

• REST API included [README]
• Docker and Docker Compose deployment [README]
• PikaPods managed hosting available for users who don’t want to self-host [README]

What it doesn’t have:

• No real-time collaboration or shared editing
• No end-to-end encryption
• No multi-user accounts or granular permissions
• No mobile native apps (browser only)
• No attachment handling beyond what markdown links support

The feature list is intentionally short. The project’s README explicitly states: “I want to keep flatnotes as simple and distraction-free as possible which means limiting new features.” [README] That’s not a weakness framed as a strength — it’s a genuine product decision with a cost (fewer features) and a benefit (focused, maintainable codebase).

---

Pricing: SaaS vs self-hosted math

flatnotes self-hosted:

• Software: $0 (MIT license) [README]
• Hosting: $5–10/mo on a shared VPS (Hetzner, Contabo, or DigitalOcean)

PikaPods managed hosting:

• flatnotes is available on PikaPods for users who want one-click deployment without managing a server. PikaPods pricing is resource-based and typically runs $1–5/mo for a lightweight app like this [README]. Exact current pricing requires checking the PikaPods site directly.

What you’re replacing:

Tool	Monthly cost	Your notes format
Notion (Plus)	$10/user/mo	Proprietary blocks
Obsidian Sync	$10/mo	Local files (sync only)
Roam Research	$15/mo	Proprietary
Standard Notes (Productivity)	$9.99/mo	Encrypted, exportable
Bear (iOS/Mac)	$2.99/mo	Proprietary Bear format

A solo founder currently paying $10/mo for Notion or Obsidian Sync, switching to flatnotes on a $6/mo Hetzner VPS, saves roughly $48–120/year — not life-changing, but the bigger win is the data sovereignty. At the $10/user level, a 3-person team saves $360/year while getting their data off a vendor’s servers.

The self-hosted math only works if you’re comfortable managing a Docker container. If you need a managed setup, PikaPods is the realistic alternative to the full DIY path.

---

Deployment reality check

flatnotes is one of the simpler self-hosted tools to deploy. The Docker Compose setup is five environment variables and a volume mount [README]:

services:
  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

That’s the entire configuration for a working instance [README]. You still need a reverse proxy (Caddy or nginx) and a domain if you want HTTPS and external access, but the app itself has no database, no Redis, no separate search service — just the container and a folder.

Realistic time estimates:

• Technical user with Docker experience: 15–30 minutes to a running instance
• Non-technical user following a guide: 1–3 hours including domain and reverse proxy setup
• PikaPods route: 5–10 minutes, no server management required [README]

Caveats worth knowing:

The single-maintainer reality matters here. The project has 565 commits and an active issue tracker, but it’s not a company. If the maintainer loses interest or gets busy, issues may sit unanswered for weeks or months. Check the GitHub issues page before committing to this for anything business-critical.

Authentication is coarse-grained. There’s one username and password for the whole instance. If you want per-user access controls or want to share read access with one person and write access with another, the current auth model won’t support that cleanly [README]. The read-only mode partially solves the sharing case, but it’s all-or-nothing.

No backup strategy is built in. Your notes are files, which is great, but you’re responsible for backing them up. The volume mount at ./data needs to be included in whatever backup system you run.

The 2FA implementation is TOTP-based, which is solid, but there’s no option to add a second user with their own credentials — it’s instance-level authentication, not user-level [README].

---

Pros and Cons

Pros

• Zero lock-in. Notes are plain markdown files. Add them, edit them, delete them outside the app — flatnotes doesn’t care. Move to any other markdown-compatible tool at any time without an export step [README].
• No database to maintain. No PostgreSQL, no SQLite, no Redis. The only state is the notes directory and the search index. Less to break, less to back up [README].
• Simple deployment. Five environment variables and a volume mount. One of the easiest Docker setups in the self-hosted category [README].
• 2FA included. TOTP two-factor authentication is a standard feature, not a paid add-on [README].
• REST API. Programmatic access for automation or integration with other tools [README].
• MIT licensed. No usage restrictions, no commercial limitations, no viral licensing concerns [README].
• Files stay accessible. Because the search index syncs incrementally, you can use any text editor alongside flatnotes without conflicts [README].

Cons

• No folder hierarchy. Intentional, but if your workflow depends on nested notebooks, this is a fundamental incompatibility, not a minor inconvenience [README].
• One set of credentials per instance. No multi-user support, no per-user permissions. Sharing access means sharing your password or running separate instances [README].
• Single-maintainer project. 2,826 stars and one primary developer. The project may not receive timely updates, security patches, or new feature work indefinitely [README].
• No native mobile app. Browser-only. Works fine on mobile browsers, but there’s no offline support or native push integration.
• No E2E encryption. Auth is at the app layer. If your VPS is compromised, your notes are readable. This is standard for self-hosted web apps but worth stating explicitly.
• Python search library (Whoosh) has scalability limits. For tens of thousands of notes, Whoosh may slow down. This is unlikely to matter for personal use but worth knowing for large knowledge bases [README].
• No attachment management. You can link to files in markdown, but there’s no built-in file upload or attachment browser.

---

Who should use this / who shouldn’t

Use flatnotes if:

• You currently pay for Notion, Obsidian Sync, or a similar tool and your primary use case is personal notes — not team collaboration.
• You already think in markdown and you want a web interface for a folder of .md files.
• Data ownership matters to you and you don’t want your notes sitting on a vendor’s servers.
• You have basic Docker experience or are willing to use PikaPods for managed hosting.
• Your retrieval model is “search for what I need” rather than “navigate a folder tree.”

Skip it if:

• Your workflow depends on nested folders, notebooks, or hierarchical organization.
• You need multi-user access with separate credentials and permissions.
• You’re looking for real-time collaboration or a shared team knowledge base.
• You need end-to-end encryption for sensitive material.
• You want mobile-native apps with offline support and push sync.
• You rely on rich embeds, databases, or Notion-style relational content.

Use a different tool if:

• Collaborative notes/wiki: HedgeDoc (real-time collaborative markdown), BookStack (wiki-style with chapters), or Wiki.js.
• Personal knowledge management with backlinks: Silverbullet or Logseq both offer self-hosted options with bidirectional linking and a graph view.
• Encrypted notes: Standard Notes self-hosted gives you E2E encryption without trusting a vendor.
• Desktop-first with self-hosted sync: Joplin with a Nextcloud or WebDAV backend.

---

Alternatives worth considering

• Silverbullet — self-hosted, Markdown-based, with live queries, extensions, and bidirectional links. More powerful than flatnotes but also more complex to configure.
• Logseq — graph-based, self-hosted sync available, strong outliner and journaling workflow. Closer to Roam Research than to flatnotes in philosophy.
• HedgeDoc — real-time collaborative markdown editor. Better for teams, requires a database.
• Joplin — open-source notes with optional self-hosted sync. Has mobile apps, E2E encryption, attachment support. More feature-rich but also more moving parts.
• Standard Notes — self-hostable, E2E encrypted, cross-platform apps. The right choice if encryption is the priority.
• Trilium Notes — rich hierarchical notes with scripting, attributes, and a tree structure. The opposite design philosophy to flatnotes — choose it if you want maximum organizational power.
• Obsidian + self-hosted sync — local files with a desktop app you control, plus self-hosted sync via LiveSync. More setup than flatnotes but stronger ecosystem and plugin library.

For the person who specifically wants “web UI for markdown files, no database, no lock-in,” flatnotes is the most direct answer. For everyone else, the alternatives above probably fit better.

---

Bottom line

flatnotes does one thing and takes it seriously: give you a clean web interface for a folder of markdown files, with search, tagging, and wikilinks, without touching a database or locking your data into any proprietary format. That’s a genuinely useful tool for a specific kind of user — someone who already writes markdown, cares about owning their notes, and wants browser-based access without paying a monthly sync fee.

The trade-offs are real and intentional. No folders, one set of credentials, a single maintainer, no mobile apps. None of these are surprises — they’re the direct result of a design philosophy that values simplicity over feature completeness. If that philosophy matches how you think about notes, flatnotes is worth an afternoon of setup. If it doesn’t, the alternatives section above has options that will.

If the Docker deployment is the blocker, upready.dev deploys tools like this for clients as a one-time service — you get the infrastructure without learning the command line.

---

Sources

Note: Third-party review articles were not available in the research sources for this tool. Citations below refer to primary sources.

1. flatnotes GitHub Repository and README — dullage/flatnotes, MIT License, 2,826 stars. https://github.com/dullage/flatnotes
2. flatnotes Demo Site — live demo resetting every 15 minutes. https://demo.flatnotes.io
3. PikaPods — flatnotes managed hosting. https://www.pikapods.com/pods?run=flatnotes
4. flatnotes Wiki — Environment Variables and configuration reference. https://github.com/dullage/flatnotes/wiki