globnotes
Docker app from alexindigo's Repository
A self-hosted, database-less note taking web app over a flat folder of markdown files.
Overview
Readme
View on GitHubA self-hosted, database-less note-taking web app built for Obsidian vaults and nested Markdown trees.
globnotes is a fork of flatnotes by Adam Dullage. flatnotes deliberately keeps every note in one flat directory; globnotes keeps its spirit (zero-config, single container, distraction-free) and adds support for notes in subdirectories. A note's relative path identifies it; its display title can come from its content.
data/
├── dad/
│ ├── recipes/
│ │ └── soup.md → note at /dad/recipes/soup
│ └── assets/
│ └── broth.jpg → served at /dad/assets/broth.jpg
└── ideas.md → note at /ideas
Obsidian-flavored support
globnotes renders the markdown features Obsidian users rely on — and the set grows over time.
Supported today:
- Wikilinks
[[wikilink]]with|aliasand#headinglinks - Image and file embeds
![[image.png]],![[doc.pdf]] - Callouts
> [!note],> [!warning], … - Hidden comments
%%comments%% - Highlight
==mark== - Mermaid diagrams
- YAML frontmatter (title, aliases, and more)
- KaTeX math
- Automatic URL linking
Not yet (roadmap): note transclusion (![[Note]]), block references/transclusion, task lists, footnotes, abbreviations/definition lists/emoji/sub/superscript, Dataview-style queries, and graph view.
Why
Markdown is supposed to be app-independent. If your notes already live in folders — an Obsidian vault, a git repo, a Syncthing share — globnotes gives you a clean web view (and editor) over exactly that structure, without flattening anything. Mount whatever you like as subdirectories:
volumes:
- /srv/dad-notes:/data/dad
- /srv/mom-notes:/data/mom
Folders are never "managed": creating a/b/c makes the directories, renaming a/b → x/y moves the file, and empty directories are pruned away (git-style).
Plain HTTP homelabs
globnotes supports ordinary HTTP on a local domain such as
http://globnotes.home/ or a LAN address. Viewing, creating, editing and saving
notes do not require a publicly registered domain, externally issued certificate,
HTTPS connection or browser secure-context exception. Resolve your local name to
the machine serving globnotes using your own local DNS or hosts mapping.
Internal UUIDs use one shared cryptographically random generator backed by
crypto.getRandomValues(), which browsers make available on plain HTTP. Plugins
can use the same contract through ctx.createUuid() or the browser
@globnotes/plugin-sdk export; see the Plugin API.
Features
- Real-path notes — the URL path IS the vault path:
/dad/recipes/soupis the note,/dad/assets/broth.jpgis its image. Relative links (,[x](../other.md)) work exactly like in Obsidian — no rewriting, no magic. - Obsidian-flavored rendering —
[[wiki-links]](with|aliasand#heading),![[image embeds]],==highlights==,> [!callouts],%%comments%%, YAML frontmatter, mermaid diagrams, KaTeX math. - Sidebar folder tree — Obsidian-style nested tree with expand/collapse, active-note highlight, filter textbox, and hover shortcuts to folder views.
- Search modal — one modal that jumps and searches: fuzzy-match a note by display title, alias, or path and open it, or take the pinned footer row into the full-text page. Matched characters are highlighted inline in the title/path of each row (filename hits outrank folder hits); top 10 results in a sticky footer'd list. top 9 results, every one with a
Ctrl/Cmd+Nshortcut;Ctrl/Cmd+Enteropens the full search with the query. Type#to complete tags; empty query shows this session's recently-opened notes. - 16 theme choices — System auto-detect plus light/dark variants of Globnotes, Catppuccin, Dracula, Gruvbox, Nord, Solarized and Tokyo Night. Settings → Appearance previews miniature notes grouped by family; System shows the default light/dark pair. Arrow keys move focus, Space/Enter applies without a page reload.
- Full-text search and
#tagsacross the whole tree, scoped to a folder or recursive, with real-time filtering. - New-note flow —
Untitled Nprefills in the current folder context; dead wiki-links offer a one-click "Create note" affordance. - Attachment-aware renames — moving a note across folders prompts you to move its referenced files along too, or just fix the links.
- First-run setup wizard — no auth env vars? globnotes asks on first launch: set a password or explicitly disable auth. Each choice is deliberate.
- Agent-friendly — raw markdown and files over plain HTTP (see below).
Versioned note backups
The shipped server plugin offers best-effort post-change previous Markdown text
history. Settings → Backups has a retention slider (default 2, integer 1–10)
and optional relative/absolute base. Newest is Note.md.0.bak; dedicated bases
mirror the captured original folder path. Adjacent backups are visible vault
files: public readers can retrieve old or deleted text under normal serving policy.
Note saves can succeed while backup delivery/storage fails. Histories are path-based;
changing bases does not migrate them. See the plugin guide
for environment pins, status, ownership/recovery and text/durability limits.
Getting started
This development tree uses v3 layered configuration.
v3 is not released. Build this checkout before using the v3 examples below;
do not use a published latest image with this configuration. The current
runtime serves only globnotes and requires an existing notes directory.
docker build -t globnotes:v3-dev .
docker run -d \
--name globnotes \
-p 8080:8080 \
-v /path/to/your/notes:/data/globnotes \
globnotes:v3-dev
Open http://localhost:8080 and complete the first-run setup: create a password, choose read-only (browse and search, no editing), or disable auth entirely (trusted networks only).
Or with docker compose from this checkout (create ./notes first and run
docker compose up -d --build):
services:
globnotes:
build: .
image: globnotes:v3-dev
container_name: globnotes
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./notes:/data/globnotes
# Optional: keep application state outside the notes tree.
# - ./state:/state
# Optional: mount additional sources as subdirectories
# - /srv/dad-notes:/data/globnotes/dad
# - /srv/mom-notes:/data/globnotes/mom
environment:
# Enable together with the ./state mount above:
# GLOBNOTES__METADATA_PATH: "/state"
TZ: "UTC"
Released v2 images (separate from this development tree)
Released images are published to Docker Hub
(alexindigo/globnotes) and GHCR
(ghcr.io/alexindigo/globnotes) with the same tags and content. For v2, select
:v2 (or :2) and follow the README/configuration shipped with that release,
not the v3 examples on this page. An exact tag such as :2.5.1 pins a release.
latest follows the numerically highest stable major. Once v3 ships, a later
v2 release updates 2 and v2 without moving latest back. See
releasing for tag details.
v3: keep application state outside your notes
GLOBNOTES__METADATA_PATH selects a metadata base. Vault state lives at
<metadata>/globnotes/, and instance metadata at <metadata>/_/. Without it,
vault state lives at <notes>/.globnotes/ and instance state at <base>/.globnotes/.
For a central Markdown repository shared with other editors, mount the existing notes directory directly and give globnotes a separate persistent state mount:
services:
globnotes:
build: .
image: globnotes:v3-dev
container_name: globnotes
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /srv/notes:/data/globnotes
- /srv/appdata/globnotes:/state
environment:
GLOBNOTES__METADATA_PATH: "/state"
Replace the host paths with your own directories. The left side of each mount is
a host path; the right side and both environment values are container paths.
In Unraid's container editor, the same setup is two path mappings (your notes to
/data/globnotes, application data to /state) and a variable named GLOBNOTES__METADATA_PATH
with value /state. /index is equally valid if that is your state mount's
container path; the directory name is not special.
| # | Content | Host location in this example |
|---|---|---|
| 1 | Markdown notes and attachments | /srv/notes/ |
| 2 | Saved setup/access and vault settings | /srv/appdata/globnotes/globnotes/config.json, config.toml |
| 3 | Search index and SQLite companion files | /srv/appdata/globnotes/globnotes/index.sqlite, index.sqlite-wal, index.sqlite-shm |
| 4 | Custom branding files | /srv/appdata/globnotes/globnotes/brand/ |
| 5 | Custom plugins and plugin policy | /srv/appdata/globnotes/globnotes/plugins/, plugins.json |
The value is the metadata base: /state means
/state/globnotes/config.toml, not /state/config.toml. State remains grouped
together; this setting does not provide independent directories for config and
the database. Keep it on a persistent mount so container recreation preserves
your settings. Environment-provided settings retain precedence over saved setup
choices.
Outside Docker, set GLOBNOTES_GLOBNOTES_PATH to the actual notes directory and
GLOBNOTES__METADATA_PATH to the actual metadata base. There is no
container-path translation in a native deployment.
The application user needs access to both directories and write permission for
state and any notes it edits. Container startup only adjusts ownership of the
selected state directory; it does not change ownership of the notes tree. Use
PUID/PGID when you need to select the application user's IDs explicitly.
Moving an existing installation
Changing GLOBNOTES__METADATA_PATH does not move existing state automatically.
Preserve the existing state rather than treating .globnotes as disposable cache:
it contains saved access configuration and other persistent application data.
| Step | Action |
|---|---|
| 1 | Stop globnotes before transferring state, so SQLite and configuration files are not changing during the copy. Back up the existing .globnotes directory. |
| 2 | For a v3 metadata relocation, copy its entire contents, including hidden files and SQLite companions, into an empty per-vault destination such as /srv/appdata/globnotes/globnotes/. Do not merge installations. v2 importing is separate future work, not a boot conversion. |
| 3 | Add the state mount, set GLOBNOTES__METADATA_PATH to its container base path, and ensure the application user can access the destination. Restart globnotes. |
| 4 | Confirm that the existing access configuration, branding, plugins, notes and search are present. Retain the original backup; remove the old vault-local state only after confirming the migration. |
Pointing at an empty state directory without copying the old configuration may start the first-run setup wizard again. Startup never issues relocation hints, converts old JSON, deletes legacy index files or performs the transfer. Treat the state directory and its backups as sensitive: configuration can contain authentication and signing material.
Note backups are separate from core application state. On versions with the
Versioned note backups plugin, GLOBNOTES__METADATA_PATH does not relocate its backup
files. The plugin defaults to backups beside notes and keeps recovery bookkeeping
in <vault>/.globnotes-backup/. Settings → Backups can select a separate backup
destination, but relocating core state alone does not move every plugin-created
file out of the vault.
Shared vaults and symbolic links
To expose an existing central notes directory in Docker, bind-mount that directory
directly as /data/globnotes, as above. To expose several directories under one notes root,
use separate mounts such as /srv/dad-notes:/data/globnotes/dad and
/srv/mom-notes:/data/globnotes/mom. These are folders in one served tree, not separate
instances with independent access settings.
A symlink inside a mounted directory is resolved in the container's filesystem.
For example, a mounted /data/shared link pointing to /srv/central-notes does
not also expose the host's /srv/central-notes. Its target must exist at that path
inside the container. A direct bind mount makes the intended notes visible without
depending on that host-only symlink target.
The current folder tree and recursive note scanner do not traverse symlinked subdirectories inside the vault. A symlink used as the configured vault root is a different case: root path resolution does not categorically reject it, but this is not a guarantee of complete symlink support across discovery, editing, renames and attachment handling. Internal links and root links should not be treated as interchangeable. If reporting a problem, describe the link's position and target using placeholder paths, plus the relevant non-secret option names; do not paste configuration files, credentials or tokens.
URL model
| What | URL |
|---|---|
| Notes | /dad/recipes/soup — the whole root space |
| Vault files | /dad/assets/broth.jpg — same tree |
| App pages | /_/login, /_/new, /_/search |
| API, health, swagger | /_/api/* |
| Built assets | /_/assets/* |
The only reserved top-level segment is _ — don't name a vault folder that. Everything else is yours.
GLOBNOTES__SERVER_PATHPREFIX is respected for multi-instance deployments: note
pages, files, API and assets live under the prefix; relative links keep working.
Configuration
Shipped defaults, optional partial TOML, then env leaf overrides. Unknown names
and invalid types stop startup before service effects. See the complete commented
defaults/globnotes.toml,
defaults/vault.toml and configuration guide.
| # | Variable | Default | Description |
|---|---|---|---|
| 1 | GLOBNOTES__VAULTS_BASEPATH |
/data |
Base folder; conventional notes at <base>/globnotes |
| 2 | GLOBNOTES_GLOBNOTES_PATH |
conventional path | Explicit existing notes directory |
| 3 | GLOBNOTES__METADATA_PATH |
empty | External metadata base, not the vault directory |
| 4 | GLOBNOTES__SERVER_HOST, GLOBNOTES__SERVER_PORT |
0.0.0.0, 8080 |
Bind address/port |
| 5 | GLOBNOTES__SERVER_PATHPREFIX |
empty | Segment-exact URL prefix |
| 6 | GLOBNOTES__SERVER_ALLOWEDHOSTS |
empty list | Comma-separated hosts, optional ports; other hosts get 421 |
| 7 | GLOBNOTES__INDEX_BATCHSIZE, GLOBNOTES__INDEX_BATCHDELAY, GLOBNOTES__INDEX_SCANCACHETTL |
200, 0.1, 15 |
Batch count, delay and listing-cache seconds |
| 8 | GLOBNOTES__HUB_SCANINTERVAL |
60 |
Periodic reconciliation seconds |
| 9 | GLOBNOTES__PLUGINS_RENDERWORKERS |
2 |
Render workers per vault |
| 10 | GLOBNOTES_GLOBNOTES_PLUGINS_AUTOENABLE |
true baseline |
Explicit TOML/env pins override saved policy; defaults do not |
| 11 | GLOBNOTES_GLOBNOTES_PLUGINS_SETTINGS |
{} |
Addressed plugin JSON, validated by installed schemas |
| 12 | GLOBNOTES__SESSIONS_EXPIRYDAYS |
30 |
Session lifetime days |
| 13 | GLOBNOTES__MCP_ENABLED, GLOBNOTES__MCP_RATELIMIT |
true, 600 |
Endpoint switch and tool calls/minute; 0 disables limiting |
| 14 | GLOBNOTES__LOG_LEVEL |
INFO |
Validated log level; LOGLEVEL is ignored |
| 15 | GLOBNOTES_GLOBNOTES_QUICKACCESS_* |
shipped vault defaults | HIDE, TITLE, TERM, SORT, LIMIT |
| 16 | GLOBNOTES_GLOBNOTES_BRAND_NAME, GLOBNOTES_GLOBNOTES_BRAND_ACCENT |
empty | Per-field branding pins, including explicit empty values |
| 17 | GLOBNOTES_CONFIG |
config/globnotes.toml |
Alternate instance TOML; explicitly missing files fail |
| 18 | PUID, PGID, EXEC_TOOL |
launcher behavior | Retained launcher inputs, never app leaves; notes are not recursively chowned |
Old auth/credential/signing/read-only-settings env inputs are removed without aliases. Setup/access retain their guarded private records during this local transition; instance accounts, Admin permissions, registry and v2 import are separate future pieces. See MIGRATION.md.
Home network deployment
Public setup makes notes readable and writable to everyone on the network.
Read-only setup allows browsing without writes. Keep these modes on trusted
networks; configure GLOBNOTES__SERVER_ALLOWEDHOSTS to prevent DNS rebinding.
The server warns when public/read-only access has no host restriction.
Access settings
Settings → Access updates the existing account in place. Leave the new-password field blank to keep the current password hash. Adding an authenticator first shows its enrolment QR; credentials and sessions remain unchanged until its new code is confirmed. Protected access changes additionally require the current password and current authenticator code when already enabled. A committed password/2FA change invalidates old sessions and requires sign-in with the confirmed credentials. Cancelling enrolment does not reset setup or the account.
The public-access panel's Read-only settings locks access/security, branding, vault plugin policy/settings and operator permissions while retaining public note editing and browser-local theme/keybinding/line-number/debug preferences. It defaults off for initial public setup, on for a saved other-mode → public change, and remains selectable before saving. Existing public deployments without the option retain writable settings. Read-only note access still denies note writes.
Locked public settings cannot unlock themselves through the UI, API or legacy
setup/reset URL. For this transitional local record, recover by editing
read_only_settings in the metadata directory's private config.json and
restarting. Public/read-only modes provide no management-only login. This bridge
is not the final v3 identity or import format.
Agent access
MCP clients (Claude Code, Codex CLI, Gemini CLI, opencode, Cursor, VS Code, Zed, Claude Desktop and others) can search, read and edit the vault through the built-in MCP endpoint: see docs/mcp.md for each client's setup.
With token auth (or no auth at all), your notes are plain HTTP:
# Raw markdown
curl -H "Authorization: Bearer $TOKEN" https://notes.example/_/api/files/dad/recipes/soup.md
# Search (add folder=dad/recipes to scope to a subtree, nested=false for root-only,
# limit=20&offset=40 for one page)
curl -H "Authorization: Bearer $TOKEN" "https://notes.example/_/api/search?term=soup"
# Drop a file into a vault
curl -H "Authorization: Bearer $TOKEN" \
-F "file=@photo.jpg" -F "directory=dad/recipes" \
https://notes.example/_/api/files
Migrating from v2 to v3
v3 is in development on main. It is a major release with breaking changes:
several vaults per instance, accounts with per-vault access, layered configuration
and new environment variable names. v2 stays available (image tag 2) and keeps
receiving fixes. MIGRATION.md describes what changes and the upgrade
steps; it is a draft until v3 is released.
Plugins
Plugins can contribute rendering, server workflows and guards, browser/editor
extensions, commands, settings pages and sandboxed HTTP endpoints. The built-ins
(globnotes-autolinks, -callout, -comments, -embeds, -mark, -mermaid)
provide the Obsidian-flavored rendering; install your own under
<state dir>/plugins/<id>/ (<vault>/.globnotes by default).
Open Settings → Plugins for inventory, enablement, auto-enable and permission review in expandable plugin rows. A plugin's Open settings action and its Plugin settings navigation entry open its declared pages as tabs; Manage in Plugins returns to its expanded row. Vault policy owns server, browser and editor activation across browsers. Pending or postponed access requests also appear under Needs attention at the top of Settings navigation. Those entries open a decision layer over the current page, preserving its tab and drafts without triggering page departure. Legacy browser render preferences may suppress an already vault-enabled renderer for a request; they cannot activate a vault-disabled plugin or stop server workflows. Theme/keybindings remain browser preferences.
Server contributions run in permission-narrowed Deno Workers. Manifests request network data and remote-code import access; effective rights also require the per-plugin Allow network master, operator approval and parent authority. Browser/editor code remains trusted same-origin code, and these server controls do not restrict browser network loads from rendered content. Explicit legacy raw filesystem grants remain a separate trust boundary. See the authoring guide and Plugin API.
Event bus
Components communicate over a mitt-based client-side event bus — publishers announce facts like "note renamed" or "theme changed," consumers decide what to refresh. 59 topics cover note lifecycle, sidebar, menus and modals, edit sessions, themes, plugins, files, search, and the editor action channel (editor:* / app:*). See docs/event-bus.md for the topic registry and usage guide.
Keybindings
Keyboard shortcuts are a switchable layer — Settings → Keybindings shows four named layers (Obsidian, Notion, Typora, VS Code-lite) plus a Custom layer, followed by the active layer's bindings. Obsidian is the default, including when a previously saved layer is no longer available.
- Cross-layer constants:
Ctrl+Alt+N(new note) andCtrl+Alt+H(home) work everywhere — every app's own new-note key is browser-reserved. - Save: all layers use
Mod+SwithCtrl/Cmd+Enterkept as an alias (Modmeans Ctrl on Windows/Linux, Cmd on macOS). - Host commands: Obsidian's
Mod+Pand VS Code-lite'sMod+Shift+Popen the command palette, including registered plugin commands. Notion's slash-menu action remains unimplemented. - Both editors, one channel: keys reach the editors as
editor:*actions on the event bus, so source mode and WYSIWYG handle the same layer — formatting actions that WYSIWYG applies natively are applied in source mode as markdown-syntax edits (Typora-style). The layer also fixes latent keymap conflicts:Mod+Entersaves instead of inserting a blank line,Mod+Itoggles italic, and Escape collapses a multi-cursor selection before exiting. - Custom layer: starts as a copy of the default Obsidian layer; click any binding and press a new key to remap it (modified entries have a Reset action). Overrides are stored per-browser in
localStorage, same as the theme choice.
Branding
Settings -> Branding sets the name, accent and logo/icon. Name and accent
live in vault config.toml; image files live in brand/ beside it. Metadata
relocation uses GLOBNOTES__METADATA_PATH, including the per-vault directory.
- The accent recolors the Globnotes Light/Dark themes; themes with a brand color of their own keep it.
- Save branding applies your choices; Cancel changes discards only Branding drafts and keeps Settings open. Reset branding… asks before clearing the vault's stored branding.
- The brand name replaces "globnotes" in the browser tab, the web manifest, and the navbar wordmark.
- A custom
icon.svgdoubles as the browser-tab favicon; drop dedicated favicon files to go further.
Favicon files are file-drop only — no dialog fields. Drop them into
<state directory>/brand/: <vault>/.globnotes/brand/ by default, or
/state/globnotes/brand/ when GLOBNOTES__METADATA_PATH=/state.
| File | Replaces |
|---|---|
favicon.ico |
the shortcut icon |
favicon-16x16.png / favicon-32x32.png |
tab favicons |
apple-touch-icon.png |
iOS home-screen icon |
safari-pinned-tab.svg |
Safari pinned tab |
site.webmanifest |
the PWA manifest (generated from the brand config when absent) |
GLOBNOTES_GLOBNOTES_BRAND_NAME / GLOBNOTES_GLOBNOTES_BRAND_ACCENT (#rrggbb)
pin individual fields. An unpinned sibling and images remain editable.
Deferred / future work
See FutureDevelopment.md — note transclusion, unresolved-link styling, backlinks/graph, compat hats, and more.
Development
# Install everything (all dependencies resolve from deno.json)
deno install
# Server — tests, lint, type check
deno task test # Server integration and unit tests
deno task lint
deno task check
# Client build & unit tests (via Deno npm compat — no npm/node required)
deno task build:client
deno task test:client
All checks, including the native browser suite, also run in a capped devcontainer; the commit hook and CI use it (testing).
Credit
globnotes is a fork of flatnotes by Adam Dullage, who built the excellent foundation this project stands on. GNU Lesser General Public License v3.0 licensed (see LICENSE); upstream flatnotes code remains under the MIT License (see THIRD-PARTY-NOTICES.md). Full attribution for upstream, dependencies, and the community that shaped the design lives in THIRD-PARTY-NOTICES.md.
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
alexindigo/globnotesRuntime arguments
- Web UI
http://[IP]:[PORT:8080]- Network
bridge- Shell
sh- Privileged
- false
Template configuration
Host path for your notes vault (markdown tree). Unless App data is set below, globnotes also keeps its settings, search index, branding and plugins in a .globnotes folder inside it.
- Target
- /data
- Default
- /mnt/user/appdata/globnotes
- Value
- /mnt/user/appdata/globnotes
Optional. Keeps globnotes' settings, search index, branding and plugins outside your notes, e.g. /mnt/user/appdata/globnotes-state, so Appdata Backup and your notes backup can each cover their own part. Also set App data location to /state. Moving an existing install: stop the container and copy the contents of the .globnotes folder from your notes here first, otherwise the setup wizard starts again. See https://github.com/alexindigo/globnotes#keep-application-state-outside-your-notes
- Target
- /state
Optional. Set to /state when you use App data above; leave empty to keep app data in the .globnotes folder inside your notes.
- Target
- GLOBNOTES_INDEX_PATH
User the app runs as. Unraid default 99 (nobody). Must have write access to the Data path.
- Target
- PUID
- Default
- 99
- Value
- 99
Group the app runs as. Unraid default 100 (users).
- Target
- PGID
- Default
- 100
- Value
- 100
Web UI port.
- Target
- 8080
- Default
- 8080
- Value
- 8080