Skip to content

README.en.md

Latest commit

 

History

History
439 lines (324 loc) · 24.3 KB

README.en.md

File metadata and controls

439 lines (324 loc) · 24.3 KB
Raw
Nowen Note

Nowen Note

An open-source, self-hosted knowledge base, collaborative note app, and task workspace

Unified knowledge tree · Rich text / Markdown editors · AI knowledge Q&A · Real-time collaboration · Tasks and mind maps · Cross-platform clients

简体中文 · Official Website / Help Center · nowen.cn (Under Maintenance) · Live Demo · Downloads · Tutorials · MCP Installation · Changelog

GitHub Release Docker Pulls License: GPL v3 Node.js 20+ Docker

Nowen Note is more than an editor. It is designed as user-controlled knowledge infrastructure that can run long-term on a NAS or server and remain accessible from the web, desktop, and mobile clients.

Remote NAS connection and sign-in: Nowen Note supports deployment on UGREEN NAS (UGOS / UGOS Pro) and Feiniu NAS (fnOS). After deployment, connect and sign in from the web, desktop, or Android client using a LAN IP address, an IPv6 address, or a public domain secured with HTTPS.

v1.4.16 is available

v1.4.16 focuses on safer note switching, video attachment authorization, Markdown/code-block editing, and desktop release reliability, improving multi-client editing, LAN media access, and desktop distribution.

  • Safer note switching: stale rich-text save acknowledgements can no longer reclaim the active note after a rapid switch, with regression coverage for late acknowledgements after commit.
  • More reliable first video open: attachment signatures are prepared before opening notes with video so playback does not start before authorization is ready.
  • Android / LAN video authorization fix: LAN attachment authorization now uses the native HTTP path, improving video access when Android connects to NAS or LAN-hosted services.
  • Editor fixes: code-block select-all shortcut handling is refined and historical Markdown block markers are cleaned again to reduce legacy marker interference.
  • Desktop release hardening: Windows SignPath test/production signing, strict Authenticode verification, post-sign update metadata, and macOS dual-architecture artifact integrity checks are strengthened.
  • Sharing compatibility: Edge share-link copying is fixed with clipboard regression coverage.

See the v1.4.16 Release and the full changelog.

Connect AI clients to Nowen Note

Nowen Note includes a supported MCP Server. Claude Code, Cursor, VS Code, and other compatible AI clients can search, read, create, and update notes within the permissions granted by your account and token.

The currently supported distribution is a source build: install Node.js 20+, build packages/nowen-mcp, create a restricted Personal API Token in Nowen Note, and configure the absolute path to packages/nowen-mcp/bin/nowen-mcp.mjs in your client. dist/scoped-entry.js is an internal build entry used by the launcher and should not be configured directly. The guide covers Windows, macOS, Linux/WSL, NAS addresses, Claude Code, Cursor, VS Code, verification, updates, and troubleshooting.

Why Nowen Note
You own the data Self-host with Docker or deploy on NAS platforms such as UGREEN UGOS and Feiniu fnOS. Databases, attachments, and backups stay under your control. Attachments can use S3, Cloudflare R2, or MinIO, while backups can be sent through email or WebDAV.
One tree for every document Mix folders, rich-text notes, and Markdown notes in one hierarchy. Create documents at the root, drag and sort nodes, import files, expand or collapse the tree, inherit permissions, protect folders with passwords, and publish shared content.
Switch editing formats per note Convert notes between rich text and Markdown while preserving major structure, code blocks, and links. Use either format for quick notes, technical documentation, or long-form writing.
Built for individuals and teams Tags, tasks, AI, workspaces, notebook permissions, real-time collaboration, public sharing, and guest comments live in one system.

Core capabilities

Module Current capabilities
Unified knowledge tree Mixed folders, rich-text notes, and Markdown notes; root-level documents, unlimited nesting, drag sorting, drag-to-change hierarchy, a unified create menu, expand/collapse all, Markdown drag-and-drop or file import, filtering, search, note counts, trash, shared tree views, and three-column browsing with child-folder scope.
Folder security and access control Folder passwords, short-lived unlock tokens, directory ACLs, Restricted mode, explicit allow/deny rules, inherited policy evaluation, and protected import/export flows.
Rich text and Markdown Tiptap 3, CodeMirror 6, per-note format conversion, live preview, split view, outline navigation, format painter, slash commands, tables, code blocks, KaTeX, Mermaid, footnotes, Callouts, media embeds, cross-note format-preserving paste, duplicate-title prefix warnings, comments, and version history.
Long documents and editor stability Complexity detection, Worker analysis, viewport rendering, windowed editing, incremental saves, large-document safe modes, outline navigation, and recovery logic for hidden Markdown markers and cursor state.
Performance and delivery Lazy-loaded workspace, editor, task, journal, file, AI, and sharing surfaces; cache validators, Gzip/Brotli precompression, and bundle-budget checks reduce startup and repeated transfer cost.
Image editing Crop images and add text, freehand drawing, arrows, shapes, and mosaic effects. Existing remote images can be migrated into local attachments or object storage.
Knowledge organization and search Colored tags, favorites, pinning, full-text search, current-directory note search, improved in-document find and replace, backlinks, block references, reverse links, and a knowledge graph. Permission-aware search hides restricted resources before result limits are applied.
AI OpenAI-compatible APIs, Qwen, Gemini, DeepSeek, Doubao, and Ollama. Features include continuation, rewriting, translation, title and tag generation, summaries, embeddings, and RAG knowledge Q&A.
Tasks and visualization Hierarchical tasks, lists, Kanban, calendar, Gantt/timeline, dependencies, recurrence, reminders, templates, AI task breakdown, My Day, Inbox, time planning, offline tasks/habits, native Android reminder scheduling with creator-timezone/date-only deadline consistency, and mind maps.
Collaboration, permissions, and sharing Yjs + WebSocket collaboration, workspaces and roles, directory ACLs, Restricted access, explicit allow/deny policies, ownership transfer, centralized share management, passwords and expiration, guest comments, public knowledge spaces, and rich-text/Markdown inline comments.
Sync and edit protection Incremental sync, persistence acknowledgements, draft recovery, and version checks. Offline attachment validation, quarantine, and recovery signaling keep broken cached blobs away from online rendering while serial saves and Yjs state protection guard Markdown/rich-text transitions.
Import, export, and migration Import Markdown, Word/DOCX, web URLs, WeChat articles, SingleFile HTML, SiYuan ZIP archives, Obsidian, Xiaomi Notes, and other supported sources. Export Markdown, PDF, Word, images, or full ZIP packages with permission mapping, conflict preview, reports, controlled rollback, image access preparation, and footnote handling. Team single-note ZIP export resolves the note's real workspace scope.
Attachments and storage Local attachments organized under YYYY/MM; reusable attachment-library insertion, thumbnails, note ownership, reference checks, orphan rescans and cleanup, protected manual uploads, local disk or S3/R2/MinIO storage, plus hardened mobile image/video file identity and multipart uploads.
Accounts and security Multiple-account history, remembered accounts, auto-login, remote server connections, session validation and revocation, 2FA, scoped Personal API Tokens, audit logs, protected attachment access, and concealment of restricted-resource existence.
Backups, automation, and developer APIs Local backups, background full-ZIP jobs, streamed archive/hash processing, native browser downloads, email backup, encrypted WebDAV backup credentials, managed Docker updates and rollback checks, webhooks, plugins, OpenAPI, TypeScript SDK, CLI, MCP Server, and a browser clipper.
Cross-platform access Web, Electron for Windows/macOS/Linux, Android, iOS project, HarmonyOS project, and Docker/NAS deployment. UGREEN UGOS and Feiniu fnOS are supported, and clients can connect through IPv4, IPv6, or a domain name. Android includes in-app gesture image preview and native task notifications.

Recent highlights

v1.4.16 · 2026-08-19

Note switching and editor stability

  • Late rich-text save acknowledgements no longer reactivate the previous note after a rapid switch.
  • Regression coverage now locks down the late-acknowledgement path after a committed switch.
  • Code-block select-all shortcut behavior is refined to reduce conflicts between block-level and document-level selection.
  • Historical Markdown block markers are cleaned again so legacy markers are less likely to affect current editing or rendering.

Video, Android, and LAN access

  • Attachment signatures are prepared before opening notes containing video, reducing first-open playback failures caused by authorization not being ready yet.
  • Android/LAN attachment authorization now uses the native HTTP path for more reliable NAS and LAN media access.
  • Regression tests cover authorization preparation before first open and Android LAN attachment authorization.

Desktop release and distribution

  • Windows release signing is hardened around SignPath test/production signing, configuration validation, and strict Authenticode verification.
  • Post-sign Windows update metadata is rebuilt/refreshed so signed artifacts and update metadata stay consistent.
  • macOS release integrity gates now cover complete and dual-architecture downloadable artifacts.
  • Release notes more clearly document the desktop platform matrix.

Sharing compatibility

  • Edge share-link copying compatibility is fixed with clipboard regression coverage.

See CHANGELOG.md and the v1.4.16 Release for complete details.

Screenshots

Desktop

AI writing assistant AI provider settings
Desktop AI writing AI settings

Mobile

Sidebar Note list Editor
Mobile sidebar Mobile note list Mobile editor

Website and demo

nowen.cn is still under maintenance. For now, use https://cropflre.github.io/ as the official Nowen help and documentation entry.

The demo is reset periodically. Do not store private or important data in it.

Quick deployment

Docker Compose (recommended)

Docker Engine and Docker Compose v2 are required.

git clone https://github.com/cropflre/nowen-note.git
cd nowen-note
docker compose up -d

Open http://<server-ip>:3001.

Default administrator account:

Username: admin
Password: admin123

Change the default password immediately. Public deployments should also use HTTPS, backups, a correct public origin, and restricted CORS settings.

UGREEN NAS / Feiniu NAS remote connection and sign-in

Nowen Note can be deployed on UGREEN NAS (UGOS / UGOS Pro) and Feiniu NAS (fnOS). Use the corresponding .upk or .fpk package from Releases, or deploy with Docker Compose.

After the service starts:

  • LAN access: Open http://<nas-lan-ip>:3001 in a browser.
  • Remote access: Enter the NAS public domain, IPv4 address, or IPv6 service address in the web, desktop, or Android client, then sign in.
  • Public deployment: Configure an HTTPS reverse proxy. Do not expose an unencrypted HTTP service directly to the internet.

See available packages in GitHub Releases.

Check status and logs:

docker compose ps
docker compose logs -f --tail=200 nowen-note

Upgrade from an earlier release

Create a full backup first and confirm that both the database and attachment directory are persisted.

docker compose pull
docker compose up -d

To pin the current stable release:

NOWEN_IMAGE_TAG=v1.4.16 docker compose up -d

v1.4.16 focuses on note-switch stability, first-open video authorization, Android/LAN attachment access, Markdown/code-block editing details, and desktop signing/release integrity. After upgrading, verify rapid note switching, first video playback, Android video access to NAS/LAN services, code-block select-all behavior, and share-link copying. Rolling back an image does not roll back the database.

Managed Docker updates (optional)

Managed updates only support the official docker-compose.yml and are disabled by default. The main application container does not mount the Docker socket; a separate restricted updater container performs the update.

cp .env.example .env
printf '\nNOWEN_UPDATER_TOKEN=%s\n' "$(openssl rand -hex 32)" >> .env
NOWEN_IMAGE_TAG=v1.4.16 docker compose --profile updater up -d

Administrators can then run preflight checks, create a full backup, update, verify health, and roll back the image from Settings → About → Version.

Rolling back an image does not roll back the database. Keep independent production backups.

See Docker online update and recovery.

Run only the main container

docker run -d \
  --name nowen-note \
  --restart unless-stopped \
  -p 3001:3001 \
  -e TZ=Asia/Shanghai \
  -v /opt/nowen-note/data:/app/data \
  cropflre/nowen-note:v1.4.16

Data, backups, and configuration

Persistent directory

The persistent directory inside the container is /app/data, not /data. The default Compose file uses the nowen-note-data Docker volume.

/app/data/
├── nowen-note.db
├── attachments/
├── backups/
├── fonts/
└── .jwt_secret
  • SQLite is the default production database at /app/data/nowen-note.db.
  • Attachments are stored under /app/data/attachments and organized by YYYY/MM.
  • Automatic backups are stored under /app/data/backups by default.
  • Map BACKUP_DIR to an independent physical disk and follow a 3-2-1 backup strategy for production.
  • Third-party image-host uploads are retired. New images use the attachment system; historical remote images can be migrated.
  • PostgreSQL adaptation and migration are still under validation. Production deployment and recovery remain based on SQLite.

Common environment variables

See .env.example for the complete template.

Variable Default Purpose
NOWEN_PORT 3001 Exposed Compose port
TZ Asia/Shanghai Container timezone
PUBLIC_WEB_ORIGIN empty Public or reverse-proxy origin used to generate share links
JWT_SECRET generated and persisted Session signing and fallback encryption; must match across instances
BACKUP_DIR /app/data/backups Automatic backup directory
BACKUP_WEBDAV_ENCRYPTION_KEY falls back to JWT_SECRET Encrypts stored WebDAV credentials; use a dedicated production key
CORS_ORIGINS native client origins Additional comma-separated web origins
MAX_ATTACHMENT_SIZE_MB 100 Maximum attachment size
ATTACHMENT_STORAGE local Set to s3 for S3/R2/MinIO
CALENDAR_EXPORT_ENCRYPTION_KEY empty Encrypts calendar S3 export credentials
NOWEN_UPDATER_TOKEN empty Enables the managed Docker updater

Client and platform status

Platform Distribution / build Status
Web / Docker Docker Hub or source build Recommended deployment; supports amd64, arm64, or multi-architecture images
Windows / macOS / Linux GitHub Releases or npm run electron:build Electron client can connect to a remote service or use the local backend
Android Release APK or Capacitor build under frontend/ Actively maintained; system share import, Markdown file import, immersive editing, mobile knowledge tree, gesture image preview, native task reminders, and remote NAS service sign-in
iOS Capacitor project and GitHub Actions/TestFlight flow Requires Apple signing and a developer account; see iOS release guide
HarmonyOS Open nowen-harmony/ in DevEco Studio ArkTS + ArkWeb MVP; some native capabilities are still being completed
fnOS .fpk in Releases Supports Feiniu NAS installation. The current package primarily targets x86_64; after deployment, connect and sign in using a LAN or public service address.
UGREEN UGOS .upk in Releases or build scripts Supports UGREEN NAS installation, depending on device architecture and app installation support; after deployment, connect and sign in using a LAN or public service address.
Other NAS Docker Compose Synology, QNAP, ZSpace, and similar devices can use the Docker deployment

Available packages vary by release. Check GitHub Releases.

Local development

Requires Node.js 20+, npm, and Git. Electron and native builds also require platform toolchains.

git clone https://github.com/cropflre/nowen-note.git
cd nowen-note
npm install
npm run install:all

Start two terminals:

npm run dev:backend
npm run dev:frontend

Open http://localhost:5173.

Common commands:

npm run build:all
npm run electron:dev
npm run electron:build
(cd backend && npm test)
(cd frontend && npm run test:run)

Android:

cd frontend
npm run cap:build
npx cap open android

Capacitor 8 requires Node.js 22+ for Android release tooling. Regular web and Electron development can continue to use the project's Node.js 20+ baseline.

iOS:

npm run cap:sync:ios
npm run cap:open:ios

Technology stack

Layer Main technologies
Frontend React 18, TypeScript, Vite 5, Tailwind CSS, Tiptap 3, CodeMirror 6, Yjs, IndexedDB
Backend Node.js 20, Hono 4, WebSocket, better-sqlite3, FTS5, sqlite-vec, sharp
Desktop Electron 33, electron-builder, electron-updater
Mobile Capacitor 8 for Android/iOS, ArkTS + ArkWeb for HarmonyOS
Storage and backup SQLite, local attachments, S3/Cloudflare R2/MinIO, email and WebDAV backups; PostgreSQL is under validation
Developer APIs OpenAPI 3.0, TypeScript SDK, CLI, MCP Server, Webhook

Repository layout

nowen-note/
├── frontend/       # React web app and Capacitor clients
├── backend/        # Hono APIs, database, sync, and background tasks
├── electron/       # Electron main process and packaging
├── packages/       # SDK, CLI, MCP, and developer packages
├── nowen-harmony/  # HarmonyOS ArkTS / ArkWeb client
├── docs/           # Deployment, tutorials, and design documents
└── scripts/        # Build, migration, packaging, and release scripts

Documentation

Current boundaries

  • Database: SQLite is the fully supported production default. PostgreSQL adapters, schemas, and partial dual-database tests exist, but production switching is not yet enabled.
  • Format conversion: Rich-text/Markdown conversion preserves major structures where possible. Highly customized HTML, complex extension nodes, or third-party syntax may still require manual review.
  • WebDAV: Used for completed backup files, not real-time sync, live database storage, or attachment hosting. Remote retention must be managed separately.
  • Managed Docker updates: Only support the official managed Compose deployment.
  • Third-party image hosting: Upload integration is retired; only historical configuration cleanup and image migration remain.
  • macOS: Unsigned or unnotarized packages may require removing quarantine attributes; see the desktop tutorial.
  • Mobile: Android has the most complete maintenance coverage. iOS and HarmonyOS distribution, signing, and some native bridges remain platform-dependent.

Releases

The README documents stable capabilities, recent highlights, and deployment. Complete commit-level history remains in the changelog.

Contributing

Issues, feature suggestions, and pull requests are welcome. Before submitting code, run at least:

npm run build:all
(cd backend && npm test)
(cd frontend && npm run test:run)

Feedback channels:

Support the project

If Nowen Note helps you, sponsorship supports continued maintenance and development.

WeChat Alipay
WeChat sponsorship QR code Alipay sponsorship QR code

Read the author's note.

License

Nowen Note is licensed under the GNU General Public License v3.0.