Website: https://deepnotes.app

DeepNotes is an open source, end-to-end encrypted infinite canvas tool with deep page nesting and realtime collaboration.

• Infinite canvases: Free yourself from the big wall of text.
• Deep page nesting: Explore concepts in all their complexity.
• End-to-end encryption: Keep your notes well protected.
• Realtime collaboration: Create groups to collaborate with your team.
• Flexible note system: Organize your notes in whatever way you want.
• Lifelong storage: Never lose your notes ever again.

Note on Developer Setup

This project uses both a README.md and a machines.txt file:

• README.md provides general project documentation, usage instructions, and contribution guidelines.
• machines.txt documents machine-specific setup, environment requirements, recommended tools, and VS Code extensions for contributors.

Please consult both files when setting up your development environment to ensure reliability and consistency across all contributors’ machines.

DeepNotes is built using modern open source technologies:

• Vue.js: Progressive JavaScript framework for building user interfaces and single-page applications.
• Quasar Framework: Cross-platform frontend framework for building SPA, SSR, mobile, and desktop apps with Vue.
• Yjs: CRDT-based library for realtime collaboration and shared editing.
• Tiptap: Rich text editor framework built on top of ProseMirror, highly extensible for custom editors.
• Docker: Containerization platform used to run databases and backend services in isolated environments.
• PostgreSQL: Advanced open source relational database powering DeepNotes data storage.
• KeyDB: High-performance, multi-threaded database compatible with Redis, used for caching and pub/sub.
• Redis: In-memory data structure store, used for caching and message brokering (via KeyDB compatibility).
• Turborepo: Monorepo build system for fast, incremental builds and caching across all packages and apps.
• pnpm: Fast, disk-efficient package manager for JavaScript/TypeScript monorepos.
• Husky: Git hooks manager used to enforce commit message style and automate checks.

DeepNotes uses a monorepo structure managed by Turborepo, which enables fast, incremental builds and caching for large codebases with many interdependent packages and apps.

• apps/: Contains all main applications, such as backend servers, frontend clients, schedulers, and related services. Each app is in its own subfolder (e.g., app-server, client, collab-server).
• packages/: Contains shared libraries and modules, organized by namespace (e.g., @stdlib, @deeplib). These packages provide reusable code, utilities, and configuration used by the apps.

• .turbo/: Local build cache for Turborepo. This folder should not be committed to version control (see .gitignore).
• patches/: Used for package manager patches (e.g., pnpm), not directly by Turborepo but often present in monorepos.

Turborepo coordinates builds, tests, and other tasks across these directories, enabling efficient development and CI/CD for all parts of the project.

For more details, see Turborepo documentation.

This project provides two main scripts for running each application:

• pnpm run dev: Starts the app with the Node.js debugger enabled (--inspect), allowing you to attach a debugger at any time. The app runs normally and does not pause at startup.
• pnpm run debug: Starts the app with the Node.js debugger in break mode (--inspect-brk), pausing execution on the first line. Use this when you want to debug from the very start of the process.

For regular development, use pnpm run dev. Use pnpm run debug only when you need to debug initialization code.

To set up and run DeepNotes locally, follow these steps:

git clone https://github.com/bluekeys/DeepNotes
cd DeepNotes

Copy the example environment file to create your own local config:

cp template.env .env

Edit .env as needed for your local ports, database credentials, etc.

Install all required packages for the monorepo:

pnpm install

This also sets up commit message hooks (via Husky) to enforce commit style.

Start the required database services using Docker:

docker-compose up -d

This launches Postgres and KeyDB containers. You need these running for backend services to work.

Run all backend services in parallel:

pnpm run dev

This starts the app-server, collab-server, realtime-server, etc. These connect to the databases you started above.

Choose one of the following commands depending on your target platform:

• Single Page Application (SPA):

  pnpm run dev:spa

• Server Side Rendered (SSR) app:

  pnpm run dev:ssr

• Electron desktop app:

  pnpm run dev:electron

• Android app (requires Android Studio):

  pnpm run dev:android

• iOS app (requires Xcode):

  pnpm run dev:ios

For SPA or SSR, open http://localhost:60379 in your browser. You can change the host and ports in the .env file.

Windows users: Use WSL or Git Bash to run these commands.

DeepNotes consists of several backend and frontend apps managed in the monorepo:

Startup Order:

1. Start databases:

docker-compose up -d

1. Start backend servers (all at once, using Turborepo):

pnpm run dev

This command uses Turborepo to run all backend apps in parallel. To run a specific app:

To run a specific app, use one of the following commands:

pnpm --filter app-server dev      # Main backend API

pnpm --filter collab-server dev   # Realtime collaborative editing

pnpm --filter realtime-server dev # Websocket server for realtime events

pnpm --filter scheduler dev       # Scheduled background tasks

pnpm --filter manager dev         # Admin/maintenance CLI

1. Start the frontend client (choose your platform):

To start the frontend client, use one of the following commands:

pnpm run spa:dev      # Single Page App

pnpm run ssr:dev      # Server Side Rendered

pnpm run electron:dev # Desktop

pnpm run android:dev  # Android

pnpm run ios:dev      # iOS

For more details on Turborepo configuration and advanced usage, see the Turborepo documentation.

This project uses Husky to manage Git hooks. After running pnpm install, Husky sets up a commit-msg hook that checks your commit messages using commitlint. This helps enforce a consistent commit history and automates changelog generation.

If you commit before running pnpm install, the hooks will not be installed and your commit messages may not be checked.

This project uses commitlint to enforce Conventional Commit messages. This helps keep the project history clean and automates changelog generation.

Commit messages must follow this format:

type(scope): short description

[optional body, each line ≤ 100 characters]

Types:

• feat: a new feature
• fix: a bug fix
• docs: documentation only changes
• style: formatting, missing semi colons, etc; no code change
• refactor: code change that neither fixes a bug nor adds a feature
• perf: performance improvement
• test: adding or correcting tests
• chore: changes to the build process or auxiliary tools

Scope: (optional) the part of the codebase affected, e.g. client, server, docs

• feat: add new canvas drawing tool
• fix(client): resolve login bug
• chore: update dependencies

• Commitlint documentation
• Conventional Commits specification

Commit messages that do not follow these rules will be rejected by the commit hook. If you need to add a longer description, use the commit body and keep each line under 100 characters.

DeepNotes is licensed under the GNU Affero General Public License v3 (AGPL-3.0).

You are free to use, modify, and redistribute this software, provided that you also share your changes under the same license. If you run a modified version of DeepNotes on a publicly accessible server, you must make the source code of your modifications available to users of that server. The AGPL-3.0 ensures that improvements and changes remain open and accessible to the community, especially for network/server software. For full license terms, see the LICENSE file or visit GNU AGPL v3.

If you contribute to DeepNotes, your contributions will also be covered by the AGPL-3.0 license.

This project is a fork of DeepNotesApp/DeepNotes by DeepNotesApp. Special thanks to the original author and contributors for their work.