url: /core-concepts/core-concepts content: | # @lucide:puzzle Core Concepts Notivae is more than just a markdown editor β€” it’s a structured knowledge system designed to support real-time collaboration, offline editing, and granular access control. This page explains the key building blocks of the system so you can better understand how everything fits together. ## Workspaces A **Workspace** is the top-level container for organizing your notes. Each user has exactly one personal workspace, created automatically when they sign up. Workspaces contain: - All of your collections and documents - Snapshot and comment metadata - Your personal structure and content β€” isolated from other users At this stage, workspaces are **private and personal**. Shared workspaces and collaboration across workspaces are planned for future versions. ## Collections **Collections** are folders within a workspace. They help you group related documents (like a project, course, or topic). You can: - Create multiple collections in a workspace - Nest documents inside collections - Use collections to manage shared access ## Documents **Documents** are where your actual content lives. They are markdown-based and support: - Real-time collaborative editing - Offline-first changes (synced automatically) - Rich markdown syntax (code blocks, tables, images) - Inline comments and snapshot versioning Documents are always part of a collection and can optionally be **nested** under other documents to form deep hierarchies. ## Hierarchical Structure Notivae supports nested documents β€” much like files inside folders. This allows you to mirror complex knowledge models: ```text πŸ“ Programming Notes ┣ πŸ“„ Languages ┃ ┣ πŸ“„ Rust ┃ β”— πŸ“„ Python ┣ πŸ“„ Tools ┃ β”— πŸ“„ Docker β”— πŸ“„ Personal Roadmap ``` Each document can act like both a page and a container. Nesting is currently limited to a reasonable depth to maintain performance and usability. ## Comments & Discussions You can leave inline comments on specific parts of a document to start discussions or request feedback. Comments are threaded, can be resolved, and are tied to document versions. ## Snapshots A **Snapshot** is like a commit: it captures the current state of a document at a point in time. You can: * Create a named snapshot (e.g. β€œFinal draft”) * Restore a snapshot if needed * Compare changes between versions (planned) Snapshots are local to each document and are automatically timestamped. ## Access Control Notivae uses a flexible **Attribute-Based Access Control (ABAC)** system. Instead of fixed roles (like β€œadmin” or β€œeditor”), permissions are evaluated based on: * User attributes (e.g. user ID, workspace role) * Resource attributes (e.g. document owner, collection ID) * Context (e.g. shared via public link, authenticated session) More on this in the [Access Control](./access-control.md) section. ## Sync & Offline-First All edits are made locally first and then synced in the background when connectivity is available. This makes Notivae usable even when you're offline or have an unstable connection. Conflict resolution is handled automatically using CRDTs (conflict-free replicated data types), which ensure consistent merging without losing user edits. --- Understanding these core ideas will help you make the most of Notivae β€” whether you're organizing your own notes or collaborating with others across a shared knowledge base. --- url: /hosting/authentication/discord content: | # Authentication via Discord This guide explains how to set up authentication via Discord for your application. ## Prerequisites 1. A valid Discord account. 2. Access to the [Discord Developer Portal](https://discord.com/developers/applications/). 3. Your application's domain or URL where the authentication system will be integrated. ## Environment Variables ::: code-group ```dotenv [.env] DISCORD_CLIENT_ID= DISCORD_CLIENT_SECRET= ``` ::: | Variable | Description | |-------------------------|----------------------------------| | `DISCORD_CLIENT_ID` | Your application's Client ID | | `DISCORD_CLIENT_SECRET` | Your application's Client Secret | :::: details Hidden Variables ::: code-group ```dotenv [.env] DISCORD_DISCOVERY_URI=https://discord.com/.well-known/openid-configuration DISCORD_SCOPES="openid profile email" ``` ::: | Variable | Description | |-------------------------|-------------------------------------------------------| | `DISCORD_DISCOVERY_URI` | Url to discord's OpenID configuration file | | `DISCORD_SCOPES` | Space-separated list of scopes requested during login | :::: ## Setup Instructions ### Step 1: Register an application 1. Head over to the [Discord Developer Portal](https://discord.com/developers/applications/) 2. Click on **New application** 3. Provide a name for your application and agree to the terms of service ![Discord Create Application](assets/discord-create-application.png) ### Step 2: Retrieve OAuth credentials 1. In the sidebar under **Settings** click on **OAuth2** 2. Locate the following credentials: - **Client ID**: Copy this value - **Client Secret**: Click on "Reset secret", confirm, and copy the generated value ![Client ID and Client Secret](assets/discord-client-id-secret.png) ### Step 3: Configure Redirect URLs 1. Scroll to the **Redirect** section under **OAuth2** 2. Click **Add Redirect** and provide your callback URL in the following format: \ `https:///api/auth/discord/callback` \ Replace `` with your application's actual domain name. ![Add Redirects](assets/discord-redirect-url.png) ### Step 4: Apply changes and restart Notivae After updating your environment variables with the Discord credentials and settings, restart Notivae to apply the changes: ```shell docker compose up -d --force-recreate ``` --- url: /hosting/authentication/github content: | --- url: /hosting/authentication/gitlab content: | --- url: /hosting/authentication/google content: | --- url: /hosting/authentication content: | # @lucide:lock-keyhole Authentication Notivae offers a flexible and self-contained authentication system, giving you full control over user data and login flows. It supports both traditional account-based login and external [OAuth/OIDC identity providers](#oauth-oidc-authentication), as well as passwordless login via [Magic-Link](./magic-link.md). ## Supported Authentication Methods Users can authenticate using one or more of the following methods: - [Password-based Authentication](./password.md) β€” traditional username/email + password login - [OAuth/OIDC providers](#oauth-oidc-authentication) β€” login via third-party services (e.g., GitHub, Discord) - [Magic-Link](./magic-link.md) β€” passwordless login via email ## Password-based login If using password-based login, users can log in using either: * Their **email address** * Or a unique **username** (set during sign-up) For email/password login details, refer to [Password-based Authentication](./password.md). ## OAuth / OIDC Authentication Notivae supports logging in via third-party identity providers using the OIDC protocol. This enables users to authenticate without managing passwords directly. Supported providers include: - [Discord](./discord.md) (Planned) - [GitHub](./github.md) (Planned) - [GitLab](./gitlab.md) (Planned) - [Google](./google.md) (Planned) - [Reddit](./reddit.md) (Planned) - [Spotify](./spotify.md) (Planned) - [Twitch](./twitch.md) (Planned) - Any identity provider compliant with [OpenID Connect](./oidc.md) > [!TIP] Workaround > While most providers aren't officially supported yet, many can still be used via generic OIDC configuration. > For example, Discord and GitLab are OIDC compatible and can be manually integrated: > ```dotenv > OIDC_CLIENT_ID= > OIDC_CLIENT_SECRET= > OIDC_DISCOVERY_URL=https://discord.com/.well-known/openid-configuration > OIDC_SCOPES="identity email" > OIDC_DISPLAY_NAME="Discord" > ``` More providers will be documented with exact values and setup instructions once the integration layer stabilizes. ## Magic-Link Authentication Magic-Link enables passwordless login through a secure link sent to the user's email address. This method is ideal for simplifying the login experience and reducing reliance on passwords. - Can be used to **register new accounts** - Can also be **linked to existing accounts** as an additional login method - See the [Magic-Link Authentication Guide](./magic-link.md) for setup and behavior details ## System Management A **system admin account** is created during the initial setup. This account has full access to all instance-level configuration and user management features. ## Session Management Sessions are handled using secure HTTP-only cookies. No client-side tokens are stored in `localStorage` or exposed to JavaScript. All tokens are cryptographically signed and validated on the backend to ensure integrity and security. ## Planned Features * Email verification and password reset flows * Admin UI for user management (per instance) * Optional 2FA support (TOTP-based) * SSO login restrictions (e.g. only allow GitHub org members) --- For more on how access is evaluated across documents and collections, see [Access Control](../../core-concepts/access-control.md). --- url: /hosting/authentication/magic-link content: | # Authentication via Magic-Link This guide explains how to enable **magic-link authentication** as one of the available login methods for your Notivae. With magic-link enabled, users can register or authenticate using a secure link sent to their email addressβ€”no password required. It's a lightweight alternative to password-based login and does not rely on external providers. > [!IMPORTANT] > Magic-link authentication requires a properly working mail configuration. > See the [Email Configuration Guide](../configuration/mail-support.md) for detailed setup instructions. ## Environment Variables ::: code-group ```dotenv [.env] MAGIC_LINK_ENABLED=True ```` ::: | Variable | Description | |----------------------|--------------------------------------------| | `MAGIC_LINK_ENABLED` | Enables the magic-link authentication flow | ## Setup Instructions ### Step 1: Enable Magic-Link Authentication Set the following environment variable in your `.env` file: ::: code-group ```dotenv [.env] MAGIC_LINK_ENABLED=True ``` ::: ### Step 2: Configure Email Settings Magic-link authentication depends on sending emails to users. You **must** have a working email system configured for this feature to work correctly. Follow the setup instructions in the [Email Configuration Guide](../configuration/mail-support.md). If email isn't set up, magic-link authentication will prevent the startup. ### Step 3: Apply changes and restart Notivae After setting the environment variable and ensuring email is configured, restart Notivae to apply the changes: ```shell docker compose up -d --force-recreate ``` --- Once enabled: - Users can register a new account using magic-link as their primary authentication method. - Existing users can link magic-link authentication to their account for future logins. This allows you to offer magic-link either as a standalone login option or as part of a multi-auth strategy alongside email+password or OAuth providers. ## Security Note Magic-links are single-use and expire after they are consumed. This means each login attempt generates a new token that can only be used once. If a user tries to reuse an old link, it will be rejected for security reasons. This behavior helps prevent replay attacks and unauthorized access from previously issued links. --- url: /hosting/authentication/oidc content: | # Authentication via OpenID Connect (OIDC) This guide explains how to set up authentication via any OpenID Connect compatible provider. ## Prerequisites 1. Access to a valid OpenID Connect provider (e.g. [Authentik](https://goauthentik.io/), [Auth0](https://auth0.com/), [Keycloak](https://www.keycloak.org/), [Okta](https://www.okta.com/)) 2. Permissions to register a new application/client on the provider 3. Your application's domain or public URL for handling authentication callbacks ## Environment Variables ::: code-group ```dotenv [.env] OIDC_CLIENT_ID= OIDC_CLIENT_SECRET= OIDC_DISCOVERY_URI=https://auth.example.com/.well-known/openid-configuration OIDC_DISPLAY_NAME="OpenID" ``` ::: | Variable | Description | |----------------------|------------------------------------------------------------------------------------------------------| | `OIDC_CLIENT_ID` | The client/application ID from your OIDC provider | | `OIDC_CLIENT_SECRET` | The client secret associated with the OIDC client ID | | `OIDC_DISCOVERY_URI` | The URI pointing to the OIDC discovery document (usually ends in `.well-known/openid-configuration`) | | `OIDC_DISPLAY_NAME` | The name shown to users during login (e.g., "Login with OpenID") | :::: details Hidden Variables ::: code-group ```dotenv [.env] OIDC_SCOPES="openid profile email" ``` ::: | Variable | Description | |-------------------------|-------------------------------------------------------| | `OIDC_SCOPES` | Space-separated list of scopes requested during login | :::: ## Common Parameter These values are often required by your OIDC provider. | Parameter | Value | |--------------|------------------------------------------------| | Redirect URI | `https:///api/auth/oidc/callback` | --- url: /hosting/authentication/password content: | # Authentication via Email + Password This guide explains how to set up password-based authentication (commonly referred to as "local auth") for your application. Password-based authentication works out of the box and is the simplest authentication mode to set up. It does not rely on any third-party authentication providers like Discord, GitHub, or Redditβ€”everything is handled internally by your application. This makes it an ideal choice for simple setups, single-user environments, or when you want full control over the authentication flow without external dependencies. ## Environment Variables ::: code-group ```dotenv [.env] AUTO_LOCAL_ENABLED=True ``` ::: | Variable | Description | |-----------------------|----------------------------------------------| | `AUTO_LOCAL_ENABLED` | Enables the built-in local auth system | ## Setup Instructions ### Step 1: Enable Local Authentication Set the following environment variable in your deployment or `.env` file: ::: code-group ```dotenv [.env] AUTO_LOCAL_ENABLED=True ``` ::: ### Step 2: Apply changes and restart Notivae After updating your environment variables, restart Notivae to apply the changes: ```shell docker compose up -d --force-recreate ``` --- url: /hosting/authentication/reddit content: | --- url: /hosting/authentication/spotify content: | --- url: /hosting/authentication/twitch content: | --- url: /hosting/configuration content: | --- url: /hosting/configuration/mail-support content: | # @lucide:mail Mail Support (Optional) The mail service is **optional**, but highly recommended if you want to enable features like: - Email verification for user signups - Notification systems (e.g., for comment threads) - Error notifications sent to administrators - Admin approval mails for account creation if `APP_ACCOUNT_CREATION=restricted` - Password reset flows - Other user or admin-triggered messages If not configured, these features will silently degrade or fallback to no-ops. ## Prerequisites 1. Access to a working SMTP server (e.g., Gmail, Mailgun, SendGrid, your own). 2. A valid sender email address and credentials (if required). ## Environment Variables ::: code-group ```dotenv [.env] MAIL_SERVER= MAIL_PORT= MAIL_USE_CREDENTIALS=true MAIL_USERNAME= MAIL_PASSWORD= MAIL_FROM= MAIL_USE_TLS=false MAIL_START_TLS= MAIL_VALIDATE_CERTS=true MAIL_TEMPLATES_DIR= ``` ::: | Variable | Description | |------------------------|--------------------------------------------------------------------------------------------------| | `MAIL_SERVER` | SMTP server hostname or IP address (e.g., `smtp.gmail.com`) | | `MAIL_PORT` | SMTP port. Defaults: `465` if `MAIL_USE_TLS=true`, `587` if `MAIL_START_TLS=true`, else `25` | | `MAIL_USE_CREDENTIALS` | Whether to authenticate using `MAIL_USERNAME` and `MAIL_PASSWORD` | | `MAIL_USERNAME` | Username for SMTP login | | `MAIL_PASSWORD` | Password (or app password) for SMTP login | | `MAIL_FROM` | Email address or `"Name "` to use in the `From` header | | `MAIL_USE_TLS` | If `true`, use TLS immediately on connect. Mutually exclusive with `MAIL_START_TLS` | | `MAIL_START_TLS` | If `true`, upgrade to TLS via STARTTLS after connecting. Overrides server STARTTLS support check | | `MAIL_VALIDATE_CERTS` | Whether to validate server certificates | | `MAIL_TEMPLATES_DIR` | Optional directory path to custom jinja email templates | ::: details TLS vs STARTTLS SMTP supports two common encryption modes: - TLS (SMTPS): Encrypts the connection from the beginning (use port 465) - STARTTLS: Starts unencrypted, then upgrades to TLS via the STARTTLS command (use port 587) Set only one of the following: - MAIL_USE_TLS=true: use SMTPS over port 465 (implicit TLS) - MAIL_START_TLS=true: use SMTP with STARTTLS over port 587 (explicit TLS) - Set both to false: use unencrypted SMTP, typically on port 25 (for internal or development servers) Do not enable both TLS and STARTTLS. ::: ## Example Configurations ### Gmail (App Passwords) ::: code-group ```dotenv [.env] MAIL_SERVER=smtp.gmail.com MAIL_PORT=465 MAIL_USE_CREDENTIALS=true MAIL_USERNAME=notivae@gmail.com MAIL_PASSWORD=your_app_password MAIL_FROM="Notivae " MAIL_USE_TLS=true MAIL_VALIDATE_CERTS=true ``` ::: ### Mailgun ::: code-group ```dotenv [.env] MAIL_SERVER=smtp.mailgun.org MAIL_PORT=587 MAIL_USE_CREDENTIALS=true MAIL_USERNAME=notivae@sandbox123.mailgun.org MAIL_PASSWORD=your_mailgun_password MAIL_FROM="Notivae " MAIL_START_TLS=true MAIL_VALIDATE_CERTS=true ``` ::: ### Localhost (No Auth, No TLS) ::: code-group ```dotenv [.env] MAIL_SERVER=localhost MAIL_PORT=25 MAIL_USE_CREDENTIALS=false MAIL_FROM="Notivae " MAIL_USE_TLS=false MAIL_START_TLS=false MAIL_VALIDATE_CERTS=false ``` ::: ## Optional: Email Templates The mail system comes with built-in HTML templates rendered using **Jinja2**. To override any of them, you can mount a custom template directory and set: ::: code-group ```dotenv [.env] MAIL_TEMPLATES_DIR=/templates/emails ``` ::: Each custom template file must match the filename (and extension) of the default it's replacing. The expected extension is: **`.html.j2`** Modify you `docker-compose.yml` to mount your templates and set the environment variable. ::: code-group ```yaml [docker-compose.yml] services: server: image: ghcr.io/notivae/server ... environment: MAIL_TEMPLATES_DIR: /templates/emails volumes: - ./my-custom-templates:/templates/emails:ro ``` ::: This will override any built-in template that has a matching `.html.j2` file in `./my-custom-templates`. ::: warning ⚠️ Important Notes * Only override templates you fully understand * Do **not** attempt to create custom mail templates unless you are comfortable with: * Jinja2 syntax and escaping * HTML for email clients (tables, inline styles, etc.) * Required template filenames (e.g., `verify_email.html.j2`, `reset_password.html.j2`) * The variables available inside each template (not documented) * Missing or broken templates won't fall back to the default built-in ones ::: ## Additional Notes * `MAIL_FROM` supports both plain email addresses and `"Name "` formats. * If you're using 2FA on your email account (e.g., Gmail), you'll need an [App Password](https://support.google.com/accounts/answer/185833). * Some SMTP servers require you to enable "less secure apps" or explicitly enable SMTP access. --- url: /hosting/configuration/virus-scanning-support content: | # @lucide:shield Virus Scanning (Optional) Notivae supports **optional virus scanning** for uploaded files. This feature is designed to improve security in environments where users can upload arbitrary attachments β€” especially in multi-user or publicly accessible deployments. ## When to Enable Virus Scanning You should **enable virus scanning** if: - Notivae is hosted on a **public-facing server** - You allow **guest access** via shared links - You're running Notivae in an **enterprise or shared multi-user environment** - You want basic protection against **known malware and trojans** You can likely **skip enabling scanning** if: - You're running a **local or private deployment** - **All users are trusted**, such as in internal dev/test setups ## Environment Variables Virus scanning is **disabled by default**. To enable it, you must set the `CLAMAV_SERVER` environment variable: ```dotenv CLAMAV_SERVER= CLAMAV_PORT=3310 ``` Once defined, Notivae will attempt to connect to the ClamAV service. If the connection fails while virus scanning is enabled, **file uploads will be rejected** as a safety precaution. ## How to Set Up Virus Scanning To enable virus scanning, add the ClamAV service to your `docker-compose.yml`: ::: code-group ```yaml [docker-compose.yml] services: clamav: image: clamav/clamav:stable_base restart: unless-stopped volumes: - clamav-db:/var/lib/clamav # persists virus signature database volumes: clamav-db: ``` ::: Then configure your `.env` file with the required environment variables: ::: code-group ```dotenv [.env] CLAMAV_SERVER=clamav CLAMAV_PORT=3310 ``` ::: The official ClamAV image automatically updates its virus definitions **once per day**. > [!WARNING] > During these updates, ClamAV may temporarily use **up to double its normal RAM** due to *concurrent reloading*. This mechanism allows scans to continue while ClamAV reloads its updated virus signatures, but it means memory usage can spike briefly. Ensure your host system has enough headroom to handle these periodic memory peaks, especially on low-memory environments. ### πŸ” Testing Virus Scanning To confirm virus scanning is active and functioning, use the **EICAR test file** β€” a harmless file designed to trigger antivirus systems: - Download or create it using the string provided at: - Upload the file to Notivae If the scanner is correctly integrated, the upload will be rejected with an error like: ``` Virus detected: Eicar-Test-Signature ``` This confirms scanning is working as expected. ## Resource Requirements ClamAV requires a **significant amount of RAM** to function properly. According to official documentation: - Minimum recommended: **3 GB RAM** - Optimal: **4 GB+ RAM**, depending on signature database and traffic You should not enable virus scanning on hosts with limited memory or swap space unless you're confident in available resources. ## How It Works When enabled: - Any uploaded attachments are scanned using the ClamAV service - If a threat is detected, the file is immediately deleted and the upload fails with an error - Clean files proceed as normal --- url: /hosting/security content: | # @lucide:shield Security in Notivae This section documents backend-level features and mechanisms designed to protect your Notivae instance from abuse, resource exhaustion, and unauthorized access. These measures apply to self-hosted deployments and may need adjustment depending on your environment. > [!NOTE] > These security features are built-in and require no external services. They apply automatically when Notivae is deployed. ## @lucide:lock-keyhole Two-Factor Authentication (Planned) Two-Factor Authentication (2FA) support is planned for future versions of Notivae. Once available, it will provide an additional layer of account security by requiring users to enter a time-based or device-generated code when logging in β€” especially useful for admin-level accounts or shared instances. ## @lucide:lock HTTPS & Reverse Proxy Configuration Notivae is designed to run behind a reverse proxy like Nginx or Caddy, which should be configured to handle HTTPS and SSL termination. Using HTTPS is essential to protect session tokens and sensitive data from being intercepted during transmission β€” especially important since authentication relies on httponly cookies. > [!TIP] > For guidance on setting up a secure reverse proxy, see the [Reverse Proxy Setup Guide](../start/installation/reverse-proxy.md). ## @lucide:octagon-minus Rate Limiting To protect the server from misuse and ensure a stable experience for all users, Notivae applies automatic rate limits to certain API endpoints. This means that if too many requests are made in a short time β€” whether by a user, a bot, or a misconfigured client β€” the server may temporarily reject further requests. In these cases, the response will clearly indicate that the limit was reached and suggest how long to wait before trying again. Rate limits apply more strictly to unauthenticated users, while authenticated sessions are granted more flexibility. ## @lucide:ban Temporary Bans If a client repeatedly hits the rate limit in a short time, Notivae may temporarily block further access from that user or IP address. This helps prevent abuse and reduces server load from bad actors or faulty automation. Temporary bans are applied automatically and expire after a short period (e.g. one hour). Most users will never encounter this unless they are spamming requests or using unsupported tools. ## @lucide:shield-half CSRF Protection Notivae’s session authentication uses a `session_token` cookie with the following security flags: - `HttpOnly`: Prevents JavaScript access - `Secure`: Only sent over HTTPS - `SameSite=Lax`: Allows form submissions but blocks most third-party cross-site requests This setup provides basic protection against Cross-Site Request Forgery (CSRF) in most scenarios. While it's not a full CSRF defense mechanism, it's considered safe for APIs that do not accept cookie-authenticated cross-origin POSTs from third-party sites. In future versions, Notivae may add stricter CSRF validation for endpoints that modify server-side state. --- url: /hosting/self-hosting content: | --- url: / content: | --- # https://vitepress.dev/reference/default-theme-home-page layout: home hero: name: Notivae text: Self-hosted structured markdown workspace tagline: Take notes offline. Collaborate in real time. Own your knowledge. image: src: /favicon.svg alt: placeholder actions: - theme: brand text: Get Started link: /start/introduction - theme: alt text: FAQ link: /other/faq - theme: alt text: GitHub link: https://github.com/notivae/notivae useCases: - icon: πŸŽ“ title: Students details: Organize your semester, write clean notes, and work offline from anywhere. - icon: πŸ”¬ title: Academics details: Manage long-form research, keep snapshots of drafts, and collaborate with peers. - icon: πŸ§‘β€πŸ’» title: Developers details: Build a project wiki, document tools, or write changelogs with markdown and versioning. - icon: πŸ›©οΈ title: Personal Knowledge details: Capture your ideas, journal, or study notes in your own local-first knowledge system. - icon: 🏒 title: Small Teams details: Share documentation, leave inline feedback, and collaborate in real time on team knowledge and handbooks. - icon: 🧠 title: Knowledge Management details: Build a long-term, structured knowledge base for personal growth, team alignment, or learning over time. keyFeatures: - icon: title: Markdown Editor details: Focus on writing with a clean, keyboard-friendly markdown interface. - icon: title: Live Collaboration details: Work together on the same document without merge conflicts. - icon: title: Structured Collections details: Group documents into collections β€” great for courses, projects, or multi-part topics. - icon: title: Nested Documents details: Organize your workspace with nested folders and subpages. - icon: title: Offline Support details: Edit notes anywhere. Sync resumes automatically when you're reconnected. - icon: title: Version Snapshots details: Mark document milestones and restore older versions when needed. - icon: title: Inline Comments details: Discuss ideas right where they matter β€” inside the document. - icon: title: Granular Sharing details: Public or private. Shared links or per-user collaboration β€” you're in control. --- > [!WARNING] Notivae is in early development. Expect breaking changes and limited support. ## @lucide:sparkles Why We Built It > [!IMPORTANT] We needed a tool that just worked β€” offline, structured, and sharable. Most tools are either locked into the cloud, built for solo work, or fall apart when your connection does. We wanted something different: - **Writing in Markdown** β€” quick, portable, and clean - **Structured like your brain** β€” nested folders, collections, and pages - **Collaborative** β€” write together, leave comments, work as a group - **Works without internet** β€” great for travel or unreliable networks - **Self-hosted** β€” no vendor lock-in or data leakage > [!INFO] Here’s how it compares to other tools: > πŸ‘‰ [Full feature comparison](./start/introduction.md#πŸ”-feature-comparison) > > | Feature | Notivae | Notion | Obsidian | > |-------------------------|:-------:|:------:|:--------:| > | Offline support | βœ… | ⚠️ | βœ… | > | Real-time collaboration | βœ… | βœ… | ❌ | > | Fully self-hosted | βœ… | ❌ | βœ… | > | Structured hierarchy | βœ… | βœ… | ⚠️ | > | Markdown-native editing | βœ… | ⚠️ | βœ… | ## @lucide:brain Use Cases > [!INFO] Built for students β€” and beyond. Whether you're a student managing semesters, a researcher documenting findings, or a developer organizing project knowledge β€” Notivae adapts to how you think, write, and collaborate. Use it alone, or with your team, no matter where you are.
## @lucide:cog Key Features Notivae brings together clean design, robust features, and a structured writing experience β€” without the usual tradeoffs. It’s designed to grow with you, whether you’re jotting down quick notes or building a long-term knowledge base. ## @lucide:anvil Under the Hood Built for control, extensibility, and privacy from day one: - 100% self-hosted β€” no external accounts or APIs required - Docker-based deployment makes hosting easy - Runs entirely on your infrastructure - Optional AI features: OCR, summarization, transcription (local-only) ## @lucide:handshake Community & Status > [!NOTE] Notivae is early-stage β€” but rapidly evolving. We welcome: - πŸ› οΈ Bug reports & feature requests - πŸ“– Docs and translations - πŸ’‘ Ideas, feedback, and help testing Join us:
[Contribute on GitHub](https://github.com/notivae/notivae) Β· [Open a discussion](https://github.com/notivae/notivae/discussions)
## @lucide:rocket Ready to take notes on your terms?
[Get Started](./start/introduction.md) Β· [View Docs](./start/introduction.md) Β· [GitHub](https://github.com/notivae/notivae)
--- url: /intelligence/features content: | --- url: /intelligence/installation content: | --- url: /intelligence/introduction content: | # Intelligence (AI/ML Module) > [!IMPORTANT] ⚠️ Work in Progress > The Intelligence module is not yet available. > The features described below are *conceptual* and may not be implemented yet or at all. > This page outlines planned functionality and areas under consideration. --- The **Intelligence module** is an optional service that enhances Notivae with AI/ML-powered capabilities β€” all running locally on the user’s system. When enabled, this module allows users to automate, analyze, and organize their content more effectively using machine learning techniques. This service is completely self-contained and runs in a separate container. Users who prefer a lightweight or privacy-focused setup can simply choose not to install or enable it. ## @lucide:sparkles Intelligent Content Features These features are designed to assist with content creation, cleanup, and refinement: - **Reviewer** Analyzes a document and recommends: - Grammar and spelling corrections - Stylistic rewrites - Clarity improvements - **OCR (Optical Character Recognition)** Converts images (e.g., scans, handwritten notes, photos of slides) into searchable, editable text. Useful for: - Better document indexing and search - Extracting text from screenshots or PDFs - **Auto-title Generator** Suggests meaningful titles for untitled documents. May also recommend improved or standardized titles for renamed files. - **Automatic Tag Suggestion** Analyzes the content of a document and suggests relevant tags to improve organization and discoverability. Suggestions are based on: - Keyword extraction - Semantic understanding of the text - Cross-referencing existing tags across the workspace This helps reduce manual tagging effort and promotes consistency in tag usage. - **Version Diff Summarization** Generates a natural language summary describing what has changed between different versions of a document. - **Smart Paste** When pasting content into a document, this feature can: - Automatically clean up formatting - Summarize large blocks of text - Extract key points or quotes ## @lucide:search Search & Organization Enhancements that help structure and navigate large volumes of notes and documents: - **Semantic Search** Goes beyond keyword search by understanding the *meaning* of queries and document content. Enables searching for concepts, not just exact terms. - **Topic Clustering** Automatically groups related documents based on shared themes or subjects. Ideal for organizing notes across broad topics or courses. ## @lucide:mic Audio & Speech Advanced tools for working with voice data and recordings: - **Audio-to-Text Transcription** Converts spoken content (e.g. meeting recordings, lectures) into text for documentation or further processing. - **Meeting Summarization & Tagging** Automatically identifies key moments and tags from recorded discussions. Can generate summaries or action items. ## @lucide:puzzle Architecture Note All features are intended to: - Run locally (no cloud dependency) - Be modular and optional - Be securely accessed via the main Notivae backend - Respect user resources β€” features are only triggered intentionally or in controlled background tasks --- Stay tuned for implementation progress and configuration guides once development starts on the Intelligence module. --- url: /other/architecture-overview content: | # @lucide:puzzle Architecture Overview Notivae is designed as a modular, scalable, and self-hosted collaborative markdown editor. Understanding its architecture helps you grasp how components interact and how to deploy, extend, or contribute to the project. ## High-Level Components - **Frontend (Vue + Vite)** A modern single-page application providing the user interface for editing, navigation, commenting, and collaboration. - **Backend API (Python FastAPI)** Serves REST and WebSocket endpoints to handle authentication, document management, versioning, access control, and CRDT-based synchronization. - **Database (PostgreSQL)** Stores users, workspaces, collections, documents, snapshots, comments, permissions, etc. ## Component Interaction ``` +----------+ +--------------+ +----------------+ | Frontend | <--REST--> | Backend | <--DB--> | Database | | (Vue) | <---WS---> | (FastAPI) | | (PostgreSQL) | +----------+ +--------------+ +----------------+ ``` ## Deployment Model - All components run inside Docker containers orchestrated via `docker-compose`. - Ports are exposed for the frontend and backend. - Persistent storage is configured for database files and user data. ## Offline-First and Sync - The frontend keeps a local replica of documents. - Changes are applied locally and synced in the background via CRDTs. - This approach guarantees no lost edits, even when offline or on unstable connections. ## Security and Access Control - Authentication is handled by the backend with support for email/password and OAuth/OIDC. - Access to documents and collections is controlled using ABAC policies evaluated on the backend. - All communications are secured via HTTPS in production (reverse proxy recommended). --- This modular design enables Notivae to be extended with features like API integrations, and enhanced collaboration tools without breaking core principles of privacy, ownership, and offline resilience. --- url: /other/contributing content: | # @lucide:handshake How to Contribute Notivae is an open-source project β€” built by and for people who care about structured, private, and collaborative knowledge management. Contributions are very welcome, whether you're a developer, designer, tester, writer, or just someone with feedback. ## @lucide:brain Ways to Contribute - **Code** β€” Implement features, fix bugs, refactor or improve developer experience - **Docs** β€” Improve this documentation or write tutorials and guides - **Testing** β€” Try out the app, report bugs, and suggest improvements - **Design** β€” Help improve UX, visual design, or accessibility - **Ideas** β€” Open issues or discussions to shape the roadmap - **DevOps** β€” Help refine the Docker setup, CI/CD, deployment flow ## @lucide:scroll-text License & Contributor Expectations Notivae is GPL3.0-licensed. By contributing, you agree your work can be included under that license. All contributors are expected to follow basic standards of respectful, constructive collaboration. --- Thanks for helping shape Notivae. Let’s make knowledge open, structured, and self-owned. --- url: /other/design-decisions content: | # @lucide:target Design Decisions Notivae’s architecture and feature set are driven by clear design principles focused on user control, privacy, collaboration, and extensibility. This page outlines the key decisions behind the project’s foundation. ## 1. Self-Hosted First - Users retain full control over their data by running Notivae on their own infrastructure. - No reliance on third-party services or proprietary cloud platforms. - Ensures privacy, security, and compliance with personal or organizational policies. ## 2. Markdown-Native - Markdown is the universal format for writing and note-taking. - Enables compatibility with many tools and simple import/export workflows. - Avoids vendor lock-in by storing plain-text documents with semantic structure. ## 3. Real-Time Collaboration with CRDTs - Uses Conflict-Free Replicated Data Types (CRDTs) to enable seamless multi-user editing. - Guarantees zero merge conflicts and automatic offline sync. - Yjs is chosen as the CRDT library for its performance and community support. ## 4. Offline-First Approach - Users can read and edit documents without an internet connection. - Local changes sync automatically once connectivity is restored. - Provides resilience against unstable networks and improves usability on mobile devices. ## 5. Hierarchical Structure - Documents can be nested within collections and other documents. - Mirrors natural knowledge organization: folders, subfolders, and pages. - Enables granular access control and easier navigation in large knowledge bases. ## 6. Attribute-Based Access Control (ABAC) - Moves beyond rigid role-based permissions. - Access is evaluated dynamically based on user attributes, document metadata, and context. - Offers fine-grained control suitable for complex sharing and collaboration scenarios. ## 7. Simple Deployment - Uses Docker and Docker Compose for straightforward setup. - Prebuilt images simplify installation for both developers and end-users. - Designed for easy upgrades and maintenance. --- These decisions collectively shape Notivae into a privacy-respecting, user-centric, and robust platform for collaborative knowledge management. --- url: /other/faq content: | # @lucide:message-circle-question-mark FAQ Frequently Asked Questions about Notivae β€” answered concisely. ## Is Notivae finished? No β€” Notivae is **very much a work in progress**. Core architecture is in place, but many features are still incomplete or entirely missing. Expect frequent changes, breaking migrations, and rough edges. It's not yet suitable for production use or critical data. ## Can I use Notivae without an internet connection? Yes. Notivae is designed to be **offline-first**. You can open the app, edit documents, and your changes will sync once you're reconnected. ## Does Notivae require any external services? No. Notivae is built to run fully isolated, without relying on any third-party services. Everything β€” backend, frontend, and database β€” runs locally by default. However, external dependencies can be added **optionally** to enhance functionality. For example: - External OAuth/OIDC providers for authentication (GitHub, GitLab, etc.) - Externally managed PostgreSQL for improved performance, scalability, or backup automation ## Is there support for real-time collaboration? Yes β€” Notivae uses **CRDT-based sync** to support real-time editing. ## What format is content stored in? The primary focus is on **Markdown-based documents**, but Notivae also supports other plain text formats such as code files (e.g. `.js`, `.py`, `.json`). In the future, support for alternative structured formats like **Typst**, **AsciiDoc**, and **WikiText** is considered β€” along with proper editors and renderers for each format. This will allow more specialized workflows while keeping content structured and exportable. ## Can I import my existing notes from Notion / Obsidian / Logseq? Not yet. But import/export support for common formats is on the roadmap. For now, you can manually paste or migrate content using Markdown. ## Does Notivae support custom domains or HTTPS? Yes β€” simply reverse proxy it behind Nginx, Caddy, or Traefik and terminate HTTPS there. You'll configure this outside the Docker container. ## Can I restrict who signs up? Eventually, yes. Planned features include: - Invite-only registration - Restrict signups to a specific domain or OAuth provider (e.g. GitHub org) ## Is my Notivae instance protected against spam or abuse? Yes. Notivae includes built-in safeguards to help protect your instance from excessive or abusive usage. This includes measures like request limits and temporary blocks for suspicious behavior. If you're self-hosting Notivae and want to learn more, see the [Security documentation](../hosting/security.md). ## Will there be mobile apps? Probably not. The current web app is being designed as a **Progressive Web App (PWA)** with offline support and responsive layout, which works well on mobile devices. ## How do I contribute? Check out the [Contributing](./contributing.md) page and the [GitHub repo](https://github.com/notivae/notivae). Contributions of all kinds are welcome β€” code, docs, testing, ideas. --- Missing a question? Open an issue or discussion on [GitHub](https://github.com/notivae/notivae/issues). --- url: /other/roadmap content: | # @lucide:square-chart-gantt Roadmap Notivae is in **early-stage development**. No features are fully implemented yet β€” everything listed below is planned but still in progress or under design. This roadmap gives a transparent view of where the project is heading. --- > [!WARNING] 🚧 Everything is subject to change. > You can track progress or contribute on [GitHub](https://github.com/notivae/notivae). ## @lucide:brick-wall Planned Foundation - [X] Codebase setup - [X] Online Documentation - [X] REST and WebSocket APIs - [X] User System - [X] Email/password authentication - [ ] third-party authentication providers - [X] OIDC-based third-party login - [ ] Personal workspace per user - [ ] Markdown-based document editor - [ ] Collections for organizing documents - [ ] Document nesting and hierarchy - [ ] Offline-first editing - [ ] Sync-on-connect model using CRDTs - [ ] Snapshot-based versioning - [ ] Inline comments and discussions - [ ] Self-hostable via Docker Compose ## @lucide:pocket-knife Upcoming Development Focus - [ ] Frontend: editor UI, navigation, commenting - [ ] Backend: data model, auth, syncing, access control - [ ] Database schema - [ ] First working end-to-end Docker setup - [ ] Persistent volume storage and backup support - [ ] CI for ghcr.io image builds ## @lucide:test-tube-diagonal Future Features - [ ] Public sharing via links - [ ] Invite-based sharing with per-user access control - [ ] Full-text search across documents - [ ] Export to PDF / Markdown - [ ] Admin interface - [ ] Comment threading & resolution - [ ] Snapshot diffs - [ ] Configurable themes - [ ] Mobile-first PWA enhancements ## @lucide:compass Long-Term Vision - [ ] Shared workspaces (teams, organizations) - [ ] Plugin system for extensibility - [ ] Self-hosted AI integration (summarization, search) - [ ] Custom metadata fields for documents - [ ] Workspace analytics and activity feed --- > [!WARNING] 🚧 Everything is subject to change. > You can track progress or contribute on [GitHub](https://github.com/notivae/notivae). --- url: /start/installation content: | > [!IMPORTANT] > Notivae is in early-stage development. No features are fully implemented yet. # @lucide:tool-case Installation Notivae can run on your own computer or server using **Docker**, a tool that bundles everything it needs. No need to install each part separately. We’ll use a tool called `docker-compose` to launch all components – the app, its backend, and the database – all with one command. ## @lucide:wrench Prerequisites Make sure these are ready on your system: - [X] **Docker** [Install Docker](https://docs.docker.com/get-docker/) - [X] **Docker Compose** [Install Docker Compose](https://docs.docker.com/compose/install/) - [X] A machine that meets the [minimum requirements](../requirements.md) - [X] Basic knowledge of how to use a terminal (e.g., navigating folders, running commands) ## @lucide:folder Setup Files To run Notivae, you'll need two files: 1. **`docker-compose.yml`** – defines the services (frontend, backend, database), ports, and volumes. 2. **`.env`** – contains configuration settings like database passwords, ports, and secrets. Copy the following files to your local machine or server. We recommend placing them under `/srv/notivae-stack`. - The `docker-compose.yml` file works as-is but can be customized to your environment or use case. - The `.env` file **must** be reviewed and adjusted. Each variable has a comment or description in the sample. For a deeper explanation, see [Configuration](../../hosting/configuration/index.md). Your folder structure should look like this: ```text πŸ“ /srv/notivae-stack ┣ πŸ“„ docker-compose.yml β”— πŸ“„ .env ``` > [!WARNING] > These configuration files are currently in draft status and are not fully functional. Use them as a reference or base for manual setup until stable versions are released. ::: code-group <<< @/assets/docker-compose.yml <<< @/assets/.env.sample{dotenv}[.env] ::: ## @lucide:square-play Start the Stack From within the `/srv/notivae-stack` directory, run: ```bash docker compose up -d ``` This command will: - Start the **database** and **cache** (for storage) - Start the **backend** (the engine) - Start the **frontend** (the user interface) Docker will automatically download any required images on the first run. This may take a while, depending on your internet connection. ## @lucide:square-check Verify After a few seconds, run this command in your terminal: ```bash curl http://localhost:8765/healtz ``` You should see a simple response like: ```json {"status":"ok"} ``` If you see this message, it means the backend is running successfully and responding to requests. However, you **won’t be able to access the web interface yet.** The frontend and backend are exposed on different ports and cannot communicate directly in this setup. > [!INFO] > πŸ› οΈ To continue, you need to configure a [reverse proxy](./reverse-proxy.md) or another solution that connects the frontend to the backend under a unified address. > This is required before opening the web UI in your browser. ## @lucide:globe Connect Frontend and Backend Notivae’s frontend expects to reach the backend at `/api` on the **same domain and port** β€” for example: ```text https://notivae.example.com β†’ frontend https://notivae.example.com/api β†’ backend ``` However, in the current setup, the backend and frontend are exposed on **different ports**: ```text http://localhost:8766 β†’ Frontend http://localhost:8765 β†’ Backend ``` This means they **can’t communicate properly** until you combine them under a unified domain or port. The solution is a reverse proxy. A **reverse proxy** acts as a gateway that: - Routes browser requests to the correct service (frontend or backend) - Handles HTTPS (SSL) if needed - Rewrites paths like `/api/*` to target the backend This setup is required even if you're running Notivae locally. Popular reverse proxy options: - [Caddy](https://caddyserver.com/) β€” simple, automatic HTTPS - [Traefik](https://traefik.io/traefik) β€” Docker-native, dynamic - [Nginx](https://nginx.org/) β€” widely supported, configurable > [!INFO] Need help setting it up? > See the [Reverse Proxy Guide](./reverse-proxy.md) for setup examples and config snippets. > [!TIP] > Hosting Notivae behind a home network? You may need a **tunnel** like [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) or [Ngrok](https://ngrok.com/) to make it accessible from the internet. > This is also covered in the [Reverse Proxy Guide](./reverse-proxy.md). ## @lucide:rocket Finalizing your instance Notivae's web-ui has a built-in wizard to help you configure the final parts or your hosted instance. To start the setup wizard open the following page in your browser. ```txt https:///#/init e.g. https://notivae.example.com/#/init ``` ## @lucide:repeat-2 Updating To update Notivae to the latest version: ```shell docker-compose pull docker-compose up -d ``` This will: - Pull the latest image versions - Restart the containers using the updated versions > [!WARNING] > This command works only if you are omitting or using floating tags like `:latest` or `:dev` in your `docker-compose.yml`. If you pin versions explicitly in `docker-compose.yml`, you need to update the tags manually before running pull. ## @lucide:octagon Stopping the Stack To shut everything down: ```shell docker-compose down ``` Your data (e.g., database files) will be preserved unless you remove the Docker volumes explicitly. --- url: /start/installation/reverse-proxy content: | # @lucide:shield Reverse Proxy Setup for Notivae To make Notivae work correctly, you need to set up a **reverse proxy**. This is required even for local installations β€” not just for exposing it to the internet. ## @lucide:circle-question-mark Why You Need a Reverse Proxy By default, Notivae’s frontend and backend are served on **different ports**: - Frontend: `http://localhost:8766` - Backend: `http://localhost:8765` But the frontend is hardcoded to call the backend via `/api` on the **same host and port**. Without a reverse proxy, this fails, and the web UI won’t work. A reverse proxy solves this by: - Making both frontend and backend accessible from **one unified domain** - Forwarding frontend requests to the frontend container - Forwarding `/api` requests to the backend container - Optionally handling HTTPS for secure public access ## @lucide:cog What You’ll Need - A reverse proxy installed (see options below) - A domain name (for internet-facing setups) - Basic familiarity with editing config files or using Docker ## @lucide:wrench Recommended Options | Tool | Why Use It | Docs | |-------------|--------------------------------------|---------------------------------------------| | **Caddy** | Easiest to set up, automatic HTTPS | [caddyserver.com](https://caddyserver.com/) | | **Traefik** | Designed for Docker, dynamic routing | [traefik.io](https://traefik.io/) | | **Nginx** | Most flexible, widely supported | [nginx.org](https://nginx.org/) | ## @lucide:file-code Example Configs > [!IMPORTANT] > These configuration examples assume your reverse proxy is running inside Docker (alongside Notivae, via `docker-compose`). > If you're using a system-wide reverse proxy (e.g., Traefik or Nginx on the host system), replace: > > - `backend:80` with `http://localhost:8765` > - `frontend:80` with `http://localhost:8766` ### @lucide:lock Caddy Example If you're using Docker Compose, create a `Caddyfile` like this: ::: code-group ```caddyfile [Caddyfile] notivae.localhost handle_path /api/* { reverse_proxy backend:80 } handle { reverse_proxy frontend:80 } ``` ::: And add a Caddy service to your `docker-compose.yml`: ::: code-group ```yaml [docker-compose.yml] services: caddy: image: caddy:alpine ports: - "80:80" - "443:443" volumes: - ./Caddyfile:/etc/caddy/Caddyfile depends_on: - frontend - backend ``` ::: > πŸ’‘ You’ll need to update `notivae.localhost` to your actual domain or host if not using `localhost`. ### @lucide:cog Nginx Example If you're using Docker Compose, create a `nginx.conf` like this: ::: code-group ```nginx [nginx.conf] server { listen 80; server_name notivae.localhost; location /api/ { proxy_pass http://backend:80/; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { proxy_pass http://frontend:80/; } } ``` ::: And add an nginx service to your `docker-compose.yml`: ::: code-group ```yaml [docker-compose.yml] services: nginx: image: nginx:alpine volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf ports: - "80:80" depends_on: - frontend - backend ``` ::: > [!INFO] > You’ll need to update `notivae.localhost` to your actual domain or host if not using `localhost`. ## @lucide:globe Exposing to the Internet If you're self-hosting (e.g., on a home network or behind NAT), you'll need to expose your reverse proxy to the internet. There are two options: ### 1. Port Forwarding (Risky) Open ports `80` and `443` on your router to your server. **Only recommended** if you know how to secure your server (firewalls, fail2ban, etc.). ### 2. Secure Tunnel (Recommended) Use a tunnel service to make your reverse proxy public without opening any ports: - **[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)** - **[Ngrok](https://ngrok.com/)** These services let you tunnel traffic from a public domain to your local machine securely. ## @lucide:brain Alternative: Tunnel-Only Setup (No Reverse Proxy) If you’re using a tunnel provider like **Cloudflare Tunnel**, you can skip setting up a separate reverse proxy altogether. Configure your tunnel to forward: - `https://notivae.example.com/api/` β†’ `http://localhost:8765` - `https://notivae.example.com/` β†’ `http://localhost:8766` This works because most tunnel providers allow advanced path-based routing. Notivae only requires that `/api/*` hits the backend on the same domain. > [!INFO] This is ideal for simple home or private setups with minimal config. ## @lucide:check-square Final Checklist - [x] You’ve confirmed `backend` and `frontend` are both running - [x] You’ve either set up a reverse proxy *or* configured a tunnel-only setup - [x] The `/api` path points to the backend, and `/` points to the frontend - [x] If you're going public, you’ve configured HTTPS and/or tunneling Once all of this is in place, open your browser at: ``` https:// e.g. https://notivae.example.com ``` and the login-page should appear. > [!TIP] > Don't forget to run the setup wizard at > ``` > https:///#/init > ``` --- > [!INFO]️ Having issues? Start by checking the container logs: > > ```bash > docker compose logs # inspect all logs > docker compose logs frontend # inspect logs for a specific service > ``` Still stuck? Look through our [troubleshooting guide](./troubleshooting.md) or otherwise open a [GitHub issue](https://github.com/notivae/notivae/issues). --- url: /start/installation/troubleshooting content: | # @lucide:hammer Troubleshooting This page helps you resolve common issues encountered while setting up or running Notivae using Docker. If you're stuck on something not listed here, feel free to open an issue or check the [Contributing](../../other/contributing.md) guide. ## @lucide:puzzle Docker Setup Issues ### Docker/Docker Compose is not installed or not found **Symptoms** - Running `docker` or `docker compose` returns `command not found`. **Solution** - Ensure Docker and Docker Compose are installed correctly: - [Install Docker](https://docs.docker.com/get-docker/) - [Install Docker Compose](https://docs.docker.com/compose/install/) - Restart your shell or terminal after installation. ## @lucide:container Container Won’t Start ### Ports are already in use **Symptoms** - Error like: ``` Bind for 0.0.0.0:8766 failed: port is already allocated ``` **Solution** - Another service is using the same port. - Run: ```bash sudo lsof -i :8766 ``` and kill the conflicting process or modify the port in `docker-compose.yml`. --- ### Environment variables are not set or invalid **Symptoms** - Services crash on startup with unclear errors. - Logs may reference missing configuration or fail to connect to other services. **Solution** - Ensure you have a `.env` file in the root directory (`/srv/notivae-stack`) and that it's configured correctly. - Check for: - Missing values - Quotes around special characters - Line endings (use Unix line endings) ## @lucide:database Database Errors ### Database container exits immediately **Symptoms** - Running `docker compose up` shows the database container starting and then exiting or restarting in a loop. **Possible Causes** - Invalid environment variables - Volume permission issues - Existing corrupt volume **Solutions** - Double-check database config in `.env` - Try resetting the volume (data will be lost): ```bash docker volume rm notivae_pgdata ``` ## @lucide:app-window Frontend is Blank or Unresponsive **Symptoms** - You open `http://localhost:8766` and see a blank screen or a browser error. **Solutions** - Check if all containers are running: ```bash docker compose ps ``` - View frontend logs: ```bash docker compose logs web ``` - Make sure the backend is reachable from the frontend container (`localhost` inside a container β‰  your host machine) ## @lucide:brush-cleaning Cleanup Tips ### Removing all containers, volumes, and networks If you want to start over clean: ```bash docker-compose down -v ``` This will remove all associated volumes (e.g., database data). Be careful β€” this is irreversible. ## @lucide:bug Still Having Issues? Open an issue on the repository with logs, your `.env` config (redact sensitive info), and a description of what’s not working. We’re early in development and appreciate any feedback or bug reports! --- url: /start/introduction content: | # @lucide:rocket Introduction to Notivae ## Why Notivae? Notivae was created to solve the limitations of existing knowledge and note-taking platforms. Tools like [Notion](https://www.notion.com/), [Outline](https://www.getoutline.com/), [Obsidian](https://obsidian.md/), [Logseq](https://logseq.com/), and [Joplin](https://joplinapp.org/) each offer parts of the solutionβ€”but not the whole. Some are closed-source, cloud-dependent, or hard to self-host. Others lack real-time collaboration, structured access control, or robust offline support. Notivae brings together the best of these systems while staying **fully self-hosted**, **markdown-native**, and **privacy-first**. ### @lucide:table Feature Comparison | Feature | Notivae | Notion | Outline | Obsidian | Logseq | Joplin | |----------------------------------------------------------|:-------:|:------:|:-------:|:--------:|:------:|:------:| | For Teams and Solo use | βœ… | βœ… | βœ… | ❌ | ⚠️ | ❌ | | Fully Self-Hosted | βœ… | ❌ | ⚠️ | βœ… | βœ… | βœ… | | Real-Time-Sync | βœ… | βœ… | βœ… | ❌ | ⚠️ | ❌ | | Real-time Collaboration | βœ… | βœ… | βœ… | ❌ | ⚠️ | ⚠️ | | Remote Access
(Internet-Ready) | βœ… | βœ… | βœ… | ⚠️ | ⚠️ | ⚠️ | | Web-First UI
(no install needed) | βœ… | βœ… | βœ… | ❌ | ❌ | ⚠️ | | Offline-First Support | βœ… | ⚠️ | ❌ | βœ… | βœ… | βœ… | | Hierarchical Documents | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | | Markdown-Native Editing | βœ… | ⚠️ | βœ… | βœ… | βœ… | βœ… | | Other Text-Based Documents
(code, note dumping, ..) | βœ… | βœ… | ⚠️ | βœ… | βœ… | βœ… | | Export to Markdown/PDF | βœ… | βœ… | ⚠️ | βœ… | βœ… | βœ… | | Snapshot-Based Versioning | βœ… | ❌ | βœ… | ⚠️ | ⚠️ | βœ… | | Inline Comments & Discussions | βœ… | βœ… | ⚠️ | ❌ | ❌ | βœ… | | Per-User Access Control | βœ… | βœ… | βœ… | ❌ | ⚠️ | βœ… | > ⚠️ = Partially supported or requires plugins/workarounds \ > ❌ = Not supported ## Got Feedback? Notivae is early-stage β€” rough, changing, and evolving. We'd love your input! Head to the [GitHub repo](https://github.com/notivae/notivae) to report issues, suggest improvements, or star the project. --- **Thanks for trying out Notivae.** Your knowledge. Your structure. Your control. ## @lucide:bot LLMs.txt Support To improve compatibility with AI tools, Notivae provides a machine-readable [`llms.txt`](/llms.txt) file. This file helps large language models (LLMs) β€” such as those used in AI-powered search, summarization, or assistant systems β€” understand the structure and content of our documentation. It includes clean, structured Markdown for each public page, along with its canonical URL. Developers building tools, bots, or integrations can use this to: - Feed context into chat-based assistants - Build semantic search or RAG pipelines - Preprocess documentation for embedding/indexing @lucide:file-text [View llms.txt](/llms.txt) --- url: /start/requirements content: | # @lucide:clipboard-list Requirements This page outlines the minimum and recommended requirements for deploying and running **Notivae**. These requirements vary depending on your intended usage, number of users, and system workload. ## @lucide:wrench Prerequisites Notivae is deployed exclusively using **Docker** and **Docker Compose**. Ensure both are installed and functioning on your host system before proceeding with the [installation](./installation/index.md). ## @lucide:cpu CPU Notivae is designed to run on **low-powered hardware**, making it suitable for self-hosted deployments and lightweight environments. However, the **actual CPU requirements depend on the number of users and the expected workload**. Workload is influenced by factors such as: - The number of concurrent users - User activity (e.g., real-time collaboration, editing, and viewing frequency) - Document complexity and size - Usage of features like version history or media embedding For small teams or personal use, a single-core virtual CPU (vCPU) should be sufficient. For larger teams or public-facing instances, allocate more CPU resources to maintain performance under load. ## @lucide:memory-stick Memory (RAM) - **Minimum**: 512MB - **Recommended**: 1GB or more for better performance Memory usage grows with the number of active users and document interactions. High concurrency, frequent edits, or large documents will increase memory demand. ## @lucide:save Disk Requirements Disk performance can impact both the responsiveness and reliability of your Notivae instance. - **Storage Type**: SSDs are strongly recommended over HDDs for faster read/write operations, especially under load. - **Storage Capacity**: The required disk space depends on: - The number of users - The volume and size of stored notes - Any embedded content or attachments Plan for growth and monitor usage over time to avoid disruptions. ## Other Dependencies ### @lucide:globe Dedicated Domain or Sub-domain A dedicated domain or sub-domain (e.g., `notivae.example.com`) is **only required for public-facing deployments**, but it is **strongly recommended** even for internal or limited-use setups. Without a proper domain: - Some features like **link-sharing** may not work reliably - **Authentication providers** often require a valid domain for redirect URIs and session handling - Cross-device or remote access may be limited or problematic While technically optional in private network environments, using a domain helps ensure full feature compatibility and smoother operation. ### @lucide:fingerprint Authentication Provider Authentication is **required** in Notivae to associate documents and data with individual user accounts. By default, Notivae includes a built-in authentication system using email or username and password. Alternatively, Notivae can integrate with external authentication providers for single sign-on (SSO) or centralized user management. Supported providers include: - OAuth2 providers (e.g., GitHub, GitLab, Discord) - Any identity provider that supports OpenID Connect (OIDC) ## Additional Recommendations - **HTTPS Support**: Use TLS/SSL certificates for encrypted traffic (strongly recommended, especially for public deployments). - **Persistent Storage**: Ensure that your storage backend is reliable and backed up regularly. Document data and user metadata should be durable. - **Reverse Proxy**: Set up a reverse proxy (e.g., Nginx, Caddy, or Traefik) to manage routing, SSL termination, and headers. - **Monitoring and Logging**: Set up basic logging and metrics collection to track performance, detect issues early, and plan scaling. --- url: /usage/document-structure content: | # @lucide:file-text Document Structure Notivae’s power lies in how you can organize your knowledge into clear, nested structures β€” making it easy to find, edit, and collaborate on content. ## Documents and Collections - **Collections** are like folders. They help you group related documents logically. (e.g. `Work` or `Studies`) - **Documents** contain the actual markdown content. Each user’s workspace holds multiple collections, and each collection contains multiple documents. ## Nesting Documents Documents can be **nested inside other documents** to create deep hierarchies that mirror your thinking or project needs. Example: ``` πŸ“ Programming Notes ┣ πŸ“„ Languages ┃ ┣ πŸ“„ Rust ┃ β”— πŸ“„ Python ┣ πŸ“„ Tools ┃ β”— πŸ“„ Docker β”— πŸ“„ Personal Roadmap ``` This lets you structure your notes as folders and subfolders, but within the markdown document hierarchy. ## Benefits of Nested Structure - Organize large knowledge bases clearly - Focus on small, manageable documents while keeping the big picture - Enable granular access control at different hierarchy levels (planned) - Support versioning and snapshots per document ## Navigation and UI Notivae’s UI reflects this hierarchy with: - Sidebar trees to browse collections and documents - Breadcrumbs for context inside nested documents - Quick search to jump between documents --- By structuring your knowledge this way, Notivae helps you maintain clarity, context, and control over your content β€” whether you’re working solo or collaborating. --- url: /usage/editor-guide content: | --- url: /usage/sharing-documents content: | --- url: /usage/workspace-management content: |