DOCSEARCHbyAlgolia
Submit Docs

LeafWiki Documentation

repository·main·Indexed 21 days ago

https://github.com/perber/leafwiki

A self-hosted, lightweight wiki system for engineers and small teams. Distributed as a single Go binary, LeafWiki uses SQLite and stores Markdown files directly on disk. It features three access modes (Internal, Public read, and Unauthenticated), support for Docker and Linux installations, and a built-in load test CI suite.

Tokens
14.6K
Snippets
32
Records
48
Agent score
71%

What's inside LeafWiki

  1. Markdown plugin features

    main

    LeafWiki supports several markdown-it syntax plugins for extended functionality:

    • Emojis: Use :emoji_name: (e.g., :wink:) or emoticons (e.g., :-)) to render icons.
    • Subscript/Superscript: Use ^text^ for subscript and ~text~ for superscript.
    • Inserted/Marked Text: Use ++text++ for <ins> and ==text== for <mark>.
    • Footnotes: Use [^id] for references and [^id]: definition for the footnote content. Inline footnotes use ^[text].
    • Definition Lists: Use Term : Definition for standard style, or `Term

    ~ Definition` for compact style.

    • Abbreviations: Define abbreviations using *[HTML]: Hyper Text Markup Language.
    • Custom Containers: Use ::: type syntax (e.g., ::: warning) to create custom content blocks.
    Footnote 1 link[^first].

[^first]: Footnote **can have markup**

::: warning
*here be dragons*
:::

  2. Understand LeafWiki Operating Modes

    main

    LeafWiki offers three distinct access modes to suit different security requirements:

    1. Internal wiki (Default): Requires authentication for both reading and editing. Use this for private team documentation.
    2. Public read, login required for editing: Anyone can browse the wiki, but only authenticated users with an editor or admin role can make changes. Use this for open documentation.
    3. No login (Unauthenticated): Authentication is completely disabled. Anyone can read and edit. Warning: Never expose this mode to the public internet; use it only on trusted internal networks.
    # Mode 1: Internal (Default)
./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword

# Mode 2: Public Read
./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --public-access=true

# Mode 3: No Login (Unsafe for public internet)
./leafwiki --disable-auth --host=127.0.0.1

  3. How Git Backup works (Experimental)

    main

    The Git Backup feature (experimental) pushes wiki content (the root/ pages and assets/ directories) to a remote Git repository via SSH on a configurable interval.

    Important Notes:

    • Content Only: This does not back up the SQLite database. For a full backup, use a filesystem-level copy of the data directory.
    • Authoritative Local: If the remote repository diverges (e.g., someone pushed directly to the backup branch), LeafWiki will show a Conflict — remote diverged warning. You can resolve this by clicking Force Push in the UI to make the local wiki the source of truth.
    • Security: It is highly recommended to set --git-backup-ssh-known-hosts to a path containing your known_hosts file. If not set, LeafWiki may fall back to ~/.ssh/known_hosts, or if that is missing (common in containers), it will disable SSH host key verification, leaving you vulnerable to MITM attacks.
    • SSH Key: Prefer using the --git-backup-ssh-key environment variable over the CLI flag to prevent the private key from appearing in process listings.
    # Example Docker Compose configuration
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

  4. Install LeafWiki via Docker

    main

    You can run LeafWiki as a Docker container. By default, it uses a single Go binary with SQLite and Markdown stored on disk.

    To run with plain HTTP, you must include the --allow-insecure=true flag. If you are serving over HTTPS via a reverse proxy, omit this flag and ensure your proxy forwards the X-Forwarded-Proto: https header.

    To run as a non-root user, specify the user ID with -u and ensure the mounted data directory is writable by that user.

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

# Non-root run
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

  5. Configure Reverse-Proxy Authentication

    main

    Use this configuration when an upstream proxy (like Nginx or Caddy) handles authentication and forwards the user's identity via an HTTP header.

    Setup Steps:

    1. Enable remote user auth with --enable-http-remote-user=true.
    2. Specify the header name used by your proxy with --http-remote-user-header-name (default is Remote-User).
    3. Crucial: Define --trusted-proxy-ips with the IP or CIDR of your proxy to prevent header spoofing.
    4. (Optional) Set --login-url and --logout-url to redirect users to an external Identity Provider (IdP).

    Warnings:

    • --login-url takes effect immediately for all unauthenticated visits. If set incorrectly, you will be locked out of the built-in login form.
    • --login-url, --logout-url, and --user-management-url must use absolute http:// or https:// URLs.
    • --http-remote-user-logout-url is deprecated; use --logout-url 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 \
  --login-url=https://auth.example.com/login \
  --logout-url=https://auth.example.com/logout

  6. Disable authentication for local development

    main

    If you are running LeafWiki in a local-only, trusted, or isolated environment and want to bypass all login requirements, use the --disable-auth flag.

    Warning: This removes all security. Do not use this in any network-exposed environment.

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

  7. Run the LeafWiki load test CI suite

    main

    The load test is a self-contained smoke check designed for CI regression testing. It builds a throwaway instance, seeds it with 500 pages, runs a curated set of scenarios, and exits with a non-zero status if errors occur or if performance regresses beyond a specific threshold compared to the checked-in baseline.

    Warning: Never point this at a real or production data directory.

    Results (including report.md and report.json) are saved to loadtest/results/ci/<timestamp>/.

    ./loadtest/ci-suite.sh

  8. Update the load test baseline

    main

    Use this command after making intentional performance changes or when establishing a new baseline on a different machine. This updates the reference performance metrics used to detect regressions.

    ./loadtest/ci-suite.sh --update-baseline

  9. Install LeafWiki as a Binary

    main

    You can run the LeafWiki binary directly. By default, the server binds to 127.0.0.1:8080 and uses ./data as the data directory.

    To expose the server to the network, use the --host=0.0.0.0 flag. You can also specify a custom data directory using --data-dir.

    # Basic execution
chmod +x leafwiki
./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --allow-insecure=true

# Expose to network and custom data dir
./leafwiki --jwt-secret=yoursecret --admin-password=yourpassword --host=0.0.0.0 --allow-insecure=true --data-dir=/path/to/data

  10. Set up LeafWiki for development

    main

    LeafWiki uses a Go backend and a React (Vite) frontend. To run the development environment, you need to run both the frontend and backend in separate terminals.

    Frontend: Runs on http://localhost:5173. Backend: Binds to 127.0.0.1 by default.

    # Clone the repo
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

  11. Install Leafwiki on a Raspberry Pi

    main

    To install Leafwiki on a Raspberry Pi, use the quick install script. This command downloads the installer, makes it executable, and runs it with the --arch arm64 flag to ensure compatibility with the Raspberry Pi architecture.

    Once the installation is complete, the Leafwiki service is accessible locally at http://localhost:8080/.

    curl -sL https://raw.githubusercontent.com/perber/leafwiki/main/install.sh -o install.sh && chmod +x ./install.sh && sudo ./install.sh --arch arm64

  12. Markdown syntax supported by LeafWiki

    main

    LeafWiki uses markdown-it for processing content. The following Markdown features are supported:

    Headings

    Use # for headings, ranging from h1 to h6.

    Emphasis and Text Styling

    • Bold: **text** or __text__
    • Italic: *text* or _text_
    • Strikethrough: ~~text~~
    • Typographic replacements: When the typographer option is enabled, symbols like (c), (r), (tm), and smart quotes are automatically converted.

    Lists

    • Unordered: Start lines with +, -, or *. Indent by 2 spaces for sub-lists.
    • Ordered: Use numbers (e.g., 1., 2.). You can use sequential numbers or keep all items as 1. for automatic numbering. You can also start with an offset (e.g., 57.).

    Code

    • Inline code: Use backticks like `code`.
    • Indented code: Indent lines with 4 spaces.
    • Code fences: Use triple backticks () for blocks. Syntax highlighting is supported by adding a language identifier (e.g., js).

    Tables

    Use pipes | and hyphens - to create tables. Alignment can be controlled using colons in the separator row (:--- for left, ---: for right, :---: for center).

    Links and Images

    • Links: [text](url) or [text](url "title"). Autoconverted links require the linkify option.
    • Images: ![alt text](url "title"). Supports reference-style images using [id] in the body and [id]: url at the bottom of the document.
    # h1 Heading

## h2 Heading

**Bold text**

*Italic text*

```js
var foo = function (bar) {
  return bar++;
};
    OptionDescription
    datapath to data files

    link text