Most wiki software wants to be everything. It wants a plugin marketplace, an app framework, a real-time collaborative canvas, a database, a CMS, a project tracker — and before you know it the thing you installed to write down how the deployments work has become a second full-time job to maintain. BookStack is the opposite. It is a self-hosted documentation and knowledge-base platform that is, by its own explicit admission, "not designed as an extensible platform." That refusal is the entire point, and it is why a 19,000-star PHP wiki has stayed boring, fast, and free for over a decade.
BookStack is MIT-licensed, written in PHP on top of the Laravel framework, and stores everything in MySQL or MariaDB. It organizes content into a rigid four-level hierarchy — shelves hold books, books hold chapters, chapters hold pages — and it gives you a WYSIWYG editor out of the box with no Markdown gatekeeping. There is no paid tier, no enterprise SKU, no feature paywall: every capability the project ships, from role-based permissions to SAML to the REST API to audit logs, is included for free. If you have been looking at Notion's per-seat pricing or Confluence's sprawl and wanted something you actually own, BookStack is one of the cleanest answers on the open-source shelf.
This is a long, honest teardown of what BookStack actually is in 2026, how its hierarchy shapes (and limits) the way you can model knowledge, what changed when the project moved its canonical repository to Codeberg, the real operational cost of running it, the bus-factor risk that comes with a one-person core team, and precisely where your documentation lands and who can read it.
1. What BookStack Actually Is
BookStack is a self-hosted wiki and documentation platform. Its job is narrow and well-defined: organize written knowledge so a team or family or community can find it again. It is not a note-taking app for personal thinking (no infinite canvas, no bidirectional links), and it is not a website builder (no theming engine beyond what the admin panel exposes). It is a structured, hierarchical documentation system that feels closer to a well-run library than to a whiteboard.
The project was first released in July 2015 by UK developer Dan Brown, originally under the name "Oxbow" before being renamed eleven days later. It exited beta with version 21.04 in April 2021 and has been on a calendar-versioning schedule ever since, with security releases shipping monthly. In 2026 the current stable line is the v26.x series (for example v26.05.5, a security-focused patch). On a normal self-hosted VPS it runs happily on very modest hardware — the project's own docs suggest a small container or a cheap VPS is enough, and community reports put a functional instance on machines costing a few dollars a month.
The headline that matters most for this series: BookStack is fully free and open, MIT-licensed, with the source available on Codeberg and a GitHub mirror. There is no cost to download and install your own instance. There is no premium tier hiding LDAP or SAML or the API behind a paywall. The project sustains itself through community donations and GitHub Sponsors, not through feature gating.
2. The Hierarchy: Shelves, Books, Chapters, Pages
The single most important thing to understand about BookStack is its content model. Everything is organized into four levels:
- Shelves group books.
- Books group chapters (and can also hold standalone pages).
- Chapters group pages.
- Pages are the actual content.
A book can sit on multiple shelves. This is the entire structure. There is no fifth level. You cannot nest a page inside a page, and there is no free-form "graph" of interconnected notes. If your mental model of knowledge is a hierarchy — runbooks, product docs, onboarding guides, policy manuals — this clicks immediately. If your mental model is a web of atomic notes that link in every direction (think Obsidian or Logseq), BookStack will frustrate you, because it was deliberately not built for that.
This opinionated scope discipline is rare in open source, and the maintainer states it without apology in the README: BookStack is "not designed as an extensible platform to be used for purposes that differ from" its core documentation mandate. That self-imposed boundary is the main reason the codebase has stayed navigable over a decade, and it is the reason the feature list stays focused instead of ballooning.
For a practical operator, the hierarchy implies a governance style. Permissions cascade from books and chapters down to descendants, with per-entity overrides. Large deployments should design around inheritance rather than per-page ACL sprawl, because dozens of one-off overrides multiply administrative complexity fast. Plan for inherited permissions and your life stays simple; fight the hierarchy with exceptions and you will regret it at scale.
3. Editing: WYSIWYG and Markdown, Both First-Class
One of BookStack's quiet strengths is that it does not force Markdown on people who do not want it. The default page editor is a WYSIWYG interface built on CKEditor (with CodeMirror 6 wired in for code blocks and syntax highlighting across a wide range of languages). Non-technical contributors — support staff, HR, operations — can write documentation without learning a markup language. That alone removes a real adoption barrier in mixed teams.
For people who prefer Markdown, BookStack ships a Markdown editor with a live preview pane, and you can switch between editors per page. The WYSIWYG output is stored in the database as HTML; the Markdown editor is a layer over that. PDF, HTML, plain-text, and Markdown export are all available out of the box, so content is not trapped in a proprietary format. Diagrams.net (draw.io) is built directly into the page editor, so you can create network topologies, architecture diagrams, and process flows inline without hosting diagrams externally and linking out to them.
The practical takeaway: BookStack is one of the few wikis where the non-engineer and the engineer can both be productive without compromise. That is a bigger deal for real-world documentation adoption than any plugin marketplace.
4. Search, Linking, and Revisions
BookStack content is fully searchable at the book level or globally across every book, chapter, and page. Direct links to specific paragraphs are supported, which keeps documentation connected — you can link a runbook step directly to the relevant paragraph rather than "see chapter 4." Cross-book sorting and page revisions round out the core reading and writing experience.
Every edit creates a revision. You can diff revisions and roll back to any previous version. For a documentation system this is table stakes, but it is worth stating because it is reliable and built in, not a paid add-on. Image management is handled inside the app, so screenshots and diagrams live with the content rather than in a separate bucket you have to wire up.
The search experience is good for the scale most self-hosters actually have — a few thousand pages across a team or a company. It is not meant to be an enterprise semantic search engine, and the project does not pretend otherwise.
5. Authentication: OIDC, SAML, LDAP, Social
BookStack's integrated authentication goes well beyond the default email/password login. It supports OIDC, SAML2, and LDAP for self-hosted and enterprise environments, plus a range of social-based secondary authentication options (GitHub, Google, Slack, Microsoft, and others). For a self-hoster who already runs an identity layer — Keycloak, Authelia, or Authentik (all of which we cover in this series) — BookStack slots in as just another OIDC or LDAP client. That means you can enforce single sign-on and centralize credential policy without BookStack becoming a separate identity silo.
MFA is built in and can be enforced at a per-role level. Options include TOTP (Google/Microsoft Authenticator, Authy, etc.) and static backup codes. For a docs system that may hold sensitive runbooks or internal policy, per-role MFA enforcement is a meaningful control that does not require an enterprise plan.
6. Roles and Permissions: Granular, Inherited, Per-Role Enforceable
BookStack ships a full role and permission system. You can lock down who can view, edit, create, or delete content at the role level and per entity, with inheritance down the hierarchy. Audit logging is included in the core (not behind a paywall), so you can see who changed what. For departmental or team-owned documentation spaces, this is enough to satisfy most internal governance needs without buying a seat-based commercial product.
The one design caveat flagged repeatedly by operators: because permissions are computed through a denormalized "joint permissions" strategy for fast list and search checks, the system is optimized for inheritance. If you instead build a sprawl of per-page overrides, administration gets complicated quickly. The guidance from the project itself is to plan around inherited permissions and avoid one-off ACL exceptions wherever possible.
7. The 2026 Codeberg Migration — and Why It Matters
Here is the fact most people miss before they go looking for issues or try to contribute: in early 2026, BookStack's canonical source repository moved from GitHub to Codeberg. GitHub now serves as a mirror. The issue tracker, CI pipelines, and active development all live at codeberg.org/bookstack/bookstack.
This is a deliberate philosophical move aligned with the project's open-source ethos, and it is worth knowing for three practical reasons. First, if you file a bug or send a patch expecting GitHub to be the front door, you are at the wrong building — go to Codeberg. Second, mirrors lag, so the GitHub star count and the live development activity are not the same clock; don't read GitHub commit recency as the project's pulse. Third, for anyone who cares about forge sovereignty (the theme of this entire blog), a popular MIT project choosing a non-GitHub home is itself a data point: the code is yours, and so is the community's choice of where to keep it.
None of this changes the software. The releases still ship on the calendar schedule, the docs are unchanged, and the MIT license is unaffected. But it is a detail that will save you confusion the first time a GitHub PR sits untouched while the real action is on Codeberg.
8. REST API and Automation
BookStack exposes a REST API covering CRUD operations on the core content types — books, chapters, pages, and more. Recent releases expanded REST support for comments and image data and added ZIP import/export endpoints. For migrations and automation, the intended path is API-first: use the API for bulk content creation rather than direct database manipulation, which avoids schema-compatibility issues and ensures proper permission and content validation.
This matters if you are migrating an existing wiki in. The project is explicit that you should use API-driven bulk operations, not direct DB writes, because major releases can change database structure, permission logic, search behavior, and email behavior. Treat upgrades as compatibility events requiring staged validation: pin versions and validate thoroughly before a production rollout rather than blind rolling deploys. v22.10 significantly changed permission management and v25.11 updated database formats, so version jumps are not cosmetic.
9. The Honest Limitations: No Plugin System, No Real-Time Collab
Here is where the opinionated scope discipline cuts both ways. BookStack has no native plugin system in the traditional sense. There is no marketplace of third-party extensions you can bolt on. If you need a capability the core does not have, your options are: live with it, script against the API, or fork (and then you own the maintenance). For teams that want to extend the wiki into a workflow engine or an app platform, this is a hard wall.
There is also no real-time collaborative editing. Two people editing the same page will collide; the last save wins, and you reconcile via revisions. If your team expects Google-Docs-style simultaneous cursors on a living document, BookStack is not that tool. It is built for written, reviewed, durable documentation — not for co-authoring a doc in the same minute.
There is no built-in commenting workflow that competes with Notion's, and no native database/spreadsheet view. If your "wiki" is really a project tracker or a CRM, you are using the wrong category of software. BookStack is a wiki. It wants to stay a wiki.
10. Bus Factor 1 — the Risk You Should Name Out Loud
BookStack is maintained primarily by Dan Brown with a community of contributors. The OpenSSF Scorecard for the project has been reported around 3.2/10, and the "bus factor" — how many people could keep the project alive if the lead were hit by a bus — is effectively 1. For a tool you might entrust your company's runbooks to, this is the risk that deserves a name, not a footnote.
It is not necessarily a dealbreaker. The software is MIT-licensed and stable; even if development slowed tomorrow, you could keep running v26.x indefinitely, and the source on Codeberg means no single company can pull the license. But "the project is one person's sustained effort" is a fact that should inform your contingency planning: export your content regularly (the Markdown/HTML/PDF/ZIP export and Git-style backups make this easy), and do not build process dependencies you cannot unwind. MIT means you are allowed to fork and self-maintain; bus factor 1 means you should know that fork might one day be necessary.
11. Deployment: PHP, Laravel, MySQL
BookStack is a traditional server-rendered PHP application on Laravel. The dependency fingerprint is unambiguous: backend PHP with Laravel (MVC, Eloquent ORM, Artisan CLI, Blade templates), MySQL or MariaDB for storage (the project actually tests against MySQL 8.4 in dev), a frontend built with TypeScript compiled via esbuild and SCSS via Dart Sass. The build chain deliberately avoids webpack/Vite sprawl — esbuild is a Go-based bundler chosen for speed over plugin ecosystem. That is a project making deliberate, conservative tooling choices, which is reassuring for long-term maintainability.
Operationally this means you need a traditional LAMP-style server (Linux, PHP, a web server like Nginx or Apache, and MySQL/MariaDB). A minimum viable setup runs on a small VPS. There is no official hosted version — you run it or you do not use it. Third-party managed providers exist (independent businesses, not BookStack itself) if you want someone else to handle the server, but those are separate commercial offerings.
Docker support exists via a dev compose file and community production images. If you go the container route, the moving parts are the PHP-FPM app, the web server, and the MySQL database — a familiar triad, not an exotic one.
12. Upgrades: Treat Them as Compatibility Events
Because BookStack stores content in MySQL and computes denormalized permission joints, upgrades are not always trivial. Major releases can change database structure, permission logic, search behavior, and email behavior. The project's own guidance — and the experience of operators — is to pin versions and validate before rolling to production.
Concretely: back up the database and the uploaded-files volume before every upgrade. Read the release notes for permission or search changes. If you are jumping multiple major versions, stage the upgrade on a copy first. v22.10's permission-management change and v25.11's database-format update are the canonical examples of "this looked like a patch and was not." None of this is unusual for a PHP app with a real database; it is just the honest cost of owning a stateful documentation system rather than renting one.
13. Where Your Data Goes
This is the question this entire blog exists to answer, so let's be precise. When you self-host BookStack:
- Content (pages, books, chapters, shelves, revisions, images) lives in your MySQL/MariaDB database and your uploaded-files volume. It does not leave your server unless you configure it to.
- Authentication, if you use OIDC/SAML/LDAP, is brokered by your own identity provider (Keycloak, Authelia, Authentik, or your corporate SSO). BookStack does not phone home for login.
- Diagrams.net is built in and runs client-side for editing; you are not shipping your diagrams to a third-party draw.io service.
- Telemetry: BookStack does not ship a phone-home analytics beacon in the core. There is no commercial entity harvesting usage data, because there is no commercial entity. This is a genuine sovereignty advantage over hosted docs products.
The one caveat: if you enable social login (GitHub/Google/etc.), those providers see the authentication handshake, exactly as with any OIDC flow. That is a choice you make per integration, not a default behavior. Out of the box, with local or self-hosted SSO, your documentation stays entirely within infrastructure you control.
14. BookStack vs the Field
A few honest comparisons, because "just use BookStack" is rarely the right answer without context.
- vs Notion / Confluence: BookStack wins on ownership and cost (free, MIT, self-hosted) and loses on real-time collaboration, rich blocks, and ecosystem. If you need a per-seat SaaS with live co-editing, those are the tools; if you need docs you own with zero licensing, BookStack is the tool.
- vs Wiki.js (covered in this series): Wiki.js is more architecturally ambitious (Git-backed storage, more database backends, a bigger feature surface) but carries an AGPL license and, in 2026, a slowing maintenance cadence. BookStack is simpler, MIT, and actively shipped monthly. Pick BookStack for simplicity and license comfort; pick Wiki.js if you specifically want Git-backed content and can accept AGPL plus maintenance risk.
- vs Outline: Outline is slicker and API-driven but needs more infrastructure to run (and is BUSL-licensed, not OSI-open). BookStack is the lower-infrastructure, more permissive choice.
- vs DokuWiki / Gollum: Those are even lighter (flat files, no DB) but feel dated and lack BookStack's role system and WYSIWYG polish. BookStack sits in the sweet spot of "modern UI, real permissions, still simple to run."
15. Cost: The Zero-Tier Tool
BookStack has exactly one tier: everything, for free. There is no free-vs-paid decision because there is no paid. The only costs are the infrastructure you run it on (a small VPS or container) and your time. For a team weighing Notion's per-seat floor or Confluence's license against a few dollars a month of server plus an afternoon of setup, BookStack is often the cheapest
and the most sovereign option — a rare combination.
The honest "cost" is operational: you patch PHP, you back up MySQL, you manage upgrades, you run the identity integration. That is the trade for not renting. For most small teams and families, it is a trade well worth making, and the total cost of ownership stays low because the app itself is undemanding.
16. Backup and Disaster Recovery
Because everything lives in MySQL plus an uploaded-files directory, backup is boring in the best way. Take a scheduled mysqldump (or your DB's native backup) and a copy of the files volume. The built-in ZIP export and the Markdown/HTML/PDF export give you human-readable offsite copies that survive any scenario, including "the server is gone and I only have the files." For extra safety, the REST API lets you script periodic content pulls.
The key discipline: do not treat "it's in the database" as "it's safe." A single mysqldump to the same disk is not a backup. Ship the dump offsite (object storage, another machine) on a schedule. BookStack makes the export trivial; the discipline is yours.
17. Security Posture and Advisories
BookStack ships monthly security releases and has a responsible-disclosure process; v26.05.x was explicitly a security-focused patch line. Public advisory trackers have listed a modest number of advisories over the project's life, consistent with a web app of its size. The mitigations that matter for an operator: keep the instance patched (the monthly cadence makes this easy), enforce MFA per role, restrict registration on public instances, and put it behind your reverse proxy with your standard WAF and rate-limiting.
One structural point in BookStack's favor: being a conventional PHP/Laravel app means your existing PHP hardening knowledge applies. There is no novel runtime to learn, no exotic memory model to reason about. The attack surface is the familiar web-app surface, and the defenses are the familiar web-app defenses.
18. Who Should Run It — and Who Shouldn't
Run BookStack if: you need structured, navigable documentation your team actually adopts; you want zero licensing cost and MIT license comfort; you value a WYSIWYG editor for non-engineers; you already run (or can run) a small PHP/MySQL stack; and you are fine with hierarchical, not graph, knowledge.
Do not run BookStack if: you need real-time multi-cursor collaboration; you want a plugin ecosystem to extend the wiki into an app platform; your knowledge model is a free-form web of atomic notes; or you require vendor-backed SLA support (there is no commercial entity behind BookStack — sponsorships and community only). In those cases, look at the alternatives above and choose the pain you prefer.
19. A Practical Getting-Started Path
For a self-hoster, the lowest-friction path is a container compose (app + db) behind your existing reverse proxy (Caddy or Traefik, both covered in this series), with SSO wired to your identity provider via OIDC or LDAP. Set registration to invite-only or disabled for a private instance. Enforce MFA on the admin role. Schedule DB + files backups offsite. Then import your existing docs via the REST API or the ZIP importer, and let the hierarchy do its job.
Resist the urge to over-engineer permissions on day one. Start with a few roles (admin, editor, viewer) and inherit downward; add per-entity overrides only when a real need appears. The teams that stay happy with BookStack are the ones that accepted its opinionated model instead of fighting it.
20. The Verdict
BookStack is the rare open-source project that is
more valuable because of what it refuses to be. No plugin marketplace means no dependency rot. No real-time collab means no operational complexity for a feature most docs don't need. No paid tier means no surprise negotiation with procurement. MIT means you can fork and keep it forever. The costs — a PHP/MySQL stack to run, monthly patching, and a bus factor of one — are real but small, and they are the price of owning your documentation instead of renting it.
For a sovereign operator who wants a wiki that stays out of the way, BookStack is one of the strongest picks in the self-hosted documentation category in 2026. Just go to Codeberg for the issues.
21. A Migration Playbook from Notion or Confluence
If you are moving an existing wiki into BookStack, resist the big-bang import. The hierarchy is the hard part, not the text. Notion's nested-page trees do not map cleanly onto shelf/book/chapter/page, and Confluence's spaces-plus-pages model needs deliberate translation. A workable path:
1.
Inventory before importing. Decide what is actually documentation worth keeping versus what is stale. Most migrations carry 30–40% dead content; leave it behind.
2.
Map at the book level. Make each Notion "top-level page" or Confluence "space" a Book, and let sub-pages become chapters or pages based on depth. Do not try to preserve infinite nesting — BookStack's four levels are a feature, not a limitation to fight.
3.
Use the REST API for bulk import, not copy-paste. Export source content to Markdown, then push via the API so permissions and revisions are created correctly. Direct DB writes will break on the next schema change.
4.
Re-establish ownership per book. Assign roles and let inheritance do the work; do not recreate per-page ACLs you had in the old tool.
5.
Train on the WYSIWYG. The biggest adoption win is letting non-engineers contribute without learning Markdown. Show them the editor, not the API.
A staged migration — one team's books first, validate, then the rest — beats a weekend blitz every time.
22. Content-Modeling Patterns That Work
Because the hierarchy is fixed, the art is in the mapping. A few patterns that hold up in production:
- Runbooks as Books. Each service or system gets a Book (e.g., "Payments Service"), with Chapters for "Deploy," "Incident," "On-call," and Pages for each procedure. Shelves group by domain ("Backend," "Infra").
- Product docs as a Shelf. One Shelf per product, Books per major area (Getting Started, API, Billing), Chapters per feature. This keeps cross-linking stable as the product grows.
- Policy manuals as Books with strict viewer roles. HR and security docs live in Books where the viewer role is locked to the relevant group, with editor restricted to owners.
- Personal sandboxes discouraged. BookStack is a team tool; giving everyone a private Book tends to fragment knowledge. Prefer shared books with clear ownership.
The failure mode is "one giant Book with 200 pages and no chapters" — search still works, but navigation collapses. Spend the chapters.
23. The Missing Native Git Sync — and What to Do Instead
Unlike Wiki.js (which can back content with a Git repository), BookStack has no native Git storage backend. Content lives in MySQL. For teams that wanted "docs as code" with Git history and PR review, this is the most-requested missing feature, and the project has deliberately not built it.
Your realistic options: use the REST API to script periodic exports into a Git repo (a cron job that pulls content and commits), or accept that BookStack's built-in revisions are your history layer. The API path gives you Git-backed offsite copies and diffable history without forking the core. It is more work than a built-in toggle, but it respects the project's scope and avoids fighting the data model. If Git-backed docs is a hard requirement, Wiki.js is the alternative in this series — at the cost of AGPL and a slower 2026 maintenance cadence.
24. Community, Docs, and the Support Reality
BookStack's documentation site is genuinely good — installation, administration, and theming are all covered, and the writing is clear. The community lives on the Codeberg repo (issues and discussions) and the project's own forum. Because there is no commercial entity, "support" means community plus your own competence; there is no SLA, no paid priority queue.
For most self-hosters this is fine. The app is stable, the docs are accurate, and the failure modes are ordinary PHP/MySQL problems you already know how to debug. The bus-factor-1 risk (Section 10) is the part to internalize: the project is one person's sustained effort, so your contingency is a solid backup and the knowledge that you
could fork under MIT if you ever had to. Treat the community as peers, not a vendor, and you will be well served.
25. A REST API Walkthrough
The API is straightforward once you have a token. In the admin panel, create an API token with the scopes you need (e.g., read/write on pages). Then:
``
bash
List books
curl -H "Authorization: Token YOUR_TOKEN" \
https://docs.example.com/api/books
Create a page inside a book (book_id from the list above)
curl -X POST -H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"book_id": 12, "name": "Onboarding Checklist", "html": "<p>Welcome.</p>"}' \
https://docs.example.com/api/pages
`
That is the entire shape: authenticate with the token, hit a resource endpoint, send JSON. For migrations you script exactly this in a loop over your exported Markdown (converted to HTML). The API also covers chapters, shelves, and images, so a complete programmatic import is feasible without touching the database. Pin your script to a specific API version and re-test on BookStack upgrades, since permission and content behavior can shift between major releases.
26. FAQ and Troubleshooting
"Login loop after enabling OIDC." Almost always a mismatched redirect URI or a missing email` claim mapping in your IdP. Check the exact callback URL BookStack shows in its auth settings and replicate it in Keycloak/Authelia.
"Search returns no results after restore." The search index is derived; after a DB restore, trigger a re-index from the admin panel or the CLI. A raw mysqldump restore does not rebuild the search tables.
"Images broken after moving servers." The uploaded-files volume is separate from the database. If you restored the DB but not the files directory, images 404. Back up both.
"Can I run it on SQLite?" No — BookStack requires MySQL or MariaDB. SQLite is not supported, and the permission-joint logic assumes a real RDBMS.
"Is the GitHub repo the source of truth?" No — Codeberg is, since early 2026. GitHub is a mirror. File issues and PRs on Codeberg.
27. The Sovereignty Scorecard
If you score BookStack on the axes this blog cares about, it lands cleanly in the "own it" quadrant:
- Data ownership: 10/10. Content and files live entirely in your MySQL and your volume. No phone-home, no vendor custody.
- License freedom: 10/10. MIT means you can use, modify, and fork with zero obligations, commercially or not.
- Operational cost: 8/10. A small PHP/MySQL stack is cheap to run; the only drag is patching and upgrades, which the monthly cadence keeps light.
- Lock-in risk: 2/10. Exports are human-readable (Markdown/HTML/PDF/ZIP); even a total fork under MIT is permitted.
- Maintenance risk: 6/10. Bus factor 1 is the only real dent — the software is stable, but the project's future rests on one person's continuity.
The aggregate is a strong yes for teams that want documentation they control, with the single caveat that you should bake backups and an exit plan into your routine from day one, precisely because the project is one maintainer's craft. For a few dollars a month and an afternoon of setup, that trade is hard to beat.
Related
For the rest of a sovereign, self-hosted stack, these pieces from our series travel with BookStack:
Comments (0)
No comments yet. Be the first to comment!