NoteHub 📝

A modern, secure, and feature-rich personal notes application with a React SPA frontend and Node.js/Express API backend.

🖼️ Screenshots

Click to view screenshots

Core Features

Login Page with Google OAuth

Login with username/password or one-click Google Sign-In

Notes Dashboard

Organize notes with tags, search, favorites, and pinning

Note Editor

Rich markdown editor with live preview

Tasks Management

Track tasks with priorities and due dates

Dark Mode

Beautiful dark theme with glassmorphism design

New Features (December 2024)

UI/UX Improvements

Clean, modern design with Apple-inspired glassmorphism

NotesPage & TasksPage:

Removed redundant elements for cleaner interface
Consistent modern design across both pages
Improved mobile experience with better dock positioning
Enhanced folder management with glassmorphism effects

Mobile Navigation:

Fixed minimized dock visibility on mobile landscape
Scrollable expanded dock for small screens
Improved tap targets and touch interactions

Folder Management:

Always visible 3-dot menu on mobile
Glassmorphism design with smooth animations
Confirmation modal for safe deletions
Improved context menu positioning

📋 Detailed Changes: See UI Improvements Documentation

Google OAuth Single Sign-On

One-click sign-in with automatic account creation

Simplified 2FA Management

Disable 2FA without entering OTP code (already authenticated via JWT)

Admin Dashboard

User management with 2FA recovery tools

Admin 2FA Recovery

Admins can disable user 2FA for account recovery (lost devices, emergencies)

Note: To add actual screenshots, see Screenshot Capture Guide

🏗️ Tech Stack

Layer	Technology
Frontend	Vite + React 19 + TypeScript
Backend	Node.js + Express
ORM	Sequelize
Database	SQLite (dev) / MySQL (prod)
Replication	Read replicas (MySQL + SQLite)
Caching	Redis (optional)
Search	Elasticsearch (optional)
Authentication	JWT + Google OAuth 2.0 (optional)
API	RESTful with JWT authentication
Reverse Proxy	Traefik v2.11 (automatic routing)
Monitoring	Prometheus + Grafana
Logging	Winston + Graylog (optional)
Deployment	Docker + Traefik + Hetzner VPS
CI/CD	GitHub Actions + GitHub Pages

🚀 Recent Improvements

UI/UX Improvements (December 2024)

🎨 Modern Design System - Apple-inspired glassmorphism across the application
- Consistent modern header design on Notes and Tasks pages
- Removed redundant UI elements for cleaner interface
- Enhanced visual hierarchy with gradient badges and modern buttons
📱 Mobile Experience - Significantly improved mobile usability
- Fixed dock positioning on mobile landscape view
- Scrollable navigation dock for small screens
- Improved touch targets and tap actions
- Better folder management on mobile devices
📁 Folder Management - Enhanced folder interaction and safety
- Always visible 3-dot menu on mobile (hover on desktop)
- Glassmorphism effects with smooth animations
- Confirmation modal prevents accidental deletions
- Increased spacing and improved context menu positioning
✨ See Detailed UI Changes Documentation

Architecture Improvements (December 2024)

🔄 Traefik Integration - Migrated from nginx to Traefik for better container-native routing
- Automatic service discovery via Docker labels
- Dynamic configuration without restarts
- SSL/HTTPS enabled by default with automatic Let's Encrypt certificates
- HTTP to HTTPS redirect with HSTS security headers
- Modern dashboard and monitoring
- ⚠️ Using a custom domain? See TROUBLESHOOTING_SSL.md to fix certificate warnings
📊 Prometheus + Grafana Monitoring - Complete observability stack
- Real-time application metrics (requests, latency, errors)
- System metrics (CPU, memory, disk, network)
- Container metrics via cAdvisor
- Pre-built Grafana dashboards
- Optimized for 2GB RAM VPS (~1GB overhead)
- No port conflicts with NoteHub or Drone CI
- See MONITORING_QUICKSTART.md for setup

Performance Enhancements (December 2024)

⚡ 10x Faster Queries - Redis caching reduces note list operations from 80ms to 8ms
🔍 5x Faster Search - Elasticsearch integration improves search from 150ms to 30ms
🗄️ SQL Optimization - Added 4 composite indexes for complex query patterns
🔄 Database Replication - Read replicas for improved performance and high availability
📊 Performance Benchmarks:

Operation Before After Improvement

List notes 80ms 8ms 10x

Search notes 150ms 30ms 5x

Get tags 40ms 4ms 10x

Read operations (with replicas) 80ms 25ms 3x

Security Improvements (December 2024)

🔑 Strengthened Password Hashing - Upgraded from bcrypt 12 to 14 rounds (4x more secure)
🔄 Automatic Hash Upgrades - Opportunistic rehashing on login (transparent to users)
🔐 Simplified 2FA Management - Remove 2FA without entering OTP code
👨‍💼 Admin 2FA Recovery - Admins can disable user 2FA for account recovery
📝 Privacy-Compliant Logging - GDPR/CCPA compliant audit trails

New Features (December 2024)

🔑 Google OAuth SSO - One-click sign-in with automatic account creation
🧪 Comprehensive Test Suite - 94+ tests covering all features and security
📚 Extensive Documentation - 50K+ words of guides and technical docs
⚙️ Configuration Management - Centralized, environment-tunable settings

All new features are optional and designed for graceful degradation. NoteHub continues to work perfectly in SQL-only mode.

✨ Features

Core Features

📝 Rich Markdown Editor - Full markdown support with live preview
🏷️ Smart Organization - Tags, favorites, pinning, and powerful search
✅ Task Management - Create and track tasks with priorities and due dates
👥 Collaboration - Share notes with other users with view/edit permissions
🎨 Customizable UI - Light/dark mode, responsive glassmorphism design
🌍 Internationalization (i18n) - Multi-language support (English, German, Vietnamese, Japanese)
📱 Mobile-Friendly - Works seamlessly on all devices, installable as PWA
👤 User Profiles - Customizable profiles with themes and bio
🔌 Offline Mode - Full offline support with automatic sync when reconnected

Security & Authentication

🔐 Two-Factor Authentication - TOTP-based 2FA with QR code setup and simplified management
🔑 Google OAuth Single Sign-On - One-click sign-in with automatic account creation
🔒 Strengthened Password Security - bcrypt with 14 rounds (4x more secure) and automatic hash upgrades
🛡️ Admin Controls - Admin dashboard with user management and 2FA recovery tools
📋 Audit Logging - Comprehensive security event logging (GDPR/CCPA compliant)

Performance & Scalability

⚡ Redis Caching - Optional 10x performance boost for frequently accessed data
🔍 Elasticsearch Integration - Optional full-text search with fuzzy matching (5x faster)
🗄️ SQL Query Optimization - Composite indexes for complex query patterns
📊 Performance Monitoring - Built-in query performance tracking
💾 IndexedDB Storage - Large offline data capacity with automatic caching

Developer Experience

🧪 Comprehensive Test Suite - 34 frontend tests with snapshot testing, 60+ backend integration tests
🔧 TypeScript Support - Full type safety across the frontend
📦 Modular Architecture - Clean separation of concerns with service layers
📚 Extensive Documentation - 50K+ words covering all features and setup

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Git
Redis (optional, for caching)
Elasticsearch (optional, for full-text search)
Google OAuth credentials (optional, for SSO)

Local Development

1. Clone the Repository

git clone https://github.com/thienng-it/note-hub.git
cd note-hub

2. Backend Setup (Node.js/Express API)

cd backend

# Install dependencies
npm install

# Configure environment (copy from example)
cp .env.example .env
nano .env  # Edit with your values

# Required settings:
export JWT_SECRET="your-secret-key-here"
export NOTES_ADMIN_PASSWORD="your-secure-password"

# Optional performance enhancements:
export REDIS_URL="redis://localhost:6379"                  # 10x faster queries
export ELASTICSEARCH_NODE="http://localhost:9200"          # 5x faster search

# Optional Google OAuth SSO:
export GOOGLE_CLIENT_ID="your-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-secret"
export GOOGLE_REDIRECT_URI="http://localhost:3000/auth/google/callback"

# Run the backend API
npm run dev
# Backend API runs at http://localhost:5000

Note: All optional services (Redis, Elasticsearch, Google OAuth) are designed for graceful degradation. The app works perfectly without them, falling back to SQL-only mode.

3. Frontend Setup (Vite + React)

cd frontend

# Install dependencies
npm install

# Configure environment (copy from example)
cp .env.example .env

# Edit .env and set VITE_API_URL to your backend URL
# For development: VITE_API_URL=http://localhost:5000
# For production: Leave empty to use same origin
nano .env

# Run development server
npm run dev
# Frontend runs at http://localhost:5173

Important for Chat Feature: The VITE_API_URL environment variable is required in development for WebSocket connections to work. Without it, Socket.io will try to connect to the frontend dev server instead of the backend.

🐳 Docker Deployment

NoteHub supports multiple deployment modes:

Development Mode (SQLite, local testing)

Recommended: Use docker-compose.dev.yml (no registry cache issues)

# Copy and configure environment (REQUIRED)
cp .env.example .env
nano .env  # Set NOTES_ADMIN_PASSWORD and other values

# Build and run with simplified development configuration
docker compose -f docker-compose.dev.yml up -d

# Seed the database with sample data
docker compose -f docker-compose.dev.yml exec backend node scripts/seed_db.js

# Access at http://localhost
# Note: Uses HTTP for simple local development (no certificate warnings)

Alternative: Use standard docker-compose.yml

# If docker-compose.dev.yml doesn't work, use standard compose file
# Note: May show registry cache warnings (403 Forbidden from ghcr.io) - these can be ignored
docker compose up -d

# Seed the database
docker compose exec backend node scripts/seed_db.js

Development with MySQL

# Set required MySQL credentials in .env first
# MYSQL_ROOT_PASSWORD, MYSQL_USER, MYSQL_PASSWORD

# Run with MySQL profile
docker compose --profile mysql up -d

# Seed the MySQL database
docker compose exec backend-mysql node scripts/seed_db.js

# Access at http://localhost or https://localhost (production config uses HTTPS)

Production Mode (Cloud Database)

For production deployments connecting to external databases (PlanetScale, AWS RDS, etc.):

# Configure production environment
cp .env.example .env
nano .env

# Set these variables for production:
# SECRET_KEY=<strong-random-key>
# DATABASE_URL=mysql://user:password@your-cloud-db:3306/notehub
# NOTES_ADMIN_PASSWORD=<secure-admin-password>
# ACME_EMAIL=admin@yourdomain.com  # For Let's Encrypt SSL certificates

# Run with production profile
docker compose --profile production up -d

# NOTE: Do NOT run seed script in production!
# Database should be pre-configured via cloud provider's management console.

# Access at https://yourdomain.com (automatic SSL via Let's Encrypt)
# Ensure your domain points to your server and ports 80/443 are open

Important: The seed script is blocked in production mode to prevent accidental data modification. Use your cloud database provider's tools to manage production data.

Or build individual images:

# Build backend
docker build -f Dockerfile.backend.node -t notehub-backend .

# Build frontend
docker build -f Dockerfile.frontend -t notehub-frontend .

Default Credentials

After running the seed script, use these credentials to login:

Admin: admin / (password set in NOTES_ADMIN_PASSWORD env var)
Demo: demo / Demo12345678!

📦 Project Structure

note-hub/
├── frontend/                  # Vite + React frontend (SPA)
│   ├── src/
│   │   ├── api/               # API client with JWT handling
│   │   ├── components/        # React components
│   │   ├── context/           # Auth and Theme contexts
│   │   ├── pages/             # Page components
│   │   ├── types/             # TypeScript types
│   │   └── test/              # Test setup
│   ├── public/                # Static assets
│   ├── vite.config.ts         # Vite + Vitest configuration
│   └── package.json           # Frontend dependencies
├── backend/                   # Node.js/Express API
│   ├── src/
│   │   ├── routes/            # API route handlers
│   │   ├── services/          # Business logic
│   │   ├── middleware/        # Authentication middleware
│   │   ├── config/            # Database configuration
│   │   └── index.js           # Application entry point
│   ├── tests/                 # Backend test suite
│   └── package.json           # Backend dependencies
├── scripts/                   # Utility scripts
│   └── seed_db.js             # Database seeding script
├── docker/                    # Docker configuration
│   └── nginx.conf             # nginx config for frontend
├── docker-compose.yml         # Full stack deployment
├── Dockerfile.backend.node    # Backend Docker image
└── Dockerfile.frontend        # Frontend Docker image

🧪 Testing

NoteHub includes a comprehensive test suite with 94+ tests covering frontend UI, backend integration, and security features.

# Frontend tests (34 tests)
cd frontend
npm test                     # Run all tests
npm run test:coverage        # With coverage report

# Backend tests (60+ tests)
cd backend
npm test                     # Run all tests
npm test -- --coverage       # With coverage report

# Lint and type-check
cd frontend
npm run lint                 # ESLint
npm run type-check           # TypeScript compilation

cd backend
npm run lint                 # ESLint

Test Coverage

✅ Frontend: Snapshot tests, user interactions, OAuth flows, error handling
✅ Backend: Authentication, 2FA management, Google OAuth, Redis caching, Elasticsearch search
✅ Security: Password hash upgrades, audit logging, admin controls
✅ Integration: E2E flows for all major features

See Test Suite Summary for complete details.

🌐 Deployment Options

Option 1: GitHub Pages (Frontend Only)

The frontend is automatically deployed to GitHub Pages on push to main. Configure the API URL via VITE_API_URL environment variable.

Option 2: Hetzner VPS + Docker (Full Stack)

~€3.50/month with unlimited bandwidth!

Component	Cost	Benefits
Hetzner VPS	€3.29/mo	2 vCPU, 2GB RAM, 40GB SSD
Cloudflare Tunnel	Free	Unlimited bandwidth, DDoS protection, CDN

# On your VPS
git clone https://github.com/thienng-it/note-hub.git
cd note-hub

# Configure
cp .env.example .env
nano .env

# Deploy
docker compose up -d

See Hetzner Deployment Guide for complete setup.

Option 3: Drone CI for Continuous Integration & Deployment

Deploy Drone CI as a standalone, independent CI/CD platform with automated deployment to production. Drone CI does not depend on NoteHub and can be deployed on the same server, a different server, or completely independently.

📘 Note: Drone CI is a completely independent application with its own services, configuration, network, and data storage. It can be deployed anywhere, with or without NoteHub.

Key Features:

🐳 Container-native CI/CD platform
🔗 Automatic GitHub integration
🚀 Parallel pipeline execution
📊 Beautiful web UI on port 8080
✅ Completely independent from NoteHub
🚢 Automated deployment to production on push to main

Automated Deployment Pipeline:

Push to main → Tests → Build → Deploy to VPS
                ✓ Backend tests
                ✓ Frontend tests
                ✓ Linting
                ✓ Type checking
                        ↓
                Auto-deploy to production
                ✓ Zero-downtime deployment
                ✓ Automatic backups
                ✓ Health checks

# Setup Drone CI (independent deployment)
cp .env.drone.example .env.drone
nano .env.drone  # Configure GitHub OAuth and secrets (separate from NoteHub)

# Deploy Drone CI
docker compose --env-file .env.drone -f docker-compose.drone.yml up -d

# Access Drone CI at http://your-server:8080
# Configure deployment secrets in Drone UI
# Push to main branch → Automatic deployment!

Documentation:

DRONE_CI_DEPLOYMENT.md - ⭐ Complete automated deployment guide
DRONE_CI_DEPLOYMENT_QUICK.md - Quick 5-minute setup
DRONE_CI_README.md - Quick start and overview
DRONE_CI_UI_IMPLEMENTATION.md - UI features and verification
DRONE_CI_STANDALONE.md - Complete independence documentation
DRONE_CI_SETUP.md - Detailed setup guide

📚 API Documentation

The API uses JWT authentication with optional Google OAuth 2.0 SSO. Key endpoints:

Authentication

Method	Endpoint	Description
POST	`/api/auth/login`	Login, get JWT token
POST	`/api/auth/refresh`	Refresh access token
GET	`/api/auth/google/status`	Check if Google OAuth enabled
GET	`/api/auth/google`	Get Google OAuth URL
POST	`/api/auth/google/callback`	Complete Google OAuth flow
POST	`/api/auth/2fa/disable`	Disable 2FA (no OTP required)

Notes & Tasks

Method	Endpoint	Description
GET	`/api/notes`	List user's notes (cached if Redis enabled)
POST	`/api/notes`	Create new note
GET	`/api/notes/search`	Full-text search (uses Elasticsearch if enabled)
GET	`/api/notes/:id`	Get note by ID
PATCH	`/api/notes/:id`	Update note
DELETE	`/api/notes/:id`	Delete note
GET	`/api/tasks`	List user's tasks
POST	`/api/tasks`	Create new task

Admin

Method	Endpoint	Description
POST	`/api/admin/users/:userId/disable-2fa`	Admin disable user 2FA

See API Documentation for full reference.

📖 Documentation

Guides

Document	Description
Hetzner Deployment	Deploy to Hetzner VPS
Custom Domain SSL Setup	Fix "not secure" certificate warnings
SSL/HTTPS Setup	SSL certificate configuration
Drone CI README	Quick start for independent Drone CI
Drone CI UI Implementation	UI features, architecture, and verification
Drone CI Standalone	Complete independence documentation
Drone CI Setup	Detailed Drone CI setup guide
Environment Configuration	.env setup and management
Logging Configuration	Structured logging setup
Graylog Setup	Centralized log aggregation and search
Database Replication	Read replicas for MySQL & SQLite
Caching & Search Setup	Redis & Elasticsearch setup
Google OAuth Setup	Configure Google Single Sign-On
Internationalization (i18n)	Multi-language support guide
Contributing	Development guidelines

Architecture & Security

Document	Description
Architecture	System design
API Documentation	REST API reference
Security Guide	Security best practices
Password Security	Password hashing improvements
2FA Improvements	2FA management changes

Investigation & Testing

Document	Description
NoSQL Investigation	SQL vs NoSQL analysis
SQL vs NoSQL Comparison	Detailed comparison
Implementation Summary	Performance enhancements
Test Suite Summary	Complete test documentation

📚 Documentation

All documentation is available in both Markdown and HTML formats for better readability:

Documentation Portal - Beautiful web interface with search functionality
Complete Index - Full list of all documentation files
Getting Started - Project overview and quick start

Building Documentation HTML

The documentation is automatically converted from Markdown to HTML during deployment. To build locally:

# Install dependencies
npm install

# Convert all markdown files to HTML
npm run build:docs

This generates HTML files with consistent styling, syntax highlighting, and easy navigation between documents.

🔧 Troubleshooting

Docker Compose Issues

Cache Registry Errors (403 Forbidden from ghcr.io)

If you see errors like failed to authorize: failed to fetch anonymous token: 403 Forbidden when building:

# Solution 1: Use docker-compose.dev.yml (recommended for local development)
docker compose -f docker-compose.dev.yml up -d

# Solution 2: Use docker-compose.local.yml override
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d

# Solution 3: Ignore the warnings and let the build continue
# The errors are warnings about cache, the build will still succeed
docker compose up -d

Why this happens: The main docker-compose.yml includes cache_from directives that reference GitHub Container Registry (ghcr.io) for faster builds in CI/CD. These require authentication, but local development doesn't need them. The docker-compose.dev.yml file removes these directives.

Network Timeout During Build

If Alpine package manager (apk) fails with "Permission denied" or timeout errors:

# This is usually a temporary network issue. Try:
# 1. Wait a few minutes and retry
docker compose -f docker-compose.dev.yml up -d --build

# 2. Use different DNS (if on Linux)
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# 3. Check your internet connection and firewall settings

Container Won't Start - "NOTES_ADMIN_PASSWORD not set"

# Make sure you've copied and configured .env file
cp .env.example .env
nano .env  # Set NOTES_ADMIN_PASSWORD to a secure password

# Then restart
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d

Local Development Setup

For the best local development experience, we recommend running the backend and frontend directly with npm instead of Docker:

# Terminal 1: Backend
cd backend
npm install
cp .env.example .env  # Configure your .env
npm run dev

# Terminal 2: Frontend
cd frontend
npm install
cp .env.example .env  # Set VITE_API_URL=http://localhost:5000
npm run dev

This provides:

✅ Faster rebuilds (no Docker layer caching needed)
✅ Hot module replacement for instant changes
✅ Better debugging experience
✅ Direct access to logs

Docker Compose is recommended for:

Production-like testing
Testing Traefik routing
Testing with MySQL instead of SQLite
Multi-service integration testing

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch:
```
git checkout -b feature/amazing-feature
```

Commit your changes:

git commit -m 'feat: add amazing feature'

Push to the branch:
```
git push origin feature/amazing-feature
```
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 466 Commits
.agent/workflows		.agent/workflows
.firebase		.firebase
.github		.github
.kiro/steering		.kiro/steering
backend		backend
docker		docker
docs		docs
e2e		e2e
frontend		frontend
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.firebase-config.json		.firebase-config.json
.firebaserc		.firebaserc
.gitignore		.gitignore
DEPLOY_TO_FIREBASE.md		DEPLOY_TO_FIREBASE.md
Dockerfile		Dockerfile
Dockerfile.backend.node		Dockerfile.backend.node
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml
firebase.json		firebase.json
fly.toml		fly.toml

Operation	Before	After	Improvement
List notes	80ms	8ms	10x
Search notes	150ms	30ms	5x
Get tags	40ms	4ms	10x
Read operations (with replicas)	80ms	25ms	3x

Folders and files

Latest commit

History

Repository files navigation

NoteHub 📝

🖼️ Screenshots

Core Features

Login Page with Google OAuth

Notes Dashboard

Note Editor

Tasks Management

Dark Mode

New Features (December 2024)

UI/UX Improvements

Google OAuth Single Sign-On

Simplified 2FA Management

Admin Dashboard

Admin 2FA Recovery

🏗️ Tech Stack

🚀 Recent Improvements

UI/UX Improvements (December 2024)

Architecture Improvements (December 2024)

Performance Enhancements (December 2024)

Security Improvements (December 2024)

New Features (December 2024)

✨ Features

Core Features

Security & Authentication

Performance & Scalability

Developer Experience

🚀 Quick Start

Prerequisites

Local Development

1. Clone the Repository

2. Backend Setup (Node.js/Express API)

3. Frontend Setup (Vite + React)

🐳 Docker Deployment

Development Mode (SQLite, local testing)

Development with MySQL

Production Mode (Cloud Database)

Default Credentials

📦 Project Structure

🧪 Testing

Test Coverage

🌐 Deployment Options

Option 1: GitHub Pages (Frontend Only)

Option 2: Hetzner VPS + Docker (Full Stack)

Option 3: Drone CI for Continuous Integration & Deployment

📚 API Documentation

Authentication

Notes & Tasks

Admin

📖 Documentation

Guides

Architecture & Security

Investigation & Testing

📚 Documentation

Building Documentation HTML

🔧 Troubleshooting

Docker Compose Issues

Cache Registry Errors (403 Forbidden from ghcr.io)

Network Timeout During Build

Container Won't Start - "NOTES_ADMIN_PASSWORD not set"

Local Development Setup

🤝 Contributing

📄 License

🔗 Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Packages