BananaWiki

BananaWiki is a self-hosted wiki application built with Flask 3.1 and SQLite. It is designed for private teams and individuals who want a fully featured knowledge base with strong editing tools, granular permissions, built-in collaboration, and simple operations — one Python app, one SQLite database, no external services required.

Screenshots

Setup	Wiki home

Editor	Admin settings

Features

Writing and content management

• Markdown editor with live preview, formatting toolbar, image upload modal, and internal-link picker
• Page attachments served through authenticated routes
• Full page history with edit summaries, snapshot viewing, and revert
• Difficulty tags, URL slug rename, and deindexing — pages can be accessible but hidden from navigation and search
• Sequential navigation for categories that should read like chapters
• Draft autosave with conflict detection

Organisation and navigation

• Hierarchical category tree with drag-to-reorder
• Kanban boards with columns, tickets, comments, attachments, and description history
• Custom pages at arbitrary URLs — 19 content types including Markdown, HTML, redirects, file downloads, and video embeds

Collaboration and community

• User profiles with avatars, bios, and contribution heatmaps
• Direct messages and moderated group chats with attachment support
• Badge system with notifications and auto-award triggers
• Site-wide announcements and people sidebar widget

Admin and governance

• Four-tier roles: user, editor, admin, protected_admin
• Fine-grained per-user permission overrides and category-specific access restrictions
• Page reservations (checkout system) with admin override — force-release, reassign, and clear cooldowns
• Lockdown mode, one-session-per-user enforcement, invite code management, and audit history
• Temporary pages, user accounts, and role grants with automatic expiry
• Beta tester programme with invitation and acceptance flow
• Full-site export/import (ZIP) with three conflict modes: delete all, override, keep existing
• Telegram backup sync — all settings including split threshold, compression, and chat attachment inclusion managed from Admin → Settings

Extensibility

• Plugin system with first-party and external plugins — enable/disable without a server restart
• bananawiki_sdk package for third-party plugin authors with stable hooks, template slots, and DB helpers
• 19 built-in optional plugins: badges, chat, groups, Kanban, page history, announcements, drafts, attachments, user profiles, page reservations, Telegram sync, chat cleanup, audit, easter egg, user data export, difficulty tags, beta testers, temporary items, and custom pages
• Plugin Development Kit — download a complete SDK package from Admin → Plugins with documentation, examples, starter template, and everything needed to build custom plugins without access to BananaWiki source code

Quick start

Requirements

• Python 3.9+
• A POSIX-like shell for the helper scripts (dev.sh, start.sh, install.sh, update.sh)
• For production: Debian/Ubuntu with sudo, optional nginx, optional Let's Encrypt

Local development

git clone https://github.com/OVTDAcc/BananaWiki.git
cd BananaWiki
make dev

make dev creates a virtualenv, installs dependencies, and starts the Flask development server at http://127.0.0.1:5001.

Run the test suite

make test

Production start

python3 -m venv venv
. venv/bin/activate
pip install -r requirements.txt
./start.sh

Fully automated production install

sudo ./install.sh

Non-interactive form:

sudo ./install.sh --non-interactive --domain wiki.example.com

First-run flow

1. Start the app.
2. Visit the site in a browser — BananaWiki redirects to /setup.
3. Create the first administrator account.
4. Sign in and configure the wiki from Admin → Site Settings.

Configuration

Static settings live in config.py — bind host/port, database path, upload limits, logging, and feature flags. See docs/configuration.md for a complete reference.

Runtime settings are managed from Admin → Site Settings:

• Theme colours and light/dark palette defaults
• Favicon selection or custom upload
• Lockdown mode and session limit
• Telegram sync (enabled, bot token, user IDs, split threshold, compression, chat attachments)
• Chat enablement, quotas, and cleanup schedule
• Page reservation enablement, timing, and admin overrides

Repository layout

BananaWiki/
├── app.py                 Flask application entry point and middleware
├── config.py              Static configuration (paths, limits, defaults)
├── sync.py                Telegram backup module
├── wiki_logger.py         Structured request and action logging
├── plugin_loader.py       External plugin loading and lifecycle
├── reset_password.py      CLI password reset tool
├── setup.py               Server-level provisioning wizard
├── gunicorn.conf.py       Gunicorn worker and bind settings
├── db/                    Database access layer (SQLite, WAL mode)
├── helpers/               Authentication, markdown, validation, permissions, time
├── routes/                Feature-area route handlers
├── bananawiki_sdk/        Public plugin SDK
├── plugins/               Built-in and external plugin directories
├── scripts/               CLI scripts (seed badges, generate license, Obsidian sync)
├── app/templates/         Jinja2 templates
├── app/static/            CSS, JavaScript, favicons, runtime uploads
├── tests/                 Pytest suite (2400+ tests)
├── docs/                  User and operator documentation
├── dev.sh                 Local development launcher
├── start.sh               Gunicorn startup wrapper
├── install.sh             Automated production installer
└── update.sh              Backup-aware updater

Documentation

Guide	Description
Getting Started	Installation, first run, and initial configuration
Configuration	Full config.py reference
Operations	Deployment, updates, backups, and troubleshooting
Architecture & Security	Application structure and security model
Permissions	Role system and fine-grained permission overrides
JSON API Reference	All /api/ endpoints with payloads and responses
Kanban	Kanban boards, columns, tickets, and sharing
Custom Pages	Admin-defined pages with 19 content types
Badges	Badge types, auto-triggers, and admin management
Beta Testers	Beta tester programme and invitation flow
Temporary Items	Time-limited pages, accounts, and role grants
License	License file generation and registration
Banana Mode API	Hidden bearer-token API for banana mode
Obsidian Sync	Experimental Obsidian vault pull/push
Plugin Overview	Plugin system architecture and built-in plugins
Plugin Authoring	Step-by-step guide to building plugins
Plugin API Reference	Complete bananawiki_sdk reference

Troubleshooting

The app keeps redirecting to /setup — First-run provisioning has not completed. Create the initial admin account in the browser.

Login sessions do not persist behind a reverse proxy — Check PROXY_MODE in config.py. When enabled, BananaWiki trusts forwarded headers and marks cookies secure.

Chat or sync settings do not match config.py — Those settings are managed from Admin → Site Settings, not from config.py.

I need a production-safe update path — Use sudo ./update.sh. It creates backups, pulls changes, refreshes dependencies, restarts the service, and verifies the deployment.

Contributing

1. Create or activate the local virtual environment with make dev or python3 -m venv venv && . venv/bin/activate.
2. Run make test before and after your change.
3. Keep SQL in db/, route handlers in routes/, and pure helpers in helpers/.
4. Preserve the security model: CSRF tokens on all mutations, sanitized Markdown output via Bleach, parameterized SQL, and authenticated attachment downloads.
5. New features should include tests in tests/ following the patterns in existing test files.