Fork disclaimer

Warning

While majority of the vulnerabilities were fixed with simple dependency bumps, toast-editor is no longer maintained and has hard-dependency on dompurify@v3.3.3 which is vulnerable to multiple CVEs, one of them allowing for an XSS bypass. Only run this locally.

I'm not a web dev. Some of the issues were done with the help of an LLM, though I've still made sure to read documentation over and over again before applying anything. It wasn't used for everything, only things I was really stumped on, or had no knowledge of. These changes aren't that big since flatnotes in itself is quite simple piece of software.

It was used as a diagnostic tool, not as a "spit out an answer and I'll believe you" way.

• style.css
• client/components/PrimeToast.vue
• client/components/PrimeMenu.vue
• postcss.config.js

I had no idea how to move colors from tailwind.css.js to style.css so I've just asked crappy Copilot to help me out. It spouted something out, I've researched it, found this stackoverflow thread and settled on some CSS values being inline and others not. That part was half me figuring things out, half LLM.

client/components/PrimeToast.vue was beating me into the mud, in the end the fix was very simple to do and I could've figured it myself if I used my head for once.

Majority of the work was done by myself since I do have some experience regarding working with NodeJS / Tailwind CSS projects, though not enough to be comfortable with it. Don't worry I'm not a stupid techbro to just blindly copy and paste shit, I wouldn't really bother with this fork if it was that, the goal of this was to update dependencies of flatnotes and implement some PRs and call it a day.

For honesty's sake, I'm explictly outlining below in the changes what was fully done by me, and what was done with LLM help. I've learned a lot of things while doing this though like how to generate proper package.json and package-lock.json, how to take care of Pipfile and update it, upgrade process for TailwindCSS v2 -> v3 etc. so it's not like I was just blindly stumbling into shit and ignoring anything else just to get to the end destination. Hoping this will be useful to somebody regardless.

Fork changes

This fork has following changes compared to upstream

• Available on GitHub Container Registry - ghcr.io/rubberverse/flatnotes:latest (arm64 builds provided as-is, can't test them) (Me)
• Merged PR from upstream: OIDC support by anujc4 via #351 (Me)
• Merged PR from upstream: Prevent focus on background element while Modal is open by noahhefner via #349 (Me)
• Merged PR from upstream: Shell hooks by reddec via #190 only on alpine-97c5bed and 97c5bed tag. (Me)
• Rootless user by default inside container (Me)
• Removes entrypoint.sh and healtcheck.sh as they're no longer needed, curl also didn't make the cut (Me)
• Runs app on 0.0.0.0:9102, override entrypoint if you want something different (Me)
• Cleaner Containerfile that I threw up together (Me)
• Debian Trixie & Alpine Linux images for both builder (node:lts) and runner (python:3.13.13) (Me)
• Adds Podman Quadlet files inside quadlet/ directory so you can quickly spin this up yourself (Me)
• Updates all NodeJS and Pipfile dependencies and packages to latest version (Me)
• Proper package locking for both Pipfile and NodeJS (Me)
• Upgraded Tailwind CSS to V4 (from V3) (30% LLM, 70% Me)
• Updated stylesheet to support Tailwind V4 in client/style.css (50% LLM, 50% Me)
• Uses Python 3.13.13 instead of Python 3.10 (Me)
• Added @tailwind/postcss plugin to postcss.config.js and devDependencies in package.json (100% LLM)
• Fixed bugs related to Tailwind CSS upgrade in client/components/PrimeToast.vue, client/partials/SearchModal.vue (50% LLM, 50% Me)
• Removed extra checkmark from toast notification in client/views/Note.vue (Me)
• Hamburger menu has hover over mouse effects now, not sure if it always had but it might've broken with Tailwind CSS upgrade in client/components/PrimeMenu.vue (100% LLM)

FYI, Alpine image is smaller by 100MB compared to Debian - 161MB (Alpine) vs 261MB (Debian)

Configuring OIDC

It's shrimple. Create a client in your OIDC provider and then copy and fill this .env out. Here's an example for VoidAuth

FLATNOTES_AUTH_TYPE=oidc
FLATNOTES_OIDC_PROVIDER_NAME=MyProvider
FLATNOTES_OIDC_AUTO_REDIRECT=false
FLATNOTES_OIDC_PROVIDER_URL=https://auth.localhost.domain.tld/oidc
FLATNOTES_OIDC_REDIRECT_URI=https://notes.localhost.domain.tld/api/auth/oidc/callback
FLATNOTES_OIDC_CLIENT_ID=ClientIDFromDashboard
FLATNOTES_OIDC_CLIENT_SECRET=ClientSecretFromDashboard
FLATNOTES_SECRET_KEY=RandomlyGenerated32CharLongString

You can mount it to the container afterwards like so

EnvironmentFile=%h/Environments/Flatnotes/.env

Note

If you keep getting redirect_uri with container_name:port then you need to configure your reverse proxy properly.

uvicorn by default will trust proxy headers in current container entrypoint. If you modified entrypoint and forgot to pass --proxy-headers to uvicorn then that's why.

Here's an example for Caddy. Some of these are reduntant but in case X-Forwarded-Host or X-Forwarded-For is not being set, you'll see that problem above. Explictly setting it like this works wonders.

notes.domain.tld {
    reverse_proxy flatnotes:9102 {
        header_up X-Forwarded-Host {host}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-For {remote}
        header_up X-Forwarded-Port {server_port}
   }
}

Original project description starts below.

---

A self-hosted, database-less note-taking web app that utilises a flat folder of markdown files for storage.

Log into the demo site and take a look around. Note: This site resets every 15 minutes.

Contents

• Design Principle
• Features
• Getting Started
  • Hosted
  • Self Hosted
• Roadmap
• Contributing
• Sponsorship
• Thanks

Design Principle

flatnotes is designed to be a distraction-free note-taking app that puts your note content first. This means:

• A clean and simple user interface.
• No folders, notebooks or anything like that. Just all of your notes, backed by powerful search and tagging functionality.
• Quick access to a full-text search from anywhere in the app (keyboard shortcut "/").

Another key design principle is not to take your notes hostage. Your notes are just markdown files. There's no database, proprietary formatting, complicated folder structures or anything like that. You're free at any point to just move the files elsewhere and use another app.

Equally, the only thing flatnotes caches is the search index and that's incrementally synced on every search (and when flatnotes first starts). This means that you're free to add, edit & delete the markdown files outside of flatnotes even whilst flatnotes is running.

Features

• Mobile responsive web interface.
• Raw/WYSIWYG markdown editor modes.
• Advanced search functionality.
• Note "tagging" functionality.
• Customisable home page.
• Wikilink support to easily link to other notes ([[My Other Note]]).
• Light/dark themes.
• Multiple authentication options (none, read-only, username/password, 2FA).
• Restful API.

See the wiki for more details.

Getting Started

Hosted

A quick and easy way to get started with flatnotes is to host it on PikaPods. Just click the button below and follow the instructions.

Self Hosted

If you'd prefer to host flatnotes yourself then the recommendation is to use Docker.

Example Docker Run Command

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

Example Docker Compose

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"
      # Optional. Allows you to save the search index in a different location: 
      # - "./index:/data/.flatnotes"
    ports:
      - "8080:8080"
    restart: unless-stopped

See the Environment Variables article in the wiki for a full list of configuration options.

Roadmap

I want to keep flatnotes as simple and distraction-free as possible which means limiting new features. This said, I welcome feedback and suggestions.

Contributing

If you're interested in contributing to flatnotes, then please read the CONTRIBUTING.md file.

Sponsorship

If you find this project useful, please consider buying me a beer. It would genuinely make my day.

Thanks

A special thanks to 2 fantastic open-source projects that make flatnotes possible.

• Whoosh - A fast, pure Python search engine library.
• TOAST UI Editor - A GFM Markdown and WYSIWYG editor for the browser.