# flatnotes: A Self-Hosted, Database-less Note-Taking Web App

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/dullage-flatnotes
Generated for open source discovery and AI-assisted research.

flatnotes is a self-hosted, database-less note-taking web application designed for simplicity and efficiency. It stores all your notes as plain markdown files, ensuring you retain full control and avoid vendor lock-in. This app offers a distraction-free interface with powerful search and tagging capabilities.

GitHub: https://github.com/dullage/flatnotes
OSRepos URL: https://osrepos.com/repo/dullage-flatnotes

## Summary

flatnotes is a self-hosted, database-less note-taking web application designed for simplicity and efficiency. It stores all your notes as plain markdown files, ensuring you retain full control and avoid vendor lock-in. This app offers a distraction-free interface with powerful search and tagging capabilities.

## Topics

- markdown
- note-taking
- self-hosted
- web-app
- Vue
- notes-app
- wiki

## Repository Information

Last analyzed by OSRepos: Thu Oct 23 2025 12:01:53 GMT+0100 (Western European Summer Time)
Detail views: 0
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

flatnotes is an innovative, self-hosted, database-less note-taking web application that prioritizes simplicity and user control. It stores all your notes as plain markdown files within a flat folder structure, eliminating the need for complex databases or proprietary formats. This design ensures that your notes are always accessible and portable, freeing you from vendor lock-in.

Designed to be distraction-free, flatnotes offers a clean and intuitive user interface. It focuses on putting your note content first, complemented by powerful search and tagging functionalities. You can explore a live demo of flatnotes to experience its features firsthand: [flatnotes Demo](https://demo.flatnotes.io){:target="_blank"}.

## Installation

flatnotes provides flexible options for deployment, whether you prefer a managed service or self-hosting. For a quick and easy setup, you can deploy flatnotes through [PikaPods](https://www.pikapods.com/pods?run=flatnotes){:target="_blank"}, a hosted solution.

For those who prefer to self-host, Docker is the recommended method, offering robust and consistent deployment across various environments. Below are examples demonstrating how to get flatnotes up and running using Docker commands or Docker Compose.

## Examples

### Docker Run Command

To quickly launch flatnotes using a Docker run command, you can use the following:

shell
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


### Docker Compose Example

For a more persistent and configurable setup, Docker Compose is an excellent choice. Here's an example `docker-compose.yml` file:

yaml
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


For a comprehensive list of configuration options and environment variables, refer to the [flatnotes Wiki](https://github.com/dullage/flatnotes/wiki/Environment-Variables){:target="_blank"}.

## Why Use flatnotes?

flatnotes stands out with its commitment to simplicity, control, and efficiency. Key features and design principles include:

*   **Distraction-Free Interface**: A clean and simple user interface that puts your note content first.
*   **No Vendor Lock-in**: Your notes are plain markdown files, easily transferable to other applications. There's no database or proprietary formatting.
*   **Powerful Search and Tagging**: Quickly find any note with advanced full-text search and flexible tagging functionality.
*   **Mobile Responsive**: Access and manage your notes seamlessly from any device.
*   **Flexible Editing**: Choose between raw markdown or a WYSIWYG editor mode.
*   **Wikilink Support**: Easily link to other notes within your collection using `[[My Other Note]]`.
*   **Customization**: Personalize your experience with customizable home pages and light/dark themes.
*   **Secure Access**: Multiple authentication options, including username/password and 2FA.
*   **API Access**: A Restful API for programmatic interaction with your notes.

The application also intelligently handles external changes to your markdown files, incrementally syncing its search index, allowing you to edit notes outside of flatnotes even while it's running.

## Links

*   **GitHub Repository**: [dullage/flatnotes](https://github.com/dullage/flatnotes){:target="_blank"}
*   **Demo Site**: [flatnotes Demo](https://demo.flatnotes.io){:target="_blank"}
*   **Official Wiki**: [flatnotes Wiki](https://github.com/dullage/flatnotes/wiki){:target="_blank"}
*   **Deploy on PikaPods**: [Run flatnotes on PikaPods](https://www.pikapods.com/pods?run=flatnotes){:target="_blank"}
*   **Sponsor the Project**: [Sponsor Dullage](https://github.com/sponsors/Dullage){:target="_blank"}