Jotty: Ditch Notion for This Self-Hosted Note App

Jotty: Ditch Notion for This Self-Hosted Note App

Your notes are not your own. Every keystroke in Notion, every checklist in Todoist, every "private" journal entry in Evernote—it all lives on someone else's server. Subject to their terms. Their breaches. Their sudden pricing changes that lock your data behind paywalls.

Sound familiar? You've probably felt that nagging discomfort. The one that hits when you realize your entire second brain sits in a cloud you don't control. When the API you relied on vanishes overnight. When the "free tier" suddenly costs $15/month just to access your own thoughts.

Here's the brutal truth: developers and privacy-conscious professionals are abandoning SaaS note-taking in droves. But the alternatives? They're either bloated, require a PhD in DevOps^{↗ Bright Coding Blog}, or look like they were designed in 2003.

Enter Jotty—the lightweight, file-based, self-hosted notes and checklists app that's making developers actually excited about personal knowledge management again. No database. No vendor lock-in. Just pure Markdown^{↗ Smart Converter} files, PGP encryption, and a deployment so simple you'll have it running before your coffee gets cold.

Ready to reclaim your data? Let's dive deep into why Jotty might be the last note-taking app you'll ever need.

What is Jotty?

Jotty (stylized as jotty·page) is an open-source, self-hosted web application for managing personal checklists and notes. Created by fccview and evolved from the earlier project rwMarkable, Jotty represents a deliberate rejection of the complexity that plagues modern productivity software.

At its core, Jotty is built on a radical philosophy: your data should live in plain files you can read, move, and back up with standard tools. No opaque databases. No proprietary formats. Just Markdown and JSON living comfortably in a directory structure you completely own.

The project has gained serious traction in developer and self-hosting communities for one simple reason—it solves the deployment paradox. Most self-hosted apps promise freedom but demand hours of configuration, dependency hell, and ongoing maintenance. Jotty? One Docker^{↗ Bright Coding Blog} Compose file. Five minutes. Done.

But don't let the simplicity fool you. Under that clean interface lurks serious capability: PGP encryption for sensitive notes, Kanban boards for project management, REST API for automation, OIDC SSO for enterprise environments, and MFA for security-conscious users. It's the rare tool that respects beginners while rewarding power users.

The versioning scheme itself reveals the creator's product-thinking: [STABLE].[FEATURE].[FIX] (e.g., 1.10.1). Unlike rigid SemVer, this acknowledges that Jotty is a product—not a package—and that feature releases may include data migrations. The promise? Automatic migration scripts on every feature update. Your data evolves seamlessly.

Key Features That Set Jotty Apart

Zero-Database Architecture

Jotty's most controversial—and brilliant—decision is abandoning databases entirely. Every checklist, every note, every user session lives as plain files in a predictable directory structure. This means:

• Instant backups: rsync, restic, or even cp -r your entire data directory
• Version control friendly: Git-track your notes if you're so inclined
• Zero migration headaches: Your data is never trapped in schema changes
• Future-proof: Markdown will outlive every SaaS platform

Military-Grade Encryption (That You Control)

Jotty implements full PGP encryption for notes that demand confidentiality. Unlike "encrypted at rest" cloud services where the provider holds the keys, Jotty's encryption is client-side and user-controlled. Your private key never leaves your server. Even if someone gains filesystem access, encrypted notes remain unreadable without your passphrase.

Kanban + Time Tracking in a "Simple" Notes App

The checklist system transcends basic todo lists. We're talking:

• Drag-and-drop reordering with visual progress bars
• Kanban boards for complex project workflows
• Time tracking built directly into tasks
• Categories for organization without rigid folder structures

This isn't a notes app with tasks bolted on. It's a legitimate project management tool that happens to store everything in Markdown.

TipTap-Powered Rich Editing with Markdown Soul

The WYSIWYG editor uses TipTap (the ProseMirror-based framework), giving you:

• Clean visual editing that feels like Notion
• Full GitHub Flavored Markdown support underneath
• Syntax highlighting for code blocks
• Export confidence: your data is always valid Markdown

Enterprise Features, Homelab Simplicity

Jotty sneaks serious infrastructure features into a personal tool:

• OIDC SSO: Authentik, Keycloak, Auth0, Okta, Google, EntraID—pick your provider
• MFA/TOTP: Settings → Profile, enable, done
• REST API: Full programmatic access for automation warriors
• PWA with offline caching: Visit a page online, revisit it offline (partial support, with full offline CRUD planned)

Obsessive Customization

14 built-in themes, custom theme support, custom emojis, custom icons, and even a custom PWA manifest override. Your Jotty instance can look and feel completely unique.

Real-World Use Cases Where Jotty Dominates

1. The Privacy-Paranoid Professional

You're a consultant handling sensitive client data. Legal requirements prohibit cloud storage. Jotty lives on your VPS or home server, encrypts sensitive case notes with PGP, and never touches third-party infrastructure. Your compliance officer sleeps soundly.

2. The Homelab Archivist

You've got 50 self-hosted services and a hatred for "just one more database container." Jotty's file-based storage means your notes backup strategy is identical to your media server strategy: simple, scriptable, reliable. No mysqldump gymnastics required.

3. The Offline-Capable Developer

You work from planes, trains, and rural cabins with spotty connectivity. Jotty's PWA caches visited pages for offline reading. Your documentation, project specs, and personal runbooks remain accessible when the world drops away.

4. The Automation Obsessive

Your todo list should populate from GitHub issues. Your daily notes should trigger from cron. Jotty's REST API with authentication lets you build these pipelines. Create checklists from CI/CD failures. Log deployment notes programmatically. Your imagination—and curl skills—are the only limits.

5. The Team That Outgrew Shared Documents

Small teams need collaboration without Notion's pricing or Confluence's complexity. Jotty's sharing system includes public shareable links and inter-user sharing on the same instance. Deploy once, collaborate infinitely.

Step-by-Step Installation & Setup Guide

Prerequisites

• Docker and Docker Compose installed
• A server or NAS with persistent storage (or your local machine)
• 5 minutes of focused attention

Step 1: Create Your Docker Compose File

Create docker-compose.yml with this exact configuration:

services:
  jotty:
    image: ghcr.io/fccview/jotty:latest
    container_name: jotty
    user: "1000:1000"  # Run as non-root for security
    ports:
      - "1122:3000"   # Host port 1122 maps to container port 3000
    volumes:
      - ./data:/app/data:rw         # Your precious data lives here
      - ./config:/app/config:rw     # Configuration files
      - ./cache:/app/.next/cache:rw # Optional: Next.js↗ Bright Coding Blog build cache persistence
    restart: unless-stopped          # Auto-recover from crashes
    environment:
      - NODE_ENV=production         # Production optimizations enabled

Critical insight: The user: "1000:1000" line isn't decorative. Running containers as root is a security anti-pattern. This maps to your host's UID/GID 1000 (typically your first user). Adjust if your setup differs.

Step 2: Prepare the Data Directory Structure

Jotty expects specific subdirectories. Create them precisely:

# Create all required directories in one command
mkdir -p config data/users data/checklists data/notes data/sharing data/encryption cache

# Set ownership to match the container's user (1000:1000)
sudo chown -R 1000:1000 data/
sudo chown -R 1000:1000 config/
sudo chown -R 1000:1000 cache/

Why this matters: Without correct permissions, Jotty can't write your notes. You'll see cryptic errors or silent failures. The chown ensures the container user owns these paths.

Optional optimization: Don't need cache persistence across restarts? Comment out the cache volume line. You'll sacrifice slightly faster subsequent startups for marginally simpler setup.

Step 3: Launch and Verify

docker compose up -d

The -d detaches the process. Check logs with docker logs -f jotty if troubleshooting.

Navigate to http://localhost:1122 (or your server's IP). You'll hit the initial setup wizard at /auth/setup.

Step 4: First-Time Configuration

If SSO is disabled (default), create your admin account directly. The first user becomes admin automatically—no separate admin creation step.

If you've configured OIDC (see howto/SSO.md), you'll authenticate through your chosen provider instead.

Alternative Deployments

• Proxmox VE: Use the community script for one-click LXC container creation
• Unraid: Install via the Community Applications template

REAL Code Examples from Jotty's Architecture

Let's examine how Jotty's design decisions manifest in actual implementation patterns.

Example 1: The File-Based Storage Contract

Jotty's data directory structure reveals its architectural philosophy:

data/
├── checklists/          # Each checklist: a single .md file
├── notes/               # Each note: a single .md file  
├── users/
│   ├── users.json       # User accounts (hashed passwords, metadata)
│   └── sessions.json    # Active session tokens
├── sharing/
│   └── shared-items.json  # Share metadata and permissions
└── encryption/
    └── [user-id]/       # Per-user PGP key pairs
        ├── public.key
        └── private.key  # Protected by user passphrase

Why this pattern matters: Every piece of data is individually addressable. Corrupted one checklist? The rest survive. Want to git diff your note history? Standard tools work. Need to grep across all notes? grep -r "TODO" data/notes/. This is the power of rejecting database opacity.

Example 2: Docker Compose Security Hardening

The recommended compose file includes subtle security wins:

services:
  jotty:
    image: ghcr.io/fccview/jotty:latest
    container_name: jotty
    user: "1000:1000"  # ← Non-root execution: limits container breakout damage
    ports:
      - "1122:3000"   # ← Non-privileged host port: no root needed to bind
    # ... volumes, environment

The user directive explained: By default, Docker containers run as root (UID 0). If an attacker exploits the Jotty application, they gain root inside the container—and potentially on your host via container escape vulnerabilities. The 1000:1000 mapping contains this blast radius to regular user privileges.

The port choice: Binding to ports <1024 requires root on Linux. Jotty uses 1122 externally, avoiding this requirement entirely. Your reverse proxy (nginx, Traefik, Caddy) handles 443 → 1122 mapping.

Example 3: Environment-Aware Production Build

    environment:
      - NODE_ENV=production

This single variable triggers cascading optimizations in Jotty's Next.js foundation:

• Dead code elimination: Development-only debug paths stripped
• Minification: Smaller bundle sizes, faster loads
• Error handling: User-friendly error pages instead of stack traces
• Caching: Aggressive static asset caching enabled

Deployment tip: Never run NODE_ENV=development in production. The performance difference is dramatic, and debug endpoints may expose sensitive information.

Example 4: Volume Mount Semantics

    volumes:
      - ./data:/app/data:rw

The :rw (read-write) suffix is explicit documentation. Jotty must write here. Contrast with truly static assets that could use :ro (read-only) for additional security hardening.

Backup strategy emerges naturally from this design:

# Automated daily backup via cron
0 2 * * * tar czf /backups/jotty-$(date +\%Y\%m\%d).tar.gz /path/to/jotty/data

# Or with restic for deduplicated, encrypted backups
restic backup /path/to/jotty/data --tag jotty-daily

No database dump scripts. No connection string management. Just files.

Advanced Usage & Best Practices

Encryption: When and How

Not every note needs PGP overhead. Use encryption strategically:

• Encrypt: Password lists, financial records, sensitive client details, personal journal entries
• Skip: Project documentation, public reference material, shared team checklists

The encryption setup is per-user and managed through the UI. Your private key passphrase is never stored server-side—decryption happens in your browser with your key.

API Automation Patterns

Jotty's REST API (documented in howto/API.md) enables powerful workflows:

# Example: Create a checklist from a failed CI pipeline
curl -X POST https://your-jotty-instance/api/checklists \
  -H "Authorization: Bearer $JOTTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy Fix: Build #'$BUILD_NUMBER'",
    "items": [
      {"text": "Investigate '$FAILED_STEP' failure", "done": false},
      {"text": "Apply patch", "done": false},
      {"text": "Re-run pipeline", "done": false}
    ]
  }'

Store your API token in environment variables or secret managers—never commit to version control.

Theme Development

With 14 built-in themes and custom CSS support, Jotty can match any aesthetic. The custom manifest system (howto/CUSTOMISATIONS.md) even lets you rebrand the entire PWA experience—app name, icons, colors—for white-label deployments.

Performance: Cache Strategy

The optional cache volume (./cache:/app/.next/cache:rw) persists Next.js build artifacts. On container restart:

• With cache volume: Sub-second startup, incremental builds preserved
• Without cache volume: ~10-30 second rebuild on first request

For production instances, include the cache volume. For ephemeral test deployments, omit it.

Comparison with Alternatives

Jotty wins when: You want self-hosting simplicity, file-based data freedom, and enterprise features without enterprise complexity.

Alternatives win when: You need full offline CRUD (Joplin, Obsidian), collaborative real-time editing (Notion), or established plugin ecosystems (Obsidian).

FAQ

Q: Is Jotty completely free?

Yes. Jotty is open-source under a permissive license. No feature paywalls, no usage limits, no "pro tier." The creator accepts donations via Buy Me a Coffee, but everything is functionally free.

Q: How does Jotty handle backups?

Since all data lives in the data/ directory as plain files, any backup strategy works: rsync, restic, borg, cloud sync tools, or even manual copies. The README explicitly warns: make sure you back up the data directory!

Q: Can I migrate from Notion/Evernote?

Jotty accepts Markdown files natively. Export from Notion as Markdown, place files in data/notes/ or data/checklists/, and Jotty recognizes them. Some manual cleanup of Notion's export format may be needed.

Q: Is Jotty suitable for teams?

Small teams, yes. Jotty supports user management, sharing between instance users, and public shareable links. However, it lacks real-time collaborative editing—multiple users can edit shared items, but not simultaneously with live cursors.

Q: What about mobile apps?

No native iOS/Android apps exist. However, the PWA installation provides near-native experience: home screen icon, standalone window, offline page caching. Install from Chrome/Safari "Add to Home Screen."

Q: How secure is the encryption really?

Jotty uses standard PGP (OpenPGP). Private keys are encrypted with your passphrase and stored server-side. Decryption happens client-side in your browser. The server never sees your passphrase or unencrypted content. For maximum security, verify the implementation details in howto/ENCRYPTION.md.

Q: Can I run Jotty without Docker?

The README emphasizes Docker as the recommended path. Alternative deployment methods (Proxmox script, Unraid template) still containerize the application. Running directly from source would require Node.js environment setup and manual dependency management—not officially supported.

Conclusion: Own Your Thoughts, Own Your Stack

Jotty represents something rare in modern software: a tool that respects both your time and your sovereignty. It doesn't demand you become a DevOps engineer to self-host. It doesn't trap your data in opaque formats. It doesn't monetize your attention or sell your patterns.

What it does: gives you a beautiful, capable notes and checklists system that happens to live on hardware you control, in files you can read with cat, encrypted with keys only you possess.

The file-based architecture isn't nostalgia—it's future-proofing. When Jotty 2.0 arrives, your Markdown files migrate forward. When you switch tools entirely, your data leaves with zero friction. When you die, your heirs can actually read your notes without API keys and subscription renewals.

Is Jotty perfect? No. The offline CRUD gap is real. The plugin ecosystem doesn't exist yet. Real-time collaboration is absent. But for the vast middle ground of personal and small-team knowledge work, these tradeoffs are consciously correct.

My verdict: If you've been waiting for a self-hosted notes app that deploys like a dream and respects your data like a vault, Jotty is that tool. Stop renting your second brain. Own it.

👉 Get started now: github.com/fccview/jotty

Star the repo, join the Discord, and start building your personal knowledge fortress today.

Have you deployed Jotty? Share your setup in the comments—homelab warriors, I'd love to hear your backup automation strategies.