flatnotes Documentation

To run flatnotes as a standalone Docker container, use the following command. This example configures password authentication and maps a local ./data directory to the container's /data volume.

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

For a persistent deployment, use Docker Compose. This configuration includes environment variables for authentication and volume mapping for your markdown files.

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

Attachments can be uploaded and downloaded. If auth_type is READ_ONLY, you can only download files.

• Download an attachment: GET /api/attachments/{filename} or GET /attachments/{filename}. The latter is a secondary route for relative URL usage.
• Upload an attachment: POST /api/attachments. Requires a file upload. Returns 409 if the attachment already exists.

Perform full-text searches across all notes or retrieve the list of indexed tags.

Search Notes GET /api/search

• term (string, required): The search query.
• sort (string, optional): One of score, title, or lastModified. Defaults to score.
• order (string, optional): asc or desc. Defaults to desc.
• limit (int, optional): Maximum number of results.

Get Tags GET /api/tags Returns a list of all indexed tags as strings.

Flatnotes provides endpoints to interact with notes. Note access is subject to the configured auth_type. If auth_type is READ_ONLY, only GET requests are permitted.

• Get a note: GET /api/notes/{title}. Returns a Note object. Returns 404 if not found.
• Create a note: POST /api/notes. Requires a NoteCreate payload. Returns 409 if the note already exists.
• Update a note: PATCH /api/notes/{title}. Requires a NoteUpdate payload. Returns 404 if not found or 409 if there is a conflict.
• Delete a note: DELETE /api/notes/{title}. Returns 404 if not found.

Use these lightweight endpoints for monitoring and verifying connectivity:

• Healthcheck: GET /health. Returns OK if the server is running.
• Auth Check: GET /api/auth-check. Returns OK if the request is successfully authenticated. This endpoint requires valid authentication dependencies.