jotty·page

A self-hosted app for your checklists and notes.

jotty·page is a lightweight alternative for managing your personal checklists and notes. It's extremely easy to deploy, keeps all your data on your own server and allows you to encrypt/decrypt your notes for your personal peace of mind.

ex rwMarkable

---

Join our communities

---

<em>Clean, intuitive interface for managing your checklists and tasks.</em>

<em>Rich text editor for notes.</em>

Quick nav

• Features
• Getting Started
• Docker Compose (Recommended)
• Initial Setup
• Data Storage
• Versioning Scheme
• Encryption
• API
• Shortcuts
• Single Sign-On (SSO) with OIDC
• Multi-Factor Authentication (MFA)
• Translations
• Custom Themes and Emojis

Features

• Checklists: Create task lists with drag & drop reordering, progress bars, and categories. Supports both simple checklists and advanced task projects with Kanban boards and time tracking.
• Rich Text Notes: A clean WYSIWYG editor for your notes, powered by TipTap with full Markdown support and syntax highlighting.
• Sharing: Share checklists or notes with other users on your instance, including public sharing with shareable links.
• File-Based: No database needed! Everything is stored in simple Markdown and JSON files in a single data directory.
• User Management: An admin panel to create and manage user accounts with session tracking.
• Customisable: 14 built-in themes plus custom theme support with custom emojis and icons.
• Encryption: Full on PGP encryption, read more about it in howto/ENCRYPTION.md
• API Access: Programmatic access to your checklists and notes via REST API with authentication.
• PWA Jotty doesn't have a native app, but it's built mobile first. Once installed the PWA on your device it will feel like you installed it from the app store. There's also partial offline caching, as long as you visited a page while online Jotty will allow you to re-visit it while offline. At the moment there's no current support for offline CRUD operation.

Getting Started

My recommended way to run jotty·page is with Docker. You can also use:

• The Proxmox community script for Proxmox VE
• The Unraid template for Unraid Community Applications

Docker Compose (Recommended)

1. Create a docker-compose.yml file:

   📖 For advanced settings and more information about how the docker compose file works and what these variables do, please read howto/DOCKER.md

   yaml 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

2. Create the data directory and set permissions:

   bash 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/

   Note: The cache directory is optional. If you don't want cache persistence, you can comment out the cache volume line in your docker-compose.yml.

3. Start the container:

   bash docker compose up -d

The application will be available at http://localhost:1122.

Initial Setup

On your first visit, you'll be redirected to /auth/setup to create your admin account if SSO is disabled, otherwise you'll be prompted to sign in via your choosen SSO provider.

Once that's done, you're ready to go! First user will be admin by default.

Data Storage

jotty·page uses a simple file-based storage system inside the data/ directory.

• data/checklists/: Stores all checklists as .md files.
• data/notes/: Stores all notes as .md files.
• data/users/: Contains users.json and sessions.json.
• data/sharing/: Contains shared-items.json.
• data/encryption/: Contains all public/private keys for all users.

Make sure you back up the data directory!

Versioning Scheme

This project uses a [STABLE].[FEATURE].[FIX] versioning scheme, not strict SemVer. As a product (not a package), this format makes more sense for my specific release cycle.

My format is 1.10.1, which breaks down as:

• 1.x.x (Stable): The 1 represents the current stable generation. I will only change this (e.g., to 2.0.0) for a complete rewrite or a fundamental shift in the product or seriously breaking changes.

• x.10.x (Feature): This is the main release number. I increment this for new features, code refactors, or significant changes (e.g., 1.9.0 -> 1.10.0). This is the equivalent of a SemVer MINOR bump.

• x.x.1 (Fix): This is incremented only for hotfixes, bug-fix-only and very minor feature releases (e.g., 1.10.0 -> 1.10.1). This is the equivalent of a SemVer PATCH bump.

A Note on "Breaking" Changes

A Feature release (like 1.10.0) may include major backend or data structure changes. When this happens, I will always provide an automatic migration script that runs on first launch to update your data seamlessly.

Because the migration is automatic, I do not consider this a "breaking" change that requires a 2.0.0 version.

I will always detail these migrations in the release notes. I highly recommend you back up your data before any feature update, just in case.

SUPPORTED MARKDOWN

jotty·page supports GitHub Flavored Markdown (GFM) and some custom syntax for complex functionality.

📖 For the complete MARKDOWN documentation, see howto/MARKDOWN.md

ENCRYPTION

jotty·page uses industry standard PGP encryption.

📖 For the complete ENCRYPTION documentation, see howto/ENCRYPTION.md

API

jotty·page includes a REST API for programmatic access to your checklists and notes. This is perfect for:

• Automation: Create tasks from external systems
• Integrations: Connect with other tools and services
• Scripts: Automate repetitive tasks
• Dashboards: Build custom interfaces

📖 For the complete API documentation, see howto/API.md

SHORTCUTS

jotty·page supports a wide range of keyboard shortcuts to help you navigate and edit more efficiently without leaving the keyboard. They are divided into two main categories: global shortcuts that work anywhere in the app, and editor-specific shortcuts that work when you are writing a note.

📖 For the complete SHORTCUTS documentation, see howto/SHORTCUTS.md

Single Sign-On (SSO) with OIDC

jotty·page supports any OIDC provider (Authentik, Auth0, Keycloak, Okta, Google, EntraID, etc.)

📖 For the complete SSO documentation, see howto/SSO.md

Multi-Factor Authentication (MFA)

jotty·page supports MFA, this needs to be enabled in settings -> profile

📖 For the complete MFA documentation, see howto/MFA.md

Translations

jotty·page can be translated in multiple languages, all translations are community driven and can be found in the app/_translations directory.

📖 For the complete translations documentation, see howto/TRANSLATIONS.md

Custom Manifest

You can completely customize your PWA by creating an override manifest file. This allows you to change the app name, description, icons, colors, and more. Custom themes and emojis can be managed through the admin UI.

📖 For the complete customisation documentation, see howto/CUSTOMISATIONS.md 📖 For better understanding on how the PWA works see howto/PWA.md

Community shouts

I would like to thank the following members for raising issues and help test/debug them!

davehope	seigel	mariushosting	Isotop7	gavdgavd
IGOLz	floqui-nl	fruiz1972	Sku1ly	ItsNoted
red-bw	kn0rr0x	mroovers	Ryderjj89	spaghetti-coder
hurleyy