Jotty: self-hosted notes and checklists with file-based storage and no database

File-based storage separates content by type across five subdirectories under data/

Jotty, hosted at jotty.page and formerly named rwMarkable, is a self-hosted application for personal checklists and notes built with TypeScript on Next.js. All content lands in a single data/ directory tree organized by type: checklists and notes as Markdown files in their respective subdirectories, user account and session data as users.json and sessions.json inside data/users/, sharing state as shared-items.json in data/sharing/, and PGP encryption keys in data/encryption/.

This file-based approach eliminates the database setup step and the need to run a database process alongside the application. Content is readable with any text editor, and moving an instance to a different server means copying two directories: data/ and config/. The README is explicit about the corresponding responsibility: make sure the data directory is backed up. Missing a backup means losing notes, user accounts, sharing records and encryption keys together, since all five subdirectories live in the same tree.

For personal deployment, the no-database model keeps the operational footprint small. For multi-user or concurrent-write scenarios, the absence of a query layer and transaction guarantees is a boundary to consider before committing to this tool.

Docker Compose on port 1122 requires three commands; bare Node.js needs 22.15 or 23.11

Docker Compose is the documented recommended path. The official image is ghcr.io/fccview/jotty:latest, and the compose file runs the container as user 1000:1000 with bind mounts for persistent data, configuration and the Next.js page cache.

services:
  jotty:
    image: ghcr.io/fccview/jotty:latest
    container_name: jotty
    user: "1000:1000"
    ports:
      - "1122:3000"
    volumes:
      - ./data:/app/data:rw
      - ./config:/app/config:rw
      - ./cache:/app/.next/cache:rw
    restart: unless-stopped
    environment:
      - NODE_ENV=production

Before launching the stack, the directories and their ownership must be set:

mkdir -p config data/users data/checklists data/notes data/sharing data/encryption cache
sudo chown -R 1000:1000 data/
sudo chown -R 1000:1000 config/
sudo chown -R 1000:1000 cache/

After that preparation, starting the stack is:

docker compose up -d

Once running, the application is accessible on the host at http://localhost:1122. On first visit, the router sends the browser to /auth/setup to create the initial account, and that first account automatically receives admin status.

Alternatives to Docker include a Proxmox community script for Proxmox VE and an Unraid template for Unraid Community Applications. Bare Node.js deployments require Node.js 22.15 or later within the 22.x series, or 23.11 or later in any later series, as documented in the engines field of package.json.

Simple checklists and Kanban boards are two modes; TipTap 3.31.3 drives the note editor

Checklists in Jotty come in two modes: a simple list with drag-and-drop reordering, progress bars and categories, and an advanced task project that adds a Kanban board layout with time tracking. Both modes exist within the same application, and neither the README nor the feature list states whether an existing list can be converted between modes after creation, which is worth confirming before building out a project in one mode.

Notes use TipTap for the editor, included at 3.31.3 in package.json. Extension packages in the dependencies cover bubble menus, code blocks, color, highlights, images, links, tables and task lists. The README describes the editor as a WYSIWYG interface with full Markdown support and syntax highlighting.

One production dependency in package.json is @excalidraw/excalidraw 0.18.1, a drawing and whiteboarding library. The README's feature list covers eight items: checklists, rich text notes, sharing, file-based storage, user management, customization, encryption, API access and PWA. No drawing or whiteboard capability appears in that list, so the Excalidraw dependency is present in the production build without documentation in the current feature set.

Both checklists and notes support sharing with other users on the same instance, and public shareable links are a separate option. Cross-instance sharing is not documented anywhere in the README.

PGP encryption keeps per-user key pairs inside data/encryption/, which the backup instruction covers

Jotty includes per-note PGP encryption, described as full PGP encryption in the README with details in howto/ENCRYPTION.md. Implementation stores public and private key pairs per user under data/encryption/, which is one of the five subdirectories inside data/.

The key storage location has a direct implication for the backup strategy. Encryption keys live on the same server as the encrypted notes, within the same directory tree the backup instruction covers. A backup that omits data/ loses both the notes and the keys needed to decrypt any previously shared encrypted content; restoring from a backup without the keys leaves encrypted notes unreadable regardless of whether the note files themselves were preserved.

Content is protected from someone who reads raw Markdown files without server access, though not from an attacker who gains full access to the data/ directory. This is a design consequence of client-side encryption stored server-side, and it is the boundary to understand before deciding how much to rely on the encryption feature.

Sharing encrypted notes between users on the same instance uses the recipient's public key from data/encryption/. Full mechanism details are in howto/ENCRYPTION.md rather than in the README.

Key management operations such as rotation or revocation are not addressed in the README. Before relying on the encryption feature for long-term sensitive storage, howto/ENCRYPTION.md is the document to read in full, since the README only confirms that PGP is the underlying technology and that key pairs are stored per user in data/encryption/.

PWA offline mode caches previously visited pages; editing requires a live server connection

Jotty is mobile-first and installable as a Progressive Web App. There is no native iOS or Android application; the PWA is the documented mobile path, and the README describes the installed experience as equivalent to a store-installed application.

Offline capability is partial. Pages loaded during a previous online session are cached by the service worker and remain accessible when the connection drops. Pages not yet visited while online will not load offline, even if the content exists on the server. Writing data of any kind, creating notes, editing checklist items or deleting content, requires an active connection to the self-hosted instance. This constraint is a meaningful limitation for anyone who expects to edit content in environments with intermittent network access.

The theme system offers 14 built-in choices alongside custom theme support with custom emojis and icons. Customization is applied at the instance level through the configuration layer rather than as a per-user setting. The repository also lists MFA under "Multi-Factor Authentication (MFA)" in the README navigation, as a feature distinct from SSO.

SSO via OIDC is configured through environment variables in the compose file

SSO is configured through environment variables rather than through a running settings screen. Setting AUTH_MODE=oidc enables OIDC-based login and requires three additional variables: OIDC_ISSUER for the identity provider, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET for the registered application credentials. An optional SSO_FALLBACK_LOCAL=yes allows local password login alongside OIDC, and OIDC_ADMIN_GROUPS=admins assigns Jotty admin status to members of a named OIDC group. All of these appear as commented-out lines in the docker-compose.yml file at the repository root, ready to be uncommented and filled in.

When SSO is not configured, the first visit triggers the /auth/setup flow to create local accounts. User accounts and sessions are managed from an admin panel with session tracking.

The REST API is controlled by ENABLE_API_DOCS=true, which exposes the API documentation endpoint; without that variable set, the documentation is not accessible. JOTTY_BODY_SIZE_LIMIT=100mb sets the maximum upload size for both the web interface and API uploads. Both variables are in the same docker-compose.yml commented block as the SSO variables, which means the full configuration surface is visible before deployment in a single file.

The [STABLE].[FEATURE].[FIX] versioning scheme differs from SemVer in how it handles breaking changes

Jotty's numbering format is [STABLE].[FEATURE].[FIX] rather than SemVer, described in the README as appropriate for a product rather than a library package. Only a complete rewrite or a fundamental shift in the product triggers the STABLE increment. The FEATURE digit covers new features, code refactors and significant changes, which the README describes as equivalent to a SemVer MINOR bump. The FIX digit covers hotfixes and minor bug fixes only.

A section of the README titled "A Note on Breaking Changes" addresses how Feature-level increments relate to breaking changes. Operators who rely on tooling that parses SemVer to detect breaking changes automatically should verify whether it handles this custom format before applying FEATURE-digit upgrades to a running instance.

Version 1.28.0 was released on 2026-09-28 and the last push was on 2026-10-04 under an AGPL-3.0 licence that requires operators who modify Jotty and serve it to others to publish those modifications.

Editorial conclusion

Jotty is appropriate for individuals and homelab operators who want a self-hosted notes and checklist app without a database, and who can keep regular backups of the data/ directory. Users who need reliable offline write operations or content sharing across separate instances should look at database-backed alternatives. Before deploying, verify your Docker or Node.js environment meets the stated runtime requirements, and read howto/ENCRYPTION.md before enabling PGP encryption on any content you plan to share.

Frequently asked questions

Official sources

1. fccview/jotty on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases