🌿 LeafWiki

Self-hosted wiki. Single Go binary. SQLite + Markdown stored on disk.

For engineers and self-hosters who want structured, long-lived documentation. No Node.js, no Redis, no Postgres — just a binary and a data directory.

If you've looked at Wiki.js or Outline and thought "this is too much to operate for what I need" — this could fit for you.

→ Try it without installing: demo.leafwiki.com · Ctrl+E edit · Ctrl+S save · resets hourly
→ If it fits, a star helps others find it.
→ Useful to you? Sponsor on GitHub · Buy a coffee on Ko-fi

docker run -p 8080:8080 -v ~/leafwiki-data:/app/data \
  ghcr.io/perber/leafwiki:latest \
  --jwt-secret=yoursecret --admin-password=yourpassword --allow-insecure=true

→ All install options (Docker Compose, Linux installer, binary)

---

Table of Contents

• Features
• Good fit / not a fit
• Install
  • Docker
  • Docker Compose
  • Kubernetes
  • Linux installer
  • Binary
  • Reset admin password
  • Restore a snapshot (offline)
• Operating Modes
• Dev Setup
• Configuration
  • CLI Flags
  • Environment Variables
  • Custom Stylesheet
  • Reverse-Proxy Authentication
  • Unix Socket (v0.11.3)
  • Git Backup
  • Email (SMTP)
  • Security
  • Operations notes
• Keyboard Shortcuts
• External Edits & Resync
• Sorting Pages
• Support this project
• Contributing

---

Features

Operations:

• Single Go binary — no external database, no runtime dependencies
• Markdown on disk — page content is readable outside the app, backup is cp -r (stop the app first)
• Runs on Linux, macOS, Windows, Raspberry Pi (x86_64 and ARM64; 32-bit x86 Linux via standalone binary)
• Reverse-proxy friendly with --base-path
• Reverse-proxy authentication via trusted HTTP header (v0.10+)
• API keys for programmatic and agent access, admin-managed, read-only — in development, not yet ready for use
• Three access modes: fully internal, public read with login-only editing, or open editing without login (see Operating Modes)
• Roles: admin, editor, viewer

Core functionality:

• Tree navigation — explicit hierarchy, not flat note feeds
• Manual page ordering — sort order is explicit, not driven by filename (see Sorting Pages)
• Full-text search across titles and content, with tag-based filtering
• Tags on pages — searchable and filterable across the wiki
• Backlinks and link status per page (incoming, outgoing, broken links), with a dedicated admin view for auditing broken links
• Built-in Markdown editor with live preview, keyboard shortcuts, and autocomplete for internal page links
• Optimistic locking for concurrent edits
• Markdown: tables, task lists, footnotes, callouts (:::info / :::warning), collapsible blocks (:::collapsible / :::collapsed), Mermaid diagrams, KaTeX math blocks ($$...$$, inline $...$ not supported), sanitized inline HTML, embedded PDFs (![name](file.pdf), optionally opened on a specific page with ![name](file.pdf#page=3))

Customization:

• Custom stylesheet (--custom-stylesheet, v0.8.5+)
• Inject HTML/JS into <head> for analytics or custom CSS
• Branding: logo, favicon, site name
• Dark mode and mobile-friendly UI
• Translated UI — ships in English, German, and Spanish; --default-language picks the default. Contributions of other languages are very welcome — see docs/i18n.md

Opt-in via feature flags:

• Revision history (--enable-revision)
• Automatic link rewriting when pages are renamed or moved (--enable-link-refactor)
• Email via SMTP for password reset and user invitations (--smtp-host, v0.13.0)
• Git backup — push wiki content to a remote Git repository via SSH or HTTP(S) (--git-backup, v0.11.3, experimental)

Markdown import:

• ZIP-based importer for editors and admins
• Supports Obsidian-style wiki link rewriting on import
• Best results with a reasonably clean folder structure; not a fully automatic converter for all source formats

Mobile:

---

Good fit / not a fit

Good fit:

• Personal wikis, engineering notebooks, and runbooks
• Internal team or homelab documentation
• Existing Markdown or Obsidian vaults that need a structured wiki UI
• Small teams that want tree navigation over flat note feeds
• Self-hosted environments with low operational overhead

Probably not a fit:

• Organizations needing complex enterprise permissions or approval workflows
• Real-time collaborative editing
• Teams looking for a Confluence or Notion replacement

LeafWiki is intentionally narrower than those systems. That focus is part of the value.

---

Prefer not to run your own server? Free hosted beta — 10 spots, starting September 2026. Get a beta spot → and help shape the hosted version.

---

Install

Docker

docker run -p 8080:8080 \
    -v ~/leafwiki-data:/app/data \
    ghcr.io/perber/leafwiki:latest \
    --jwt-secret=yoursecret \
    --admin-password=yourpassword \
    --allow-insecure=true

--allow-insecure=true is required for plain HTTP. Omit it when serving over HTTPS (make sure your reverse proxy forwards X-Forwarded-Proto: https).

Non-root:

docker run -p 8080:8080 \
    -u 1000:1000 \
    -v ~/leafwiki-data:/app/data \
    ghcr.io/perber/leafwiki:latest \
    --jwt-secret=yoursecret \
    --admin-password=yourpassword \
    --allow-insecure=true

The data directory must be writable by the specified user.

Docker Compose

services:
  leafwiki:
    image: ghcr.io/perber/leafwiki:latest
    container_name: leafwiki
    user: 1000:1000
    ports:
      - "8080:8080"
    environment:
      - LEAFWIKI_JWT_SECRET=yourSecret
      - LEAFWIKI_ADMIN_PASSWORD=yourPassword
      - LEAFWIKI_ALLOW_INSECURE=true  # Required for plain HTTP. Omit for HTTPS (ensure `X-Forwarded-Proto: https` is forwarded).
    volumes:
      - ${HOME}/leafwiki-data:/app/data
    restart: unless-stopped

Kubernetes

See docs/install/kubernetes.md for a Deployment + PersistentVolumeClaim + Service + Ingress example (Gateway API alternative included).

Linux installer

sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/perber/leafwiki/main/install.sh)"

Installs LeafWiki as a system service. Tested on Ubuntu, Debian, and Raspbian.

Update:

sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/perber/leafwiki/main/update.sh)"

Only works if you installed with the script above. Not compatible with Docker or binary installs.

Non-interactive mode:

cp .env.example .env
# Edit .env with your configuration
sudo ./install.sh --non-interactive --env-file ./.env

Security: in interactive mode, environment variables are written in plain text to /etc/leafwiki/.env. Restrict access to that file.

Deployment examples:

• Install with nginx on Ubuntu
• Install on a Raspberry Pi

Binary

Download leafwiki-<version>-<os>-<arch> and its .sha256 file from GitHub Releases (linux-amd64, linux-arm64, linux-386, darwin-amd64, darwin-arm64, windows-amd64), check that the hash matches the one in the .sha256 file, and rename it to leafwiki:

sha256sum leafwiki-<version>-<os>-<arch>
cat leafwiki-<version>-<os>-<arch>.sha256
mv leafwiki-<version>-<os>-<arch> leafwiki
chmod +x leafwiki
./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --allow-insecure=true

The server binds to 127.0.0.1:8080 by default. To expose it on the network:

./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --host=0.0.0.0 --allow-insecure=true

Default data directory is ./data. Change with --data-dir.

32-bit x86 Linux (i686, e.g. Alpine on an Intel Atom) is supported on a best-effort basis: use the linux-386 binary. It is built without CGO, so it doesn't need glibc and runs on musl-based distros. The systemd installer and Docker images only cover amd64/arm64, so the binary is the only install path on 32-bit x86 (that includes update.sh, which expects the systemd setup).

Build from source

Requires Go and Node.js. make build compiles the UI, embeds it, and produces a self-contained leafwiki binary (same as release/Docker builds). Use HTTP (http://localhost:8080/), not HTTPS, unless you terminate TLS in front of LeafWiki.

git clone https://github.com/perber/leafwiki.git
cd leafwiki
git switch --detach v0.13.0   # or any tag / main
make build
./leafwiki --disable-auth --host=127.0.0.1 --data-dir ./data --allow-insecure=true

For API-only local development with Vite, use make build-api (or make run) instead — see Dev Setup.

Reset admin password

./leafwiki reset-admin-password

Restore a snapshot (offline)

For disaster recovery or migrating to a fresh instance, restore a snapshot ZIP into the data directory while the server is stopped:

./leafwiki --data-dir ./data restore-snapshot ./data/snapshots/leafwiki-snapshot-2026-01-01.zip

When --snapshot is enabled, a live restore is also available from the admin UI (Settings → Full Backup). Use this offline command when the server can't start or you're seeding a new data directory. The --snapshot* flags are in CLI Flags.

---

Operating Modes

LeafWiki supports three access modes. Pick the one that matches your environment:

1. Internal wiki — login required (default)

All access requires authentication. Nobody can read or edit without a valid account. This is the default behavior when no access flags are set.

./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword

Use this for team-internal wikis or homelab setups where content should stay private.

2. Public read, login required for editing

Anyone can browse the wiki without logging in. Only authenticated users with an editor or admin role can make changes.

./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --public-access=true

Use this for open documentation or project wikis where readers don't need accounts, but you still want to control who can edit.

3. No login — everyone can read and edit (--disable-auth)

Authentication is completely disabled. Anyone who can reach the server can read and edit all pages.

./leafwiki --disable-auth --host=127.0.0.1

⚠️ Only use this on trusted internal networks or local setups. Never expose a --disable-auth instance to the public internet.

---

Dev Setup

Stack: Go · React (Vite) · SQLite

git clone https://github.com/perber/leafwiki.git
cd leafwiki

Terminal 1 — Frontend:

cd ui/leafwiki-ui
npm install
npm run dev

Terminal 2 — Backend:

cd cmd/leafwiki
go run . --jwt-secret=yoursecret --allow-insecure=true --admin-password=yourpassword

Vite starts on http://localhost:5173. The backend binds to 127.0.0.1 by default.

See CONTRIBUTING.md for contribution guidelines.

---

Configuration

Required

Optional admin identity

For plain HTTP: add --allow-insecure=true so login and CSRF cookies work.

CLI Flags

Docker image default: LEAFWIKI_HOST is set to 0.0.0.0 automatically by the container entrypoint if neither --host nor LEAFWIKI_HOST is provided.

Environment Variables

Custom Stylesheet

Place a .css file inside your data directory and pass its path:

./leafwiki \
  --data-dir=./data \
  --custom-stylesheet=custom.css \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword

• File must exist at ./data/custom.css
• Served as /custom.css (or ${base-path}/custom.css with --base-path)
• The endpoint is publicly accessible

Reverse-Proxy Authentication

Available since v0.10.0. Use when an upstream proxy authenticates users and forwards the username or email via HTTP header.

./leafwiki \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword \
  --enable-http-remote-user=true \
  --http-remote-user-header-name=X-Forwarded-User \
  --trusted-proxy-ips=127.0.0.1,172.18.0.0/16 \
  --login-url=https://auth.example.com/login \
  --logout-url=https://auth.example.com/logout

• Only trusts the header from IPs listed in --trusted-proxy-ips
• If the forwarded username or email doesn't match a LeafWiki user, the request is rejected — unless --enable-http-remote-user-auto-create is set (see below)
• Do not enable without configuring --trusted-proxy-ips
• --login-url and --logout-url are independent, optional redirect targets — set either or both to send users to an external IdP instead of the built-in login form / to redirect after logout
• --login-url, --logout-url, and --user-management-url must all start with http:// or https://; the server refuses to start otherwise (relative paths are not accepted for any of them)
• ⚠️ --login-url takes effect regardless of --enable-http-remote-user and has no in-app bypass: once set, every unauthenticated visit (including /login itself) redirects to it immediately. Double-check the URL before setting it — a wrong or unreachable value locks all users, including admins, out of the built-in login form
• --http-remote-user-logout-url (v0.10.0) is deprecated; use --logout-url instead. It still works as a fallback when --logout-url/LEAFWIKI_LOGOUT_URL isn't set, but a deprecation warning is logged

Auto-creating users (v0.12.1)

By default, a proxy-asserted identity with no matching LeafWiki account is rejected (401). Set --enable-http-remote-user-auto-create=true to provision one automatically instead:

./leafwiki \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword \
  --enable-http-remote-user=true \
  --http-remote-user-header-name=X-Forwarded-User \
  --trusted-proxy-ips=127.0.0.1,172.18.0.0/16 \
  --enable-http-remote-user-auto-create=true \
  --http-remote-user-email-header-name=X-Forwarded-Email \
  --http-remote-user-default-role=viewer

• Requires --enable-http-remote-user to also be set; the server refuses to start otherwise
• The value in --http-remote-user-header-name becomes the new account's username verbatim, even if it looks like an email address — if your proxy sends an email in that header and you want a distinct, readable username, point --http-remote-user-email-header-name at a separate proxy header
• If --http-remote-user-email-header-name isn't set or the header is empty, a non-deliverable placeholder email (<username>@remote-user.invalid) is used instead
• Auto-created accounts get a random password nobody is told — they can only ever authenticate via the trusted proxy, not the built-in login form
• --http-remote-user-default-role must not be admin — the server refuses to start otherwise. A forged or misrouted header must not be able to mint an admin account by itself; promote an auto-created user to admin manually if needed

Unix Socket (v0.11.3)

Use --unix-socket when LeafWiki should listen on a local unix domain socket instead of TCP.

./leafwiki \
  --unix-socket=/run/leafwiki/leafwiki.sock \
  --data-dir=./data \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword

• --unix-socket overrides --host and --port
• LeafWiki still serves normal HTTP; a reverse proxy such as Nginx or Caddy connects to the socket
• If a stale socket file exists from a previous run, LeafWiki removes it before listening
• New socket files are created with permissions 0660
• On Windows, unix sockets are not supported and LeafWiki returns a startup error if this option is used

Git Backup (v0.11.3, experimental)

Experimental — This feature is new and may change in future releases. Test it thoroughly before relying on it for critical data.

Git Backup pushes wiki content to a remote Git repository on a configurable interval, via SSH or HTTP(S). Only the root/ (pages) and assets/ directories are committed, so database files (.db, .db-wal, etc.) and other runtime files are never included; .gitignore rules are still honoured. By default the content is committed at the repository top level — set --git-backup-path to nest it under a directory (useful for a monorepo).

Backups run automatically on a configurable interval and can also be triggered manually from the Git Content Backup page.

CLI flags (v0.11.3+):

Environment variables:

Example — SSH (Docker Compose):

environment:
  - LEAFWIKI_GIT_BACKUP=true
  - LEAFWIKI_GIT_BACKUP_REMOTE=git@github.com:youruser/yourwiki-backup.git
  - LEAFWIKI_GIT_BACKUP_BRANCH=main
  - LEAFWIKI_GIT_BACKUP_SSH_KEY=${LEAFWIKI_GIT_BACKUP_SSH_KEY}  # from .env file
  - LEAFWIKI_GIT_BACKUP_INTERVAL=60m

Example — HTTPS with an access token (Docker Compose, v0.13.0+):

environment:
  - LEAFWIKI_GIT_BACKUP=true
  - LEAFWIKI_GIT_BACKUP_REMOTE=https://github.com/youruser/yourwiki-backup.git
  - LEAFWIKI_GIT_BACKUP_BRANCH=main
  - LEAFWIKI_GIT_BACKUP_HTTP_USERNAME=youruser
  - LEAFWIKI_GIT_BACKUP_HTTP_PASSWORD=${LEAFWIKI_GIT_BACKUP_HTTP_PASSWORD}  # from .env file
  - LEAFWIKI_GIT_BACKUP_INTERVAL=60m

On GitHub, create a fine-grained personal access token limited to the backup repository with Contents: Read and write permission, and use it as the password. The username can be your GitHub username.

Notes:

• --git-backup-remote is required when pushing to a remote. It must be an SSH URL (git@... or ssh://...) or an HTTP(S) URL (https://..., http://...). Leave it unset for local-only backups.
• For SSH remotes, either --git-backup-ssh-key or --git-backup-ssh-key-path is required. Prefer the environment variable to avoid the key appearing in process listings.
• For HTTP(S) remotes, both --git-backup-http-username and --git-backup-http-password are required. Prefer LEAFWIKI_GIT_BACKUP_HTTP_PASSWORD over the flag — LeafWiki warns at startup when the password is passed as a flag, since flags are visible in process listings. Credentials embedded directly in the remote URL (https://user:token@host/repo.git) also work and are masked in logs and in the UI.
• Prefer https:// over http://: with plain http:// the credentials and your wiki content travel unencrypted, and LeafWiki logs a warning at startup.
• --git-backup-ssh-known-hosts is optional but recommended for SSH remotes. If not set, LeafWiki falls back to ~/.ssh/known_hosts. If that file does not exist either (common in containers), SSH host key verification is disabled — leaving connections open to MITM attacks. Set this flag explicitly in production. It has no effect on HTTP(S) remotes, which are verified via TLS.
• If the remote diverges (e.g. someone pushed directly to the backup branch), LeafWiki will stop auto-pushing and show a Conflict — remote diverged warning in the UI. Click Force Push in the UI to overwrite the remote with the current local backup history. Your wiki content is never lost — the local backup repo is always authoritative.
• This backs up content only — the SQLite database is not included. For a full backup, use your data directory (cp -r with the app stopped).
• When LeafWiki first connects to a remote that already contains a backup, it syncs that content into the local data directory before the wiki loads its pages (local files always win — nothing is overwritten). A new instance therefore picks up the backed-up pages instead of overwriting the remote with an empty wiki, and it does not seed its default welcome page when the backup already has content. After that first sync, backups behave normally, including committing deletions.
• --git-backup-path (e.g. docs) commits root/ and assets/ under that directory instead of the top level — docs produces docs/root/ and docs/assets/ — and pulls external edits back from there. This is handy when the backup remote is a monorepo: files outside the configured directory are left untouched. LeafWiki's live content still lives in <data-dir>/root and <data-dir>/assets; nothing is copied into the repository working tree. Leave it empty to keep the historical top-level layout.

---

Email (SMTP)

Available since v0.13.0. Configure an SMTP server to enable the forgot-password flow and email-based user invitations. Without --smtp-host, both features stay off and the login form shows no password-reset link.

./leafwiki \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword \
  --smtp-host=smtp.example.com \
  --smtp-port=587 \
  --smtp-security=starttls \
  --smtp-username=leafwiki@example.com \
  --smtp-password=yourpassword \
  --smtp-from=leafwiki@example.com \
  --public-url=https://wiki.example.com

• --smtp-from and --public-url are required once --smtp-host is set — the server refuses to start otherwise
• --public-url must be an absolute http(s):// URL; it is the base for links in outgoing email
• --smtp-security is one of none, starttls (default), or tls
• Prefer LEAFWIKI_SMTP_PASSWORD over the flag to keep the password out of process listings
• --smtp-insecure-skip-verify disables TLS certificate verification — for testing only

---

Security

Enabled by default since v0.7.0:

• Secure, HttpOnly cookies for session handling
• CSRF protection on all state-changing requests
• Rate limiting on auth endpoints
• Role-based access: admin, editor, viewer

--disable-auth removes all authentication. Only use for local development, trusted internal networks, or isolated environments.

# Safe local-only example:
./leafwiki --disable-auth --host=127.0.0.1

For most setups, prefer --public-access for read-only public access and the viewer role for restricted accounts.

Operations notes

• Default bind: 127.0.0.1 (binary) / 0.0.0.0 (Docker image)
• Default data dir: ./data (binary) / /app/data (container)
• Defaults are intentionally conservative — a fresh install does not become network-exposed by accident

---

Keyboard Shortcuts

Ctrl+V / Cmd+V for pasting images and files works in the editor.
Esc closes modals, dialogs, and edit mode.

Press Ctrl+/ / Cmd+/ in the app for the full in-product shortcuts list.

---

Relative Markdown Links

LeafWiki resolves relative page links with page-as-folder semantics: the current page path is treated as a folder, so [Setup](setup) on /docs/guide resolves to /docs/guide/setup, not a sibling /docs/setup.

A trailing .md suffix in a link target is ignored for page lookup (for example setup.md → setup), which matches common filesystem / Obsidian-style Markdown.

External Edits & Resync

LeafWiki is intended to be the primary writer for a workspace. However, Markdown files may still be changed outside LeafWiki — for example through a text editor, Git, a script, or a bulk import.

LeafWiki does not continuously watch the filesystem for these changes. To make externally modified files visible to LeafWiki, trigger a resync in one of two ways:

• Admin UI: click the Refresh button in the page-tree toolbar (admins only). It runs a resync with live progress across four phases (tree, links, tags, search); if HTTP Git Backup is configured, it first pulls the latest commits from the remote. Non-admin users see the same button, but for them it only re-fetches the current page tree.
• OS signal: send SIGUSR1 or SIGHUP to the running process — no restart required. This can be useful when an external workflow needs to explicitly tell LeafWiki that files have changed.

Both paths run the same resync job and produce the same result. A resync should be considered an explicit reconciliation of the workspace rather than continuous bidirectional filesystem synchronization.

Changes to .leafwikiignore are separate and are only read at startup.

New files without a leafwiki_id: LeafWiki stores the identity of a page in the leafwiki_id field in its frontmatter rather than deriving it from the filename or path. This allows LeafWiki to retain the identity of a document when it is renamed or moved.

If a Markdown file created outside LeafWiki does not yet contain a leafwiki_id, the next resync generates one and writes it back to the file. No manual action is required, but the file will therefore change on disk during the resync.

If root/ is managed by a separate Git workflow outside LeafWiki's built-in Git Backup, this generated ID will appear as an additional diff.

---

Sorting Pages

Page order in LeafWiki is explicit and manual — it does not follow filename or alphabetical order automatically. By default, pages appear in the order they were created.

LeafWiki is not a file browser. The tree reflects the structure you define, and the order you set is the order your readers see.

To reorder the pages inside a section or under a parent page:

1. Hover over the section or page in the sidebar tree to reveal the action buttons
2. Click the ⋮ (more actions) button
3. Select Sort Section Children or Sort Page Children

The sort dialog lets you drag items into position, use the ↑ ↓ arrow buttons, or jump to alphabetical order with A → Z / Z → A. Click Save to apply.

Sorting is per level — the order of a section's direct children is independent of deeper nested items.

---

Support this project

If it's useful to you:

• ⭐ Star the repo — helps others find it
• 💛 Sponsor on GitHub — supports ongoing maintenance, bug fixes, and new features
• ☕ Buy a coffee on Ko-fi — a one-time thank-you
• 🚀 Don't want to self-host? LeafWiki Hosted — managed LeafWiki, your content stays plain Markdown

Need help deploying LeafWiki for your team? Business support & setup →

---

Contributing

Contributions, discussions, and feedback are welcome.
Open an issue or start a discussion on GitHub. Follow the repository to get notified about new releases.

Translations: the UI currently ships in English, German, Spanish, French, and Simplified Chinese. Adding another language is a self-contained contribution — docs/i18n.md walks through it.