Confluence Migration Guide: Step-by-Step to Docmost

Migrating from Confluence to Docmost is straightforward if you understand what transfers and what does not. Confluence Server reached end-of-life in February 2024, and Data Center faces the same deadline in March 2029, forcing teams to choose: pay Atlassian's rising cloud fees or move to a self-hosted alternative. This guide walks you through the complete export, import, and verification process.

Why Migrate from Confluence Now?

Your Confluence Server has already reached end-of-life. If you are still running it, you are exposed to security vulnerabilities and unsupported bugs. If you use Confluence Data Center, you face a harder choice: stay on Data Center and hit end-of-life in March 2029, or switch to Cloud and accept higher per-user costs. Neither path is appealing if you value data privacy and infrastructure control.

Atlassian's pricing for Cloud is aggressive: $5 to $7 per user per month on the Standard plan, scaling with your team. For a 50-person company, that is $3,000 to $4,200 monthly. Data Center perpetual licenses start at $17,500 and require annual support subscriptions that push the true cost higher. Self-hosted alternatives like Docmost eliminate per-user fees entirely. You pay once for hosting infrastructure, not per seat.

The 2029 Data Center deadline creates urgency now, not in 2028. Migrations take time: planning, content auditing, testing, training, and rollback readiness. Starting in 2028 or 2029 means competing for migration resources with thousands of other teams. Starting now gives you two to three years to pilot, refine, and move at your own pace. You can test Docmost with a small team first, migrate a subset of spaces as a proof-of-concept, and roll out gradually.

Docmost covers 90% of what most teams actually use from Confluence: collaborative pages, attachments, version control, full-text search, and user permissions. It is open-source (21.7k GitHub stars, 52 active contributors), runs on your own servers, and costs nothing to self-host. The migration is one-time work, but the savings compound every single year.

What Gets Transferred (The Good)

Confluence exports via XML format, and Docmost can import that XML directly. Your data is not lost; most of it transfers cleanly.

Pages and body text transfer exactly. All page titles, body content, and formatting (bold, italic, numbered lists, bullet lists, tables, links) move to Docmost without loss. A 500-page space becomes 500 pages in Docmost with identical structure and appearance.

Attachments move alongside pages. Images, PDFs, Excel spreadsheets, and other files attached to pages are included in the export and import. Docmost stores them in the same location as the pages and includes them in all backups.

User and group structure imports. Confluence spaces map to Docmost workspaces. Your user list (names, email addresses) imports into Docmost, and basic group membership translates. You will need to reset passwords or configure SSO post-import so users can log in.

Page hierarchy and nesting stay intact. Parent-child page relationships and space organization structures carry over. A deeply nested page tree in Confluence remains nested in Docmost. This matters for large documentation sites where structure is part of usability.

Internal wiki links resolve. Links between Confluence pages ([Link to Page]) work in Docmost if the target pages are imported. External URLs in your pages remain unchanged. A link to a vendor website or external documentation works exactly as before.

Full-text search indexes automatically. Docmost indexes all imported content immediately. Search queries work without additional configuration. If you search for "Q3 revenue," you find pages containing that phrase just as you would in Confluence.

What Doesn't Transfer (Prepare Now)

Not everything in Confluence survives the move. Understanding these losses now prevents frustration during or after migration.

Confluence macros are not portable. Macros (code blocks, task lists, Gantt charts, diagrams, Jira issue queries, third-party app content) are Confluence-specific plugins. Docmost does not understand them. A {code} macro showing Python syntax becomes plain text; a {jira-query} macro showing open issues vanishes entirely. You must choose: reformat manually in Docmost, accept plain text representation, or use native Markdown syntax (which Docmost supports).

Workaround: Before export, audit your high-value spaces for macro usage. Create a spreadsheet listing pages with complex macros so you know which ones need post-import review. For code blocks, if possible, reformat them as Markdown backticks before export. For Jira queries, screenshot the results and attach the image to the page. For diagrams, export them separately or recreate them in a compatible tool.

Third-party Marketplace apps and plugins do not port. Any Confluence app from the Marketplace (custom tabs, approval workflows, data integrations, analytics, reporting tools) does not exist in Docmost. If your team relies on a specific app, you must find an open-source alternative in the Docmost ecosystem, implement a workaround, or accept losing that functionality.

Workaround: Inventory every active Marketplace app you use. Document what each one does and how critical it is. Contact the app vendor to ask if they support Docmost. Many do not, but some open-source tools have Docmost integrations. Opsily's managed hosting can help you evaluate alternatives.

Nested permissions do not translate one-to-one. Confluence allows granular per-page permissions: user A can view only, user B can edit, team C cannot access at all. Docmost supports workspace-level and page-level permissions but with less nesting depth. All users with access to a workspace have read access to all pages unless you explicitly restrict specific pages to a subset.

Workaround: Design your Docmost workspace structure with this constraint in mind. If you had five permission tiers in Confluence (sensitive HR docs, finance team only, engineering specs, product team only, general knowledge base), collapse them to two or three in Docmost by using separate workspaces for highly sensitive content. Sensitive content gets its own workspace with limited members; general content is in a shared workspace.

Jira and Bitbucket integrations are broken. Confluence macros that pull Jira issue lists or Bitbucket commit logs do not work in Docmost. External links to Jira and Bitbucket remain as URLs, but live data binding is gone.

Workaround: Export Jira and Bitbucket data separately if you need a snapshot. Link to external Jira dashboards and Bitbucket repositories as URLs instead of embedding data. Accept that Docmost is a knowledge base, not a Jira replacement. The two tools work together, not as one.

Step 1: Prepare Your Confluence Instance

Before you export a single byte, prepare your Confluence environment. This step determines migration smoothness and prevents surprises.

Take a full backup first. Export your Confluence database, home directory, and attachments to a safe location. If something goes wrong during testing or the import, you need to restore quickly. A full backup takes 30 minutes to 2 hours depending on size.

Inventory your content next. List every space, sub-space, and the approximate page count in each. Audit which spaces are active (updated in the last 3 months), stale (not touched in a year), or candidates for deletion. You do not have to migrate everything; use this as an opportunity to prune dead spaces and archived projects. Migrating 20,000 pages takes longer than migrating 5,000.

Document macro usage. Use Confluence's search or audit tools to find every page containing {code}, {jira}, {table-of-contents}, {panel}, {expand}, and any custom macros. Export a CSV report of affected pages. This is your remediation list for post-import. If a page has 10 macros, you know to spend 30 minutes on it after migration.

Review permissions carefully. List every page with custom permissions (not inherited from the space). Decide if those per-page restrictions are critical in Docmost or if you can simplify to workspace-level access. If someone has edit-only access to a single financial page, is that security requirement real, or can they have broader access?

Disable third-party integrations during the migration window. Turn off any webhooks, OAuth connections, or API integrations pointing to external systems (Slack bots posting from Confluence, Zapier workflows, custom plugins). You will reconfigure them after cutover once Docmost is live.

Communicate early with your team. Tell people the migration is happening, when it starts, when Confluence goes read-only for export, and when Docmost goes live. Set expectations: "This looks different, macros are not available, but your content is here. We will provide training."

Step 2: Export from Confluence

Confluence offers two export formats: space-level XML and full-site XML. Each has tradeoffs.

Space-level export: Go to each space, Settings menu, Export option, select XML as the format. Confluence generates a .zip file containing that space's pages, attachments, and metadata. Export each space individually. This is slower if you have 50 spaces (50 exports, 2-5 minutes each), but safer for large instances: one corrupt export does not doom the whole migration.

Full-site export: Admin > Manage users > Backup and restore > Create site backup. Confluence generates one complete .zip of the entire instance in one job. This is one file, one download, one import, faster overall. But if the export fails halfway through or the file corrupts, you have to restart the entire process.

Recommendation: If you have fewer than 10 spaces, full-site export is fine. If you have 10 to 50 spaces, use full-site export but test it on a staging copy first by importing 3 to 5 high-value spaces before doing the full run. If you have 50+ spaces, export by space, testing your largest spaces first, then rolling out the rest in batches.

File size matters more than you think. A full export of a 500-person Confluence instance with 5 years of accumulated pages can reach 20 to 50 GB. The download itself takes hours, not minutes. Do this during off-hours or overnight. Docmost's import will also take time: minutes for small imports, hours for massive ones. Plan for downtime.

After export completes, verify the .zip file integrity. On Linux or Mac, run unzip -t myspace.zip to test extraction without decompressing. On Windows, try extracting a small folder to verify the archive is not corrupt. A corrupt file fails silently during import, wasting hours of waiting and troubleshooting.

Step 3: Import into Docmost

Docmost accepts XML imports and parses them into pages, attachments, and user accounts.

Set up a staging instance first. Do not import into production on your first try. Spin up a test Docmost workspace (or run a local Docker container) and import there first. Test navigation, search, and page integrity. Delete it. Then import to production with confidence.

Upload the XML file. In Docmost admin panel, go to Import > XML > select your exported .zip file. Docmost queues the import job and processes it in the background. You can close the admin panel; the import continues.

Map users when prompted. Docmost asks you to match Confluence users to Docmost users. If you already created Docmost accounts (via SSO or manual signup), select them from the dropdown. Otherwise, Docmost creates new users with temporary passwords or sends password reset links. You will send those links afterward so users can set real passwords.

Choose permission behavior. Docmost prompts: preserve Confluence permissions as-is, or default everyone to "member" (view and edit) on import? If you preserved complex per-page permissions in Confluence and want to replicate them, choose "preserve" and review the result. If you simplified permissions in Step 1, choose "member" for simplicity and adjust manually post-import if needed.

Wait for the import to complete. Docmost imports pages, generates previews, and indexes all content for search. A 10 GB export takes 30 to 60 minutes. A 1 GB export takes 5 to 10 minutes. Do not interrupt the job or restart the server. Let it finish.

Review the import log afterward. Docmost displays a summary: "20,000 pages imported, 47 pages failed, 150 macros skipped." Most failures are macros Docmost does not support; that is expected and fine. Some may be corrupted pages from Confluence; investigate those manually by checking if the source page is readable in Confluence and re-exporting if needed.

Step 4: Verify & Re-Onboard

The import finished, but the migration is not complete. You must verify everything works before cutting over all users.

Spot-check 20 random pages. Open them in Docmost. Are titles correct? Do attachments load and preview correctly? Are links between pages working? Are macros visibly removed (so you can note them for manual fixes)?

Test search functionality. Search for keywords you know exist in multiple pages. Does Docmost return the right pages? Does search ranking make sense? Is the search index fully populated?

Verify user access with real users. Have 5 people from different teams log in with their new accounts. Have them create a new page, edit an existing page, upload an attachment, and delete a test page. Check that their actual permissions match what you set.

Check space and page structure. Navigate through workspaces and page hierarchies. Is nesting correct? Are all pages visible or are some orphaned? Can you follow the same information architecture you had in Confluence?

Audit attachment integrity. Download 5 random attachments from different spaces. Open them. Verify they are not corrupted. Check file sizes match what you expect.

Train your team. Docmost UI is different from Confluence. Show people where to create new pages, how to link to other pages, how to share workspaces with new members, and how to manage permissions. Give them a sandbox workspace to experiment in without breaking anything.

Set up URL redirects if needed. If you had public wiki links (e.g., wiki.company.com/display/SPACE/Page+Title), your users will need to use new Docmost URLs. Most teams announce the new Docmost URL, update bookmarks, and let old Confluence links rot or redirect to a "migrated" landing page.

Sunset Confluence on a fixed date. Set a cutoff: after that date, no one edits Confluence; it goes read-only. A week later, turn it off entirely or archive it for audit purposes. Do not run both systems in parallel forever; it creates duplicate-editing risk and confusion.

Frequently Asked Questions

How long does a Confluence-to-Docmost migration take? Export: 1-4 hours depending on total size. Import: 5 minutes to 2 hours. User training and re-onboarding: 1-2 weeks. Total elapsed time: 2-4 weeks if you plan and test well.

Will my Jira and Bitbucket links work in Docmost? Yes, but not as embedded macros. External URLs to Jira and Bitbucket work. Live issue lists and commit logs embedded via macros are gone. You must link to Jira dashboards and Bitbucket repositories as external URLs.

Can I run Confluence and Docmost together during the transition? Yes, but it creates risk. If someone edits a page in Confluence while you are importing to Docmost, those changes do not reflect in Docmost. Best practice: lock Confluence to read-only 24 hours before export, import to Docmost, verify, then switch users over.

What happens to Confluence's Marketplace apps after migration? They stop working. Docmost does not have built-in connectors for every Marketplace app. You must find open-source alternatives or accept losing that functionality.

Do I need to pay for Docmost? Docmost itself is free and open-source. You pay for hosting infrastructure. If you self-host on your own servers, you pay for servers, backups, and DevOps time. If you use managed Docmost hosting through Opsily, pricing is based on your instance size and storage.

Is Docmost GDPR compliant? Docmost itself is a tool; compliance depends on where and how you host it. If you self-host on your own servers, you control data. If you use managed hosting, your provider's privacy policy applies. Opsily-hosted Docmost instances are GDPR compliant.

What if pages fail to import? Docmost logs all failures. Check the import report. Most failures are non-critical (skipped macros, unsupported metadata). If critical pages fail, restart the import from your backup. Confluence's XML format is human-readable; you can manually extract text and recreate important pages in Docmost.

Can I migrate back to Confluence later if I change my mind? Technically, yes. You can export Docmost as XML or Markdown and import into Confluence. But the reverse migration is harder because Docmost stores less Confluence-specific metadata. Treat the move to Docmost as permanent.

The Bottom Line

Confluence migration to Docmost is not as painful as you think. Most of your content--pages, attachments, structure--transfers directly. Macros are the main loss, but they represent a small fraction of most spaces. The real effort is re-training users and reconfiguring integrations.

The 2029 Data Center end-of-life deadline gives you breathing room to plan, test, and move deliberately. Waiting until 2028 or 2029 means competing with thousands of other teams and rushing the work. Starting now lets you validate Docmost thoroughly before full cutover. And the cost savings ($3,000-$4,200 yearly for a 50-person team) justify the migration effort.

Docmost is production-ready, open-source, and backed by a growing community. If you value data sovereignty or need to cut costs, migration is worth the effort. Explore managed Docmost hosting with Opsily to skip the infrastructure complexity and focus on your team's knowledge base.