Skip to content

gamosoft/NoteDiscovery

BranchesTags

Repository files navigation

📝 NoteDiscovery

Your Self-Hosted Knowledge Base

What is NoteDiscovery?

NoteDiscovery is a lightweight, self-hosted note-taking application that puts you in complete control of your knowledge base. Write, organize, and discover your notes with a beautiful, modern interface—all running on your own server.

Note Discovery

🎯 Who is it for?

  • Privacy-conscious users who want complete control over their data
  • Developers who prefer markdown and local file storage
  • Knowledge workers building a personal wiki or second brain
  • Teams looking for a self-hosted alternative to commercial apps
  • Anyone who values simplicity, speed, and ownership

✨ Why NoteDiscovery?

vs. Commercial Apps (Notion, Evernote, Obsidian Sync)

Feature NoteDiscovery Commercial Apps
Cost 100% Free $xxx/month/year
Privacy Your server, your data Their servers, their terms
Speed Lightning fast Depends on internet
Offline Always works Limited or requires sync
Customization Full control Limited options
No Lock-in Plain markdown files Proprietary formats

Key Benefits

  • 🔒 Total Privacy - Your notes never leave your server
  • 🔐 Optional Authentication - Simple password protection for self-hosted deployments
  • 💰 Zero Cost - No subscriptions, no hidden fees
  • 🚀 Fast & Lightweight - Instant search and navigation
  • 🎨 Beautiful Themes - Multiple themes, easy to customize
  • 🔌 Extensible - Plugin system for custom features
  • 📱 Responsive - Works on desktop, tablet, and mobile
  • 📂 Simple Storage - Plain markdown files in folders
  • 🧮 Math Support - LaTeX/MathJax for beautiful equations
  • 📄 HTML Export - Share notes as standalone HTML files

🚀 Quick Start

Running from GitHub Container Registry (Easiest & Recommended)

Use the pre-built image directly from GHCR - no building required!

💡 Tip: Always use ghcr.io/gamosoft/notediscovery:latest to get the newest features and fixes.

📁 Important - Volume Mapping: The container needs local folders/files to work:

  • Required: data folder - Your personal notes will be stored here (create an empty folder)
  • Required: themes folder with theme .css files (at least a single theme must exist)
  • Required: plugins folder (can be empty for basic functionality)
  • Required: config.yaml file (needed for the app to run)
  • Optional: documentation folder - If you cloned the repo, mount this to view app docs inside NoteDiscovery

Setup Options:

  1. Minimal (quick test - download just the essentials):

    # Linux/macOS
mkdir -p data plugins themes  # data/ is for YOUR notes
curl -O https://raw.githubusercontent.com/gamosoft/notediscovery/main/config.yaml
# Download at least light and dark themes
curl -o themes/light.css https://raw.githubusercontent.com/gamosoft/notediscovery/main/themes/light.css
curl -o themes/dark.css https://raw.githubusercontent.com/gamosoft/notediscovery/main/themes/dark.css
    # Windows PowerShell
mkdir data, plugins, themes -Force  # data\ is for YOUR notes
Invoke-WebRequest -Uri https://raw.githubusercontent.com/gamosoft/notediscovery/main/config.yaml -OutFile config.yaml
# Download at least light and dark themes
Invoke-WebRequest -Uri https://raw.githubusercontent.com/gamosoft/notediscovery/main/themes/light.css -OutFile themes/light.css
Invoke-WebRequest -Uri https://raw.githubusercontent.com/gamosoft/notediscovery/main/themes/dark.css -OutFile themes/dark.css

  2. Full Setup (recommended - includes all themes, plugins, and documentation):

    git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery
# The data/ folder is empty - for your personal notes
# The documentation/ folder has app docs you can optionally mount

🔐 Security Note: Authentication is disabled by default with password admin. For testing/local use, this is fine. If exposing to a network, change the password immediately - see AUTHENTICATION.md for instructions on how to enable it.

Option 1: Docker Compose (Recommended)

💡 Multi-Architecture Support: Docker images are available for both x86_64 and ARM64 (Raspberry Pi, Apple Silicon, etc.)

# Download the docker-compose file
curl -O https://raw.githubusercontent.com/gamosoft/notediscovery/main/docker-compose.ghcr.yml

# Or if you cloned the repo, just use it directly
docker-compose -f docker-compose.ghcr.yml up -d

# Access at http://localhost:8000
# Login with default password: admin

# View logs
docker-compose -f docker-compose.ghcr.yml logs -f

# Stop the application
docker-compose -f docker-compose.ghcr.yml down

Option 2: Docker Run (Alternative)

# Linux/macOS
docker run -d \
  --name notediscovery \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/plugins:/app/plugins \
  -v $(pwd)/themes:/app/themes \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --restart unless-stopped \
  ghcr.io/gamosoft/notediscovery:latest
# Windows PowerShell
docker run -d `
  --name notediscovery `
  -p 8000:8000 `
  -v ${PWD}/data:/app/data `
  -v ${PWD}/plugins:/app/plugins `
  -v ${PWD}/themes:/app/themes `
  -v ${PWD}/config.yaml:/app/config.yaml `
  --restart unless-stopped `
  ghcr.io/gamosoft/notediscovery:latest

Access at http://localhost:8000

Why use the GHCR image?

  • ✅ No build time - instant deployment
  • ✅ Always up-to-date with the latest release
  • ✅ Tested and verified builds
  • ✅ Smaller download with optimized layers

Running with Docker Compose (Recommended for Development)

Docker ensures consistent environment and easy deployment:

# Clone the repository
git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery

# Start with Docker Compose
docker-compose up -d

# Access at http://localhost:8000

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

Requirements:

  • Docker
  • Docker Compose

Running Locally (Without Docker)

For development or if you prefer running directly:

# Clone the repository
git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

# Access at http://localhost:8000

Requirements:

  • Python 3.8 or higher
  • pip (Python package manager)

Dependencies installed:

  • FastAPI - Web framework
  • Uvicorn - ASGI server
  • PyYAML - Configuration handling
  • aiofiles - Async file operations

📚 Documentation

Want to learn more?

  • 🎨 THEMES.md - Theme customization and creating custom themes
  • ✨ FEATURES.md - Complete feature list and keyboard shortcuts
  • 🧮 MATHJAX.md - LaTeX/Math notation examples and syntax reference
  • 📊 MERMAID.md - Diagram creation with Mermaid (flowcharts, sequence diagrams, and more)
  • 🔌 PLUGINS.md - Plugin system and available plugins
  • 🌐 API.md - REST API documentation and examples
  • 🔐 AUTHENTICATION.md - Enable password protection for your instance

💡 Pro Tip: If you clone this repository, you can mount the documentation/ folder to view these docs inside the app:

# In your docker-compose.yml
volumes:
  - ./data:/app/data              # Your personal notes
  - ./documentation:/app/data/docs:ro  # Mount docs subfolder inside the data folder (read-only)

Then access them at http://localhost:8000 - the docs will appear as a docs/ folder in the file browser!

💖 Support Development

If you find NoteDiscovery useful, consider ☕ buying me a coffee to help keep the project going. Every bit helps with new features, bug fixes, and improvements. Thank you!

🔒 Security Considerations

NoteDiscovery is designed for self-hosted, private use. Please keep these security considerations in mind:

Network Security

  • ⚠️ Do NOT expose directly to the internet without additional security measures
  • Run behind a reverse proxy (nginx, Caddy) with HTTPS for production use
  • Keep it on your local network or use a VPN for remote access
  • By default, the app listens on 0.0.0.0:8000 (all network interfaces)

Authentication

  • Password protection is ENABLED by default with password: admin
  • ⚠️ CHANGE THE DEFAULT PASSWORD IMMEDIATELY if exposing to a network!
  • See AUTHENTICATION.md for complete setup instructions
  • To disable auth, set security.enabled: false in config.yaml
  • Change password with Docker: docker-compose exec notediscovery python generate_password.py
  • Perfect for single-user or small team deployments
  • For multi-user setups, consider a reverse proxy with OAuth/SSO

Data Privacy

  • Your notes are stored as plain text markdown files in the data/ folder
  • No data is sent to external services
  • Regular backups are recommended

Best Practices

  • Run on localhost or a private network only
  • Use Docker for isolation and easier security management
  • Keep your system and dependencies updated
  • Review and audit any plugins you install
  • Set appropriate file permissions on the data/ directory

TL;DR: Perfect for personal use on your local machine or home network. Enable built-in password protection if needed, or use a reverse proxy with authentication if exposing to wider networks.

📄 License

MIT License - Free to use, modify, and distribute.

Made with ❤️ for the self-hosting community

About

Your Self-Hosted Knowledge Base

Topics

python docker markdown open-source alternative privacy self-hosted free note note-taking evernote knowledge-base obsidian notion onenote hosted fastapi

Resources

Readme

License

MIT license
Activity

Stars

944 stars

Watchers

9 watching

Forks

80 forks
Report repository

Releases 6

v0.3.0 - Added Image Support Latest
Nov 20, 2025
+ 5 releases

Sponsor this project

Packages

 
 
 

Languages