Getting Started & Installation

🚀 Getting Started & Installation

Flatnotes-Enhanced can be deployed in two ways: Docker (recommended, easiest) or manual installation (for developers). This guide covers both options.

Note

This is a community fork with limited support. For issues with the original Flatnotes, refer to the original Flatnotes documentation.

Important

Security upgrade recommended: Version 1.18.2 fixes four privately reported security issues, including cross-site scripting in the note viewer and path traversal in note paths. Upgrading is strongly recommended for every installation. No configuration or database changes are required.

---

Prerequisites

For Docker (Recommended)

• Docker installed on your system
• Supports linux/amd64 and linux/arm64 (Raspberry Pi, Apple Silicon)
• About 500MB disk space for the image

For Manual Installation

• Python 3.13+
• Node.js 20+ (recommended: 24+)
• uv for Python dependency management
• Familiarity with the command line
• About 2GB disk space

---

🐳 Quick Start with Docker (Easiest)

Using the Pre-built Image

The easiest way — pull the pre-built image from Docker Hub:

docker run -d \
  --name flatnotes-enhanced \
  -p 8080:8080 \
  -v ./data:/data \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  -e "FLATNOTES_SECRET_KEY=changeMeToo-a-long-random-string" \
  dockerbobw/flatnotes-enhanced:latest

Then open your browser to: http://localhost:8080

What this does:

• -p 8080:8080 — Exposes Flatnotes on port 8080
• -v ./data:/data — Stores all notes and settings in the ./data folder
• -e ... — Sets environment variables (auth type, username, password, secret key)

Note

FLATNOTES_SECRET_KEY is required when using password or TOTP auth. It signs login tokens — if it changes, existing sessions are invalidated. Generate one with openssl rand -hex 32.

Building Your Own Image

Prefer to build the image yourself?

# Clone the repository
git clone https://github.com/BobWs/flatnotes-enhanced.git
cd flatnotes-enhanced

# Build the image
docker build -t flatnotes-enhanced:latest .

# Run the container
docker run -d \
  --name flatnotes-enhanced \
  -p 8080:8080 \
  -v ./data:/data \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  -e "FLATNOTES_SECRET_KEY=changeMeToo-a-long-random-string" \
  flatnotes-enhanced:latest

Want Docker Compose instead?

For a persistent setup, Docker Compose is easier to maintain than a long docker run command. See the Docker Compose Examples page for complete examples covering secrets, SSO, reverse proxy, and NAS deployments.

---

📦 Manual Installation

For developers or specific deployment needs.

Step 1: Clone the Repository

git clone https://github.com/BobWs/flatnotes-enhanced.git
cd flatnotes-enhanced

Step 2: Install Python Dependencies

The project uses uv for Python dependency management.

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies (creates .venv and installs packages)
uv sync

Step 3: Install Frontend Dependencies

npm ci

Step 4: Build the Frontend

npm run build

This creates optimized frontend files in client/dist/.

Step 5: Run the Server

# Activate the virtual environment
source .venv/bin/activate

# Run the server
uvicorn server.main:app --host 0.0.0.0 --port 8080

# Or with auto-reload for development:
uvicorn server.main:app --reload --host 0.0.0.0 --port 8080

The server starts on: http://localhost:8080

---

🌍 Environment Variables

Configure Flatnotes-Enhanced behavior with environment variables.

Essential Variables

Variable	Default	Description	Example
FLATNOTES_AUTH_TYPE	password	Authentication method	none, read_only, password, totp, oidc
FLATNOTES_USERNAME	(required)	Login username	user
FLATNOTES_PASSWORD	(required)	Login password	changeMe!
FLATNOTES_SECRET_KEY	(required)	JWT token signing secret	openssl rand -hex 32

Optional Variables

Variable	Default	Description
FLATNOTES_PATH	/data	Where to store notes on disk
FLATNOTES_HOST	0.0.0.0	Server bind address
FLATNOTES_PORT	8080	Server port
FLATNOTES_TRASH_DAYS	0	Auto-delete trash older than N days (0 = disabled)
ENABLE_DATABASE	true	Enable SQLite database for settings
DATABASE_PATH	/data/.flatnotes/flatnotes.db	SQLite database location
DATABASE_ECHO	false	Log SQL statements (debugging only)
LOGLEVEL	INFO	Logging level: DEBUG, INFO, WARNING, ERROR

A full reference — including SSO, branding, and showcase-mode variables — is in the README.

Authentication Types

none — No authentication. Anyone can access.

FLATNOTES_AUTH_TYPE=none

read_only — View-only access. Cannot create/edit notes. As of v1.18.2, state-changing API routes (settings, backup, restore, trash, archive-delete, sharing) return 403 for write requests. View-only share links continue to work.

FLATNOTES_AUTH_TYPE=read_only
FLATNOTES_USERNAME=user
FLATNOTES_PASSWORD=password

password — Standard username/password login (default).

FLATNOTES_AUTH_TYPE=password
FLATNOTES_USERNAME=user
FLATNOTES_PASSWORD=changeMe!
FLATNOTES_SECRET_KEY=your-secret-key-here

totp — Two-factor authentication with an authenticator app (e.g., Google Authenticator).

FLATNOTES_AUTH_TYPE=totp
FLATNOTES_USERNAME=user
FLATNOTES_PASSWORD=password
FLATNOTES_SECRET_KEY=your-secret-key-here
FLATNOTES_TOTP_KEY=your-totp-key-here

oidc — Single Sign-On via OIDC or OAuth2. See the README's SSO section for full configuration.

Generate secure keys:

# Secret key
openssl rand -hex 32

# TOTP key
openssl rand -base64 32

---

🐳 Docker Compose Setup

Running Flatnotes-Enhanced with Docker Compose gives you persistent, version-controllable configuration.

Basic Configuration

Create a compose.yml file:

services:
  flatnotes-enhanced:
    container_name: flatnotes-enhanced
    image: dockerbobw/flatnotes-enhanced:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      TZ: "Europe/Berlin"
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "changeMeToo-a-long-random-string"
      ENABLE_DATABASE: "true"

Note

The version: key is no longer needed — it's deprecated in Compose v2.

Common commands:

# Start the service
docker compose up -d

# Stop the service
docker compose down

# View logs
docker compose logs -f flatnotes-enhanced

# Update to the latest image
docker compose pull
docker compose up -d

More scenarios — Docker secrets, SSO/OIDC, reverse proxy, and Synology/NAS bind mounts — are covered in Docker Compose Examples.

---

Accessing Flatnotes-Enhanced

Initial Login

1. Open http://localhost:8080 (or your configured URL)
2. Enter the username and password from your environment variables
3. You're in! Create your first note.

First Time Setup Tips

• Settings → Preferences — Add your display name and avatar
• Settings → Callouts — Customize callout types (optional)
• Settings → Appearance — Configure header and highlight colors (optional)
• Navbar → Theme — Pick one of the 16 built-in color themes
• Settings → Branding — Add a custom name, logo, and accent color (optional)
• Create a _templates folder for reusable note templates
• Start organizing with Folders and Tags

---

Data Persistence

Your notes are stored in the /data volume:

/data/
├── notes/                    # Your markdown notes
├── .flatnotes/
│   ├── flatnotes.db          # SQLite database (settings, metadata)
│   ├── backups/              # Automatic preferences backups
│   ├── brand/                # Custom logo and favicon (if set)
│   └── *.meta.json           # Note metadata (creation/modified dates)
└── attachments/              # File attachments (PDFs, documents, etc.)

• Docker: Volume is mapped to ./data on your host machine
• Manual: Volume is at /data (or the FLATNOTES_PATH environment variable)

Tip

Back this up. The /data folder holds everything — notes, settings, backups, and branding.

---

🔒 Security Recommendations

Change Default Credentials

Never use default usernames/passwords in production:

FLATNOTES_USERNAME=your_secure_username
FLATNOTES_PASSWORD=your_strong_password_here
FLATNOTES_SECRET_KEY=your_long_random_string_here

Use HTTPS in Production

If exposing Flatnotes-Enhanced to the internet, use HTTPS via a reverse proxy:

• Nginx — Popular, free
• Caddy — Simple, auto-HTTPS
• Nginx Proxy Manager — GUI-based setup

Note

HTTPS matters for more than confidentiality: SSO callback URLs and the clipboard API both expect a secure context.

Enable Two-Factor Authentication (TOTP)

For enhanced security, use TOTP:

FLATNOTES_AUTH_TYPE=totp
FLATNOTES_TOTP_KEY=generated-totp-key

After logging in, scan the QR code from Settings → Preferences with your authenticator app.

Keep Backups

Regularly back up your /data volume:

# Backup
docker cp flatnotes-enhanced:/data ./backup-$(date +%Y%m%d)

# Restore
docker cp ./backup-20240101 flatnotes-enhanced:/data

---

Reverse Proxy Setup (Optional)

To run Flatnotes-Enhanced behind a reverse proxy (e.g., Nginx or Caddy).

Nginx Example

server {
    server_name notes.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Authorization $http_authorization;
    }
}

Caddy Example

notes.example.com {
    reverse_proxy localhost:8080
}

Note

Running the reverse proxy in Docker? See Docker Compose Examples for the shared-network pattern.

---

Troubleshooting

Container Won't Start

Check the logs:

docker logs flatnotes-enhanced

Common causes:

• Missing required environment variables — check FLATNOTES_SECRET_KEY
• Port already in use — change -p 8080:8080 to a different port
• Volume permissions issue — ensure the /data folder is writable

Can't Connect to http://localhost:8080

• Check if the container is running: docker ps
• Check if port 8080 is in use: lsof -i :8080 (macOS/Linux)
• Try a different port: -p 8081:8080 and visit http://localhost:8081

Login Not Working

• Username and password match your environment variables
• FLATNOTES_SECRET_KEY is set (required for password auth)
• If using TOTP, the code is correct and within the 30-second window
• If using OIDC, the redirect URI matches exactly what's registered with your provider

Notes Not Persisting

• Volume is mounted: -v ./data:/data
• /data folder exists and is writable
• Container is stopped gracefully (not killed)

Upgrading to a Newer Version

Note

Upgrading from a version before 1.18.2? No action is required beyond pulling the new image. The security fixes are automatic. If you use FLATNOTES_AUTH_TYPE=read_only, verify that any external scripts or integrations that relied on previously unblocked write routes are updated.

With Docker Compose:

docker compose pull
docker compose up -d

With plain docker run:

# Pull the latest image
docker pull dockerbobw/flatnotes-enhanced:latest

# Stop and remove the old container
docker stop flatnotes-enhanced
docker rm flatnotes-enhanced

# Run the new version (same docker run command as before)
docker run -d \
  --name flatnotes-enhanced \
  -p 8080:8080 \
  -v ./data:/data \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  -e "FLATNOTES_SECRET_KEY=changeMeToo-a-long-random-string" \
  dockerbobw/flatnotes-enhanced:latest

Your notes are safe — they're stored in the /data volume and persist across upgrades.

---

Multi-Instance Setup

Running two separate instances (e.g., work and personal notes) on the same server?

Flatnotes-Enhanced fully supports this. Each instance needs:

• Its own port or domain
• Its own /data volume
• Its own FLATNOTES_SECRET_KEY
• Its own FLATNOTES_TOTP_KEY (if using TOTP)

See the Multi-Instance Setup page for a full walkthrough.

---

Getting Help

Common Resources

• Wiki — Browse the Flatnotes-Enhanced wiki for feature guides
• GitHub Issues — Report bugs or request features
• Original Flatnotes — For compatibility questions, see the original project

Limitations

This is a community fork with limited support. We do our best, but:

• Support is on a best-effort basis
• For original Flatnotes issues, refer to the original project
• Development resources are limited

---

Next Steps

• ✅ Flatnotes-Enhanced is running
• 📚 Read the wiki pages: Folders, Tags, Settings
• 🎨 Customize your experience in Settings
• 📝 Start creating and organizing notes!

See Also

• Docker Compose Examples — Secrets, SSO, reverse proxy, NAS deployments
• Folders & Organization - Managing notes
• Tags System - Organizing with tags
• Note Management - Trash, archive, templates
• Settings & Customization - Appearance and behavior
• Multi-Instance Setup - Running multiple instances