How to Migrate from Confluence to BookStack

Confluence pricing ($6.05-11.55/user/month) and Atlassian's push toward cloud mean many teams are looking for self-hosted alternatives. BookStack is the most Confluence-like open source option — organized by shelves, books, chapters, and pages. Here's how to migrate.

Why BookStack?

BookStack's hierarchy mirrors Confluence naturally:

Confluence	BookStack
Space	Shelf or Book
Page tree	Chapters
Pages	Pages
Labels	Tags
Comments	Comments
Attachments	Attachments

What Transfers

Content	Status
✅ Pages and content	HTML export → import
✅ Page hierarchy	Recreate as chapters/pages
✅ Text formatting	Well preserved via HTML
✅ Images	Embedded in export
✅ Tables	Supported
✅ Code blocks	Supported
⚠️ Macros	Some need manual conversion
⚠️ Attachments	Export separately, re-upload
❌ Page comments	Not preserved in export
❌ Page history	Not preserved
❌ Confluence macros	Replace with BookStack equivalents

Step 1: Deploy BookStack

# Docker Compose
docker run -d \
  --name bookstack-db \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=bookstack \
  -e MYSQL_USER=bookstack \
  -e MYSQL_PASSWORD=secret \
  mysql:8.0

docker run -d \
  --name bookstack \
  --link bookstack-db:db \
  -e DB_HOST=db \
  -e DB_DATABASE=bookstack \
  -e DB_USERNAME=bookstack \
  -e DB_PASSWORD=secret \
  -e APP_URL=https://docs.yourdomain.com \
  -p 80:80 \
  solidnerd/bookstack

Default login: admin@admin.com / password — change immediately.

Step 2: Export from Confluence

Option A: Space export (recommended)

1. Go to the Confluence space → Space Settings → Content Tools
2. Click Export
3. Select HTML Export
4. Choose Full Export (all pages)
5. Download the ZIP

Option B: Individual pages

1. Open page → ⋯ → Export → Word or PDF
2. Repeat per page

Option C: API export (for large spaces)

# Export pages via Confluence REST API
curl -u email:api-token \
  "https://your-instance.atlassian.net/wiki/rest/api/content?spaceKey=MYSPACE&limit=100&expand=body.storage" \
  > confluence-export.json

Step 3: Import into BookStack

BookStack doesn't have a native Confluence importer, but several approaches work:

Approach 1: HTML import (best for most cases)

1. Extract the HTML export ZIP
2. Open BookStack → Create a Book for each Confluence space
3. Create Chapters for page tree sections
4. For each page: New Page → click the HTML editor → paste the HTML content
5. Clean up formatting as needed

Approach 2: Markdown conversion

# Convert HTML to Markdown using pandoc
for f in *.html; do
  pandoc "$f" -f html -t markdown -o "${f%.html}.md"
done

Then import Markdown files into BookStack pages.

Approach 3: API import (for automation)

# Create a book via API
curl -X POST https://docs.yourdomain.com/api/books \
  -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  -d '{"name": "Migrated Space", "description": "From Confluence"}'

# Create pages
curl -X POST https://docs.yourdomain.com/api/pages \
  -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  -d '{"book_id": 1, "name": "Page Title", "html": "<p>Content...</p>"}'

Step 4: Organize Structure

1. Create Shelves for top-level categories (Engineering, Product, HR, etc.)
2. Create Books within shelves (matching Confluence spaces)
3. Create Chapters for page groups
4. Move pages into appropriate chapters
5. Set permissions per shelf, book, or chapter

Step 5: Set Up Authentication

# LDAP (Active Directory)
AUTH_METHOD=ldap
LDAP_SERVER=ldap://your-ad-server:389
LDAP_BASE_DN=dc=yourdomain,dc=com
LDAP_DN=cn=admin,dc=yourdomain,dc=com

# SAML (Okta, Azure AD, etc.)
SAML2_ENABLED=true
SAML2_IDP_ENTITYID=https://your-idp.com
SAML2_AUTOLOAD_METADATA=true

BookStack supports LDAP, SAML, OIDC, and social login (Google, GitHub, etc.).

Step 6: Handle Confluence Macros

Confluence Macro	BookStack Equivalent
Code block	Code block (syntax highlighted)
Table of contents	Auto-generated sidebar
Info/Warning/Note panels	Callout blocks
Jira issue link	Manual link
Page include	Not available (link instead)
Expand/Collapse	Details block
Status label	Not available (use text)
Draw.io diagram	Embed as image

Cost Savings

Team Size	Confluence Standard	BookStack	Savings
10 users	$61/month	$10/month (VPS)	$612/year
25 users	$151/month	$15/month	$1,632/year
50 users	$303/month	$20/month	$3,396/year
100 users	$578/month	$40/month	$6,456/year

Migration Timeline

Week	Task
Week 1	Deploy BookStack, export Confluence, begin import
Week 2	Complete import, organize structure, set up auth
Week 3	Invite team, run both platforms
Week 4	Primary documentation moves to BookStack
Month 2	Sunset Confluence

Production Hardening and Backup Strategy

A fresh BookStack install works well for a small team, but moving into production requires several additional steps to protect your data and ensure availability.

Start with your database backup strategy. BookStack stores all content in MySQL. A daily automated backup to off-server storage — an S3 bucket, Backblaze B2, or even a different VPS — is non-negotiable for a knowledge base your team depends on. A simple nightly cron job running mysqldump and uploading to object storage takes fifteen minutes to set up and saves you from catastrophic data loss. Pair this with testing your restore process at least once during the migration, before you decommission Confluence. Many teams discover their backup process has a silent failure mode only when they need to use it.

Reverse proxy configuration matters both for security and for user experience. BookStack should sit behind Caddy or Nginx that handles TLS termination, HTTP-to-HTTPS redirection, and appropriate security headers. Caddy makes this particularly easy — its automatic Let's Encrypt integration means you configure your domain once and HTTPS just works. Add a Content Security Policy header to prevent XSS vulnerabilities, and ensure the X-Frame-Options header prevents clickjacking on your wiki pages.

File uploads in BookStack default to local filesystem storage. This works fine initially but creates complications if you ever run multiple application nodes or need to restore from a partial backup. Consider configuring S3-compatible storage (MinIO for self-hosted) from the start. BookStack supports it natively via the STORAGE_TYPE=s3 environment variable and a handful of S3 configuration variables. With S3 storage, your Docker volumes only contain the application code and configuration — all user data lives in the database and object storage, which are independently backed up.

Permissions, Roles, and Access Control

One of BookStack's genuine strengths over many wiki alternatives is its layered permissions model. Understanding it fully unlocks the ability to build a knowledge base that serves different teams with different access needs.

BookStack has four default roles: Admin, Editor, Viewer, and a customizable Public role. You can create additional custom roles with any combination of permissions. The permissions system works at two levels: role-level permissions determine what actions a user can take globally (create books, delete pages, export content), and content-level permissions restrict access to specific shelves, books, chapters, or pages.

The content-level permissions are particularly useful for knowledge bases that mix public and private content. An engineering team's runbooks should be visible only to engineers. HR documentation should be visible only to HR and management. Public-facing documentation can be world-readable without authentication. You can implement all of these distinctions within a single BookStack instance by configuring content-level permissions on the relevant shelves and books. You do not need separate BookStack instances for different content sensitivity levels.

For enterprise deployments, the LDAP and SAML integrations let you automatically assign roles based on group membership in your identity provider. When a new employee joins and gets added to the Engineering group in your LDAP directory, they automatically receive the Engineering role in BookStack — no manual provisioning required. This matters at scale because manual role management becomes a real operational burden with frequent staff changes.

Teams considering BookStack as part of an Atlassian replacement should also review the full context around why teams are leaving Atlassian after recent price hikes. The decision is rarely just about the wiki — most teams migrating from Confluence are simultaneously evaluating Jira alternatives like Plane, and a complete migration plan addresses both tools together rather than in isolation.

BookStack vs Other Open Source Wiki Options

BookStack is the most Confluence-like open source wiki, but it is not the only option. Understanding where it fits in the broader landscape helps you confirm you are picking the right tool.

Wiki.js is the most direct alternative to BookStack. It offers a similar feature set — rich text editing, multiple content trees, access control, and self-hosting — but uses a more modern technology stack (Node.js) and supports more database backends including PostgreSQL and SQLite. Wiki.js has stronger full-text search capabilities out of the box and a more flexible content organization model. BookStack's advantage is its more opinionated Confluence-like hierarchy, which makes it easier to onboard teams that already think in terms of spaces and pages.

Outline is another strong option, particularly for teams that prioritize clean UI and real-time collaboration. Outline's editor is more polished than BookStack's, and its Slack-like collections model is intuitive. The trade-off is that Outline is more document-focused and less wiki-focused — it excels at creating and sharing documents, but its hierarchical organization is shallower than BookStack or Confluence. For teams whose primary use case is collaborative note-taking and documentation rather than deep hierarchical knowledge management, AppFlowy and Outline offer an interesting comparison worth reading before committing.

DocMost is a newer entrant with explicit Confluence inspiration and a modern stack. It is earlier-stage than BookStack but moves quickly and is worth watching if you want a more contemporary architecture.

The right choice depends on what Confluence workflows your team actually uses. If your knowledge base is heavily nested with many levels of hierarchy and lots of different spaces with different permission sets, BookStack's Confluence-inspired model will feel most natural. If your team primarily creates and shares standalone documents, Outline may be a better fit.

Running the Migration Without Disruption

The biggest migration risk is not technical — it is operational continuity. Teams that go "cold turkey" on Confluence and immediately expect everyone to use BookStack tend to hit friction: content that did not migrate correctly, colleagues who cannot find familiar pages, and loss of confidence in the new tool. A parallel running period eliminates most of this risk.

The recommended approach is a phased migration over four to six weeks. In week one, deploy BookStack and migrate one high-traffic section of your knowledge base — the engineering onboarding docs or the product specifications section. Get ten people using BookStack for that content while everything else stays in Confluence. In week two, gather feedback, fix formatting issues, and migrate a second section. By week four, most content has moved and Confluence is used only for history lookup. By week six, you can archive Confluence access or let the subscription lapse.

This approach has a secondary benefit: it surfaces the content that matters. Migrating an entire Confluence instance often reveals that large sections of pages have not been read or updated in years. The migration itself is a content audit. When you manually import pages into BookStack, you make a conscious decision about whether each piece of content is worth carrying forward — which is an opportunity to remove outdated runbooks, superseded architecture documents, and meeting notes from 2019 that should have been archived long ago.

For teams navigating the broader Atlassian exit decision — not just Confluence but also Jira — the guide to open source Atlassian alternatives after the price hike covers the full picture including Plane for issue tracking and GitLab for code hosting, which most teams need to evaluate alongside their Confluence migration. Teams that want a detailed head-to-head evaluation of BookStack specifically against Wiki.js should also read the BookStack vs Wiki.js comparison before committing to either platform — both are strong choices and the right pick depends on your team's technical comfort and organizational structure.

---

Compare documentation platforms on OSSAlt — editing experience, organization, and self-hosting options side by side.

See open source alternatives to Confluence on OSSAlt.