Install Flatnotes with Docker - A Markdown Notes App#

Docker Compose#

Create a folder named “flatnotes”:

mkdir flatnotes
cd flatnotes

Create docker-compose.yml:

nano docker-compose.yml

Edit compose.yml:

version: "3"

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "totp"
      FLATNOTES_USERNAME: user
      FLATNOTES_PASSWORD: "<password>"
      FLATNOTES_SECRET_KEY: "<32 random characters>"
      FLATNOTES_TOTP_KEY: "<32 random characters>"
    volumes:
      - "./data:/data"
      # Optional. Allows you to save the search index in a different location:
      - "./index:/data/.flatnotes"
    ports:
      - "12005:8080"
    restart: unless-stopped

1. Set FLATNOTES_USERNAME and FLATNOTES_PASSWORD. These will be your username and password.
2. Set 32 random characters for FLATNOTES_SECRET_KEY and FLATNOTES_TOTP_KEY.
3. If you do not want to use TOTP, change FLATNOTES_AUTH_TYPE to “password” and delete FLATNOTES_TOTP_KEY.

If you change FLATNOTES_AUTH_TYPE to “read_only”, your Flatnotes becomes visible to anyone, but you can’t login.

If your password has a $ symbol, write $$ instead. This is because Docker thinks $ is a variable name and $$ tells it to use a normal $.

(Retrieved from flatnotes GitHub on January 25, 2025)

Save your docker-compose.yml.

Print QR code and TOTP key for 2-step verification (skip this step if you’re using FLATNOTES_AUTH_TYPE: “password”):

docker logs flatnotes

You can scan the QR code with your phone or manually copy TOTP key, which looks something like ABCDEFGHIJKL====

Caddy#

Install Caddy:

apt install caddy
sudo systemctl enable caddy

Open Caddyfile:

nano /etc/caddy/Caddyfile

Edit Caddyfile:

example.com {
  # You can use a different name instead of "/notes."
  route /notes* {
    uri strip_prefix /notes
    redir https://notes.{host}{uri}
  }
}

# To use a different port, change the "ports:" section in your docker-compose.yml file.
notes.example.com {
  reverse_proxy localhost:12005
  redir / /search?term=*&sortBy=1 permanent
  encode zstd gzip
}

Restart Caddy:

sudo systemctl restart caddy

Go to Flatnotes at https://notes.example.com or at https://example.com/notes if you prefer using a subpath.

Flatnotes Customization#

You can add more variables to “environment:” section in docker-compose.yml to customize your Flatnotes setup. After making changes to docker-compose.yml file, restart Docker by running docker compose down; docker compose up -d.

FLATNOTES_SESSION_EXPIRY_DAYS: Login session lifetime in days. The default is 30 days. Set to 365 if you don’t want to be logged out automatically for a long time. FLATNOTES_QUICK_ACCESS_LIMIT: Number of notes to show on homepage. Default is 4. FLATNOTES_QUICK_ACCESS_HIDE: Set to “true” to hide notes on homepage. Default is “false”. FLATNOTES_QUICK_ACCESS_SORT: Value can be “score”, “title”, and “lastModified”. Default is “lastModified”.

You can find more variables in FlatNotes GitHub Wiki.

(Retrieved from flatnotes GitHub Wiki on January 25, 2025)