Confluence Data Center to XWiki Migration: The Self-Hosted Path

If you're running Confluence Data Center because your organization requires on-premise infrastructure — and Confluence Cloud is not an option — XWiki is the most technically mature open-source replacement available.

This guide covers the exact migration path: what XWiki's native importer handles, where it breaks, how to get data out of large DC instances without hitting the XML export's OutOfMemory wall, and what the content translation actually looks like at a technical level.

This is written for teams that must keep their wiki on infrastructure they control. Not teams evaluating Notion or SharePoint.

Who This Guide Is For

This targets a specific audience: organizations where self-hosted infrastructure is a hard requirement, not a preference.

That includes:

• Government agencies and defense contractors operating in air-gapped or classified environments
• Healthcare systems subject to HIPAA or national health data residency laws
• Financial institutions under regulatory mandates for data locality
• EU organizations concerned about US cloud data sovereignty post-Schrems II
• Any team that chose Confluence Data Center specifically to avoid cloud dependency

Atlassian Data Center reaches End of Life on March 28, 2029. If you do not currently own a Data Center license, the door closes on March 30, 2026 — from that point forward, the only entry point into the Atlassian ecosystem is the Cloud. Atlassian implemented significant price increases on February 17, 2026, for Data Center products, designed to encourage the move to Cloud.

If your organization rejected Confluence Cloud for regulatory or sovereignty reasons, those same reasons rule out most SaaS alternatives. Your realistic shortlist for a self-hosted wiki is XWiki, BookStack, Wiki.js, or DokuWiki. Of these, XWiki is the only one that matches Confluence's enterprise feature set: structured permissions, LDAP/AD integration, macro extensibility, and clustering for high availability. Atlassian ended Confluence Server support on February 15, 2024, so Server customers face the same decision.

For a broader comparison of all Confluence alternatives including cloud options, see Confluence Alternatives (2026): Platforms, Limits & Migration.

XWiki vs Confluence: Architecture and Syntax Differences

The good news for infrastructure teams: XWiki's stack is structurally familiar. In terms of features and technologies, XWiki and Confluence look very similar in appearance. Both are developed in Java and include many features by default. Extensions and plugins are available and can extend other functionalities.

XWiki is a Java application that runs on Apache Tomcat and stores its data in a relational database. The resource requirements scale with your user count, content volume, and the number of extensions you install. Your team's existing skills in JVM tuning, reverse proxy configuration (Nginx/HAProxy), and database maintenance transfer directly.

What XWiki Does Better

XWiki is a 100% Open Source software (developed under the LGPL license), unlike Confluence, a proprietary software. Unlike Atlassian Confluence, XWiki supports a structured data model that lets you add form and consistency to your content. XWiki's class/property system lets you define custom fields on any document type — something Confluence can only approximate with page properties macros and third-party apps.

XWiki provides native support for LDAP and Active Directory authentication, including group synchronization and automatic user provisioning. XWiki supports SAML 2.0, OpenID Connect, Keycloak, and CAS for single sign-on integration. Unlike Confluence Cloud, which requires the paid Atlassian Access add-on for SAML SSO and SCIM provisioning, XWiki includes these authentication capabilities at no additional cost.

What XWiki Does Worse

Be honest with your team about the trade-offs:

• Smaller extension ecosystem. Confluence's Marketplace advertises 4,000+ apps and integrations across Atlassian products. XWiki's extension site advertises 900+ extensions. That is not a one-for-one Confluence comparison, but the gap is real. Expect more plugin-gap analysis and more cases where you redesign a workflow instead of replacing an app by name.
• Less polished WYSIWYG editor. XWiki uses CKEditor, which is functional but not as refined as Confluence's editor — especially for non-technical users. Recent versions enable real-time WYSIWYG editing by default, but teams used to Confluence should test editor-heavy pages early.
• Smaller community. Fewer Stack Overflow answers, fewer blog posts, fewer consultants. Your team will rely more heavily on XWiki's official documentation and forums.
• No native Jira integration. If your team depends on the Confluence–Jira link, that integration does not exist natively in XWiki.

Storage Format: Why This Is a Translation Project

Confluence stores content in a proprietary XHTML-based format. Every page is an XML document containing Atlassian-specific elements for macros, layouts, and image attachments.

XWiki defaults to XWiki Syntax 2.1. Raw HTML must be wrapped in an HTML macro. When migrating, Confluence's XHTML must be parsed and translated into XWiki Syntax to ensure native editability. That is why a Confluence Data Center to XWiki migration is a format-translation project, not a file copy.

How the XWiki Confluence Migrator Pro Works

The Confluence Migrator is the old tool that allowed you to migrate one space at a time. In 2023, XWiki SAS focused on developing the new Confluence Migrator (Pro), which allows you to directly import your Confluence backup package and import multiple spaces at a time, including users, permissions (beta feature at the moment) and blog posts.

XWiki offers two migration tools. The community Confluence Migrator is free and open-source, suitable for testing and evaluation. The Confluence Migrator Pro, which includes advanced features like user mapping, permission migration, and batch processing, is available to organizations with an active XWiki Business or Enterprise subscription. For production migrations, the Migrator Pro is strongly recommended.

What Migrates Successfully

• Confluence's parent-child page relationships are preserved during migration. XWiki uses a hierarchical document model (Nested Pages) that maps naturally to Confluence's page tree structure. Spaces, parent pages, and child pages maintain their relationships.
• Attachments and inline images are included in the Confluence export and migrated along with page content. Page history is preserved, though attachment history is not preserved yet.
• Confluence's Info, Warning, Note, and Tip panels convert to XWiki's message macros. Code blocks convert to XWiki's code macro with language syntax highlighting preserved. The Table of Contents macro converts to XWiki's TOC macro. Expand/Collapse sections convert to XWiki's collapsible content components. Page includes and excerpts have direct XWiki equivalents.
• The Migrator Pro docs list code, include, pagetree, warning, tip, note, attachments, excerpt, excerpt-include, gliffy, and drawio as supported. (store.xwiki.com)

What Breaks or Needs Manual Work

• Macros from Marketplace apps require more attention. If a Confluence app provided a custom macro (for example, a diagramming macro from draw.io), the Migrator Pro will preserve the content but may not be able to render it in XWiki's native format without the corresponding XWiki extension installed.
• Confluence proposes many fine-grained permissions for which XWiki doesn't have corresponding rights (including, but not limited to: EXPORTSPACE, EXPORTPAGE, REMOVEMAIL, REMOVEOWNCONTENT, CREATEATTACHMENT, REMOVEATTACHMENT, REMOVECOMMENT, PROFILEATTACHMENTS, ARCHIVEPAGE).
• Jira macros — any {jira} or {jiraissues} macro content renders as an unknown macro in XWiki. The migrator does not automatically convert jira-key or jira-jqlQuery.
• Status macros — Confluence's colored status labels have no native XWiki equivalent and require custom CSS or a bridge macro.
• Deep table formatting — complex merged cells and colored rows may lose styling.
• Lucidchart — No possibility to display Lucidchart diagrams after the Confluence migration — renders as "Unknown macro: lucidchart-onprem".
• Table Filter, Scroll-* macros, and pageapproval-report are listed as not automatically migrated. (store.xwiki.com)

Bypassing the Confluence XML Export OutOfMemory Trap

This is where most large-scale migrations hit their first wall. Confluence backups require large amounts of memory and CPU. Atlassian recommends disabling the backup from within Confluence and using native database SQL dump tools instead. This is preferable for backup, upgrade, and creation of a test server. The XML backup is only needed for migration to a new database.

The XML backup performs poorly under load and requires large amounts of memory and thus does not scale.

Confluence's XML export process serializes all page content and Base64-encodes every attachment inline, loading the entire DOM into the server's memory. In practice, spaces with 5,000+ pages and heavy attachments frequently trigger java.lang.OutOfMemoryError. One user migrating between DC instances reported very large spaces ranging from 5GB to 35GB, noting that the export takes forever, and downloads very often fail — sometimes waiting hours before the download still fails.

One important nuance: a Confluence export package is not just one monolithic XML file. It contains entities.xml, exportDescriptor.properties, and usually an attachments folder. Space packages contain pages, attachments, notifications, and permissions for that space. Site packages contain all spaces plus users and groups, but not the attachments folder. Users and groups appear only in full site exports, not in space exports — which is why identity and permission planning must happen outside the export process. (xwiki.org)

For a deep dive on all Confluence export methods and their limits, see How to Export All Data from Confluence: Methods, Limits & Tools.

Workarounds for Large Exports

1. Increase JVM heap for the export. Temporarily bump -Xmx in setenv.sh to 8–16 GB for the export process. This solves the problem for medium-sized spaces but often delays the crash rather than preventing it for very large ones.

2. Export spaces individually. Don't attempt a full site export. Export each space via Space Settings → Content Tools → Export → XML. This keeps individual export sizes manageable.

3. Export without attachments if heap is the blocker. Atlassian suggests exporting without attachments, then moving the attachments directory separately from <confluence-home>/attachments. (confluence.atlassian.com)

4. Use the REST API to batch page trees. For a single space with 10K+ pages, use the Confluence REST API (/rest/api/content) to identify page trees and export sub-trees individually. This bypasses the memory limit but introduces rate-limiting delays.

5. Direct database extraction. For the largest instances, extract content directly from the Confluence database (BODYCONTENT, CONTENT, and ATTACHMENTDATA tables) and build synthetic XML packages that XWiki's importer can consume. This is the most reliable approach for instances over 50 GB, but it requires understanding Confluence's internal schema. XWiki documents that entities.xml is close to Confluence's Hibernate/SQL model, making this feasible though not trivial. (xwiki.org)

Translating Macros, Links, and Storage Formats

The Migrator Pro handles the conversion from Confluence's XHTML storage format to XWiki Syntax 2.1 automatically for standard content. Here is what the translation looks like for the most common elements:

The Drawio macro is a bridge between the Drawio macro used in Confluence and the Diagram macro used in XWiki. The aim of this macro is to allow users to view and also to modify the Drawio/Diagrams.net diagrams migrated from Confluence. By default, the macro displays the preview of the Drawio diagram. XWiki recommends using the native XWiki diagram feature, also based on drawio.

Macro Mapping Example

A Confluence Info Panel stored as:

<ac:structured-macro ac:name="info">
  <ac:rich-text-body>Server maintenance at midnight.</ac:rich-text-body>
</ac:structured-macro>

Becomes this in XWiki Syntax:

{{info}}
Server maintenance at midnight.
{{/info}}

Similar translations are required for code blocks, page includes, and excerpt macros. The pattern is consistent: Atlassian's XML-based <ac:structured-macro> elements map to XWiki's {{macro}} syntax. For a deeper look at macro translation patterns across platforms, see Confluence to SharePoint Migration: Methods, Limits & Macro Mapping.

Link Rewriting: The Single Biggest Technical Challenge

Confluence links reference pages by title within a space or by internal ID:

<ac:link>
  <ri:page ri:content-title="Q3 Security Audit" />
</ac:link>

XWiki uses a hierarchical document reference format: [[doc:Space.ParentPage.ChildPage]]. Every internal link in every page must be rewritten during migration.

The Migrator Pro attempts this automatically, but edge cases are common:

• Duplicate page titles across spaces cause ambiguous references
• Pages with special characters in titles may produce invalid XWiki document names
• Cross-space links require the full XWiki reference path
• Anchors within pages use different syntax (#anchor in Confluence vs {{id name="anchor"/}} in XWiki)

XWiki's own reference-handling docs confirm that conversion fails when the importer does not know where the target space was migrated or does not know the page hierarchy needed to build the correct reference. (xwiki.org)

The practical approach is to build a mapping table before import:

{
  "RUN": {
    "Incident Runbook": "Ops.Runbook"
  },
  "RUN:ids": {
    "42": "Ops.Runbook"
  }
}

That example mirrors XWiki's documented link-mapping format: map by space key + page title, and use page IDs where titles are ambiguous. Build this mapping before import, then replay broken-link reports after. (xwiki.org)

For large instances (1,000+ pages), expect 5–15% of links to need manual review or a custom rewriting script.

Migrating Active Directory and LDAP Permissions

Both platforms support LDAP/AD natively, which simplifies the user migration path significantly.

LDAP authentication is the most established method for connecting XWiki to enterprise directories. The XWiki LDAP Authenticator extension supports both OpenLDAP and Microsoft Active Directory, providing username and password validation against the directory server, automatic user profile creation on first login, and group membership synchronization.

If you're interested in connecting XWiki with Active Directory you may be interested in the Active Directory Application, which is a paying application dedicated to simplifying the integration. The Active Directory Application allows you to easily connect your Active Directory server to XWiki using a visual editor, update advanced configuration settings without restarting the application server.

Permission Mapping: Confluence → XWiki

Permissions can be migrated from Confluence to XWiki using the Confluence Migrator (Pro). XWiki rights are hierarchical and more granular compared to Confluence.

The key differences:

• Confluence uses a flat space-level permission model with page-level restrictions as overrides
• XWiki uses a hierarchical inheritance model — rights set on a parent page cascade to all children unless explicitly overridden
• Confluence's VIEWSPACE maps to XWiki's view right. EDITSPACE maps to edit. SETSPACEPERMISSIONS maps to admin.
• In XWiki, some rights imply others. For instance, a user having DELETE right on a page automatically and implicitly has VIEW rights.

The practical consequence: your Confluence permission model will probably become more permissive in XWiki unless you explicitly audit and tighten the mappings during migration. Pay special attention to Confluence pages with explicit "View Restrictions" — if these are not mapped to XWiki page-level deny rules during import, previously restricted HR or financial documentation may become visible to the entire company.

Plan for a permissions review sprint post-migration.

User Migration Strategy

Do not migrate user accounts from Confluence's internal database. Instead:

1. Point XWiki at the same LDAP/AD directory Confluence uses
2. Configure group synchronization so XWiki pulls the same groups
3. Map Confluence space-level group permissions to XWiki space rights using the same group names
4. Users authenticate on first login; XWiki auto-creates their profile from LDAP attributes

This approach avoids password migration entirely and ensures your identity source of truth remains the directory.

Remember: space exports do not carry user or group objects — they appear only in full site exports. Identity setup must happen independently of content import. You do not want identity discovery happening at the same time as rights validation. (xwiki.org)

Extension and Plugin Gap Analysis

Confluence DC customers frequently depend on Marketplace plugins. Do not plan this by logo matching — plan it by behavior.

Infrastructure Planning for XWiki

The "will my infra team need to learn a whole new stack" concern is the most common objection we hear. The answer is mostly no.

An XWiki instance consists of several components: Java as the runtime environment, Apache Tomcat as the servlet container, PostgreSQL as the database, and Nginx as the reverse proxy for external access. If your team already manages Confluence DC, they already know every layer of this stack.

Sizing Guidelines

Organizations with 50 to 200 users should start with 8 CPU cores, 8 GB of RAM, and 100 GB of NVMe storage. This headroom accounts for concurrent editing sessions, search indexing operations, and the memory overhead of extensions. The additional cores allow PostgreSQL and Tomcat to handle parallel requests without contention.

For larger deployments equivalent to a Confluence DC instance serving 500+ users:

• 16+ CPU cores and 16–32 GB RAM for the XWiki application node
• Dedicated PostgreSQL instance with 8+ GB RAM and tuned shared_buffers — PostgreSQL is recommended over MySQL for better concurrent read/write performance during heavy indexing
• External Apache Solr instance for search (XWiki uses Solr, not Lucene). Ensure your storage layer has high IOPS for query performance.
• NFS or S3-backed shared storage if running multiple application nodes

Clustering for HA

XWiki provides an easy way to setup static clustered instances based on network events distribution. An XWiki cluster consists of two XWiki instances located in different servers and working with the same database. NGINX load balancer handles and shares all the users' requests to different server instances.

The clustering model uses JGroups for cache invalidation across nodes. To enable event distribution, set the property observation.remote.enabled to true in xwiki.properties. All nodes share a single database and Solr instance.

How ClonePartner Handles Confluence DC → XWiki Migrations

The XWiki Confluence Migrator Pro handles the standard case well. Where it falls short — and where teams burn weeks — is in the edge cases that dominate large, long-lived DC instances.

Here is what we bring to these migrations:

• Direct database extraction for DC instances that exceed the XML export's memory limits. We read from the Confluence schema directly and build import-compatible packages, bypassing the OOM wall entirely.
• Automated macro audit and conversion. We scan every page for macro usage, map each macro to its XWiki equivalent (or flag it as unsupported), and build conversion scripts for the translatable ones.
• Link rewriting engine. Our tooling maps every Confluence page ID and title to the correct XWiki Space.Page document reference — including cross-space links, anchors, and pages with special characters.
• Permission mapping. We translate Confluence space permissions and page restrictions to XWiki's hierarchical rights model, accounting for the inheritance differences between the two systems.
• Post-migration validation. Automated comparison of source and target: page counts, attachment integrity, link resolution checks, and rendered output sampling.

We handle the data migration layer. Your infrastructure team handles XWiki deployment and ongoing ops — which, as covered above, is a stack they already know.

For organizations navigating Atlassian's Data Center sunset timeline and weighing their options, our Atlassian Data Center End of Life 2029 guide covers all the critical milestones.

What a Workable XWiki Migration Plan Looks Like

Migrating from Confluence DC to XWiki is a real project — not a weekend task. The content translation is automatable for 80–90% of standard pages. The remaining 10–20% — complex macros, link rewriting edge cases, permission fine-tuning, and plugin gap replacements — is where the engineering time goes.

A good plan follows this sequence:

1. Proof-import one or two representative spaces first. Don't start with the biggest space. Pick one that exercises your most common macros and page structures.
2. Reconnect LDAP/AD before rights testing. Identity must be in place before you can validate permissions.
3. Inventory every macro and plugin before export. Use Confluence's Macro Usage report. Classify each into supported, partial, and redesign-required.
4. Build page-title and page-ID link mappings before import. This is the step most teams skip and most regret.
5. Validate restricted pages with real users, not admin accounts. Admin accounts bypass most permission checks. Test with users from each role.
6. Expect some workflows to be redesigned, not translated. Comala, Scroll Versions, and Jira-heavy pages need new approaches, not 1:1 ports.

The alternative is paying rising Atlassian DC license fees until March 2029, then being forced into Confluence Cloud or a rushed migration under deadline pressure. For organizations where self-hosted infrastructure is a regulatory requirement, XWiki is the strongest path forward — and starting the evaluation now gives you time to do it right.