Migrate from Confluence Cloud to Server

This page is for people who are currently using Confluence Cloud, and wish to move to Confluence Server (a self-managed Confluence site).

Not moving from Cloud to Server?

These resources will help you plan your migration from:


On this page:

Before you begin

There's a few things to understand before you begin this process. Ready to migrate?  Skip to the migration steps

Minimum Confluence version

You can migrate from Confluence Cloud to Confluence Server /  Data Center 6.0 or later only. You can't import Cloud data (either the whole site or individual spaces) into any earlier versions of Confluence.

We recommend installing either latest version of Confluence, or the latest Enterprise Release. The Confluence Upgrade Matrix will help you choose the right version for your organisation.  

Features and app availability

Some Cloud features won't be available in Confluence Server or Data Center. The navigation and user experience will also be different in some places. The core functionality of Confluence is the same however. 

Marketplace apps are not automatically migrated. When you set up your Confluence Server or Data Center site, you'll need to reinstall each of your apps. 

Not all apps are available for both Cloud and Server / Data Center. When planning your migration, we recommend you check that your essential apps are available for Server / Data Center in the Atlassian Marketplace and make a list of the ones you'll need to reinstall. 

Templates

All pages that were created from a template will be migrated. 

However, any custom templates you may have created in your Confluence Cloud site will not be migrated. You'll need to re-create your templates once your migration is complete. 

You should also be aware that the range of built-in templates (known as blueprints) is much smaller in Confluence Server and Data Center, so some of the default templates you have previously used may not be available. See the full list of blueprints

Team Calendars and Questions data

Confluence Questions and Team Calendars data can't be migrated, as there is currently no way to export this data from Confluence Cloud. 

Migration approach

You can choose to migrate your entire site in one go, or to import your team's content, space by space. 

A full site migration involves a full site export (backup), and importing this file into Confluence Server or Data Center. Users and groups are included in this export. All spaces will be migrated, including archived spaces and personal spaces. 

See Migration steps below to find out how to do this. 

A space by space migration involves exporting each space individually, and importing these files into Confluence Server or Data Center one at a time. This means you can choose which spaces you want to migrate, or migrate in stages over time.  Users and groups are not automatically migrated.  If you've connected Confluence Server or Data Center to an external user directory, or have already populated your new site with user accounts, we'll attempt to attribute content to the right people on import. 

See Import a space from Confluence Cloud if you plan to migrate your spaces one by one.

Infrastructure and database choice

Where you choose to host Confluence Server or Data Center is up to you. See Supported Platforms to find out which operating systems and databases are supported. 

You can use any database listed on the Supported Platforms page, but you don't already have a database server, we recommend PostgreSQL, which is what Confluence Cloud is run on. 

Licenses

You will need a new license to migrate to Confluence Server or Data Center. Your existing Confluence Cloud license can't be used. You can get a new license at https://my.atlassian.com. You'll also need new licenses for any paid Marketplace apps. 

Account visibility

In Confluence Cloud, people can choose not to make their profile information visible. This means when a Cloud site is imported into Server, user account information such as their full name, may not be included.

As long as you are logged in as a Site Admin when you complete the site export, email addresses will always be included, and used as the username when the user accounts are created. Users can then log in, and update their profile to provide the missing information. 

Migration steps

This page will guide you through a full site migration. See Import a space from Confluence Cloud if you plan to migrate your spaces one by one. 

Step 1: Check your apps

To check your apps are compatible:

  1. In Confluence Cloud, go to Settings > Manage Apps
  2. Make a note of all User-installed apps. 
  3. Go to https://marketplace.atlassian.com and look up each app to see if a Server or Data Center edition is available. 

Step 2: Install Confluence Server or Data Center

The way you do this depends on whether you're migrating to Server or Data Center, and how you plan to host the application. 

See Confluence Installation Guide for links to all the installation options.  

Step 3: Export your Confluence Cloud Site

To export your Confluence Cloud site:

  1. Log in to Confluence Cloud as a Site Admin
  2. In Confluence Cloud, go to Settings > Backup Manager
  3. Follow the prompts to back up the site, and download the XML file. 

The file will include all spaces and pages (including attachments), and all your users and groups. 

Step 4: Import your Confluence Cloud site export file

Unless your site export file is quite small (less than 25mb) we recommend importing via the home directory method.  

The import will overwrite all spaces, pages, and user accounts in your site - including your administrator account. You'll recover that account in the next step.

You should back up your database, home directory, and installation directory before you begin, in case you need to roll back.

To import a site from the home directory: 

  1. Copy your export file to <confluence-home>/restore. 
    (If you're not sure where this directory is located, the path is listed in the Backup and Restore screen)
  2. Go to 

    Error rendering macro 'excerpt-include'

    User 'null' does not have permission to view the page.

     > Backup and Restore
  3. Select your site export file under Import from home directory
  4. Make sure Build Index is checked so that your index is created automatically.
  5. Choose Import.

See Restoring a Site for more information about the import process. 

Step 5: Recover sys admin permissions

When you import a site export file, all user accounts are overwritten, including the system administrator account that was created when you installed Confluence. Your existing Cloud Site Admin account will not automatically have system administrator permissions for Confluence Server or Data Center. 

To recover system administrator permissions:

  1. Stop Confluence.
  2. Edit <installation-directory>/bin/setenv.sh or setenv.bat and add the following system property, replacing <your-password> with a unique, temporary password. 

    -Datlassian.recovery.password=<your-password>


    See Configuring System Properties for more information on using system properties.

  3. Start Confluence manually (don't start Confluence as a service).
  4. Log in to Confluence with the username recovery_admin and the temporary password you specified in the system property. 
  5. Go to 

    Error rendering macro 'excerpt-include'

    User 'null' does not have permission to view the page.

     > User Management > Add Users.
  6. Enter the details for your new system administrator account and hit Save. Make sure to use a strong password. 
  7. Choose Edit Groups and select the confluence-administrators group. This is a super-group that has system administrator permissions. 
  8. Log out, and confirm that you can successfully log in with your new account.
  9. Stop Confluence. 
  10. Edit <installation-directory>/bin/setenv.sh or setenv.bat and remove the system property. 
  11. Restart Confluence using your usual method (manually or by starting the service). 

See Restore Passwords To Recover Admin User Rights for more information on this process. 


Step 6: Install any apps

To re-install your apps:

  1. Log in to Confluence Server or Data Center as an administrator.
  2. Go to 

    Error rendering macro 'excerpt-include'

    User 'null' does not have permission to view the page.

    .
  3. Follow the prompts to search for or upload the apps you identified in step 1.  You'll need to purchase new licenses for these apps. 

Remember that Team Calendars and Questions data is not included in your export, and cannot be migrated from Cloud at this time. 

If you had multiple Cloud products, such JIRA Software, you may need to make some changes to the application links. 

To remove or update application links:

  1. Go to 

    Error rendering macro 'excerpt-include'

    User 'null' does not have permission to view the page.

     > Application Links.
  2. Follow the prompts to check and update any application links that are now pointing to the wrong place. 

If you're unable to remove the Jira Cloud application link from your Confluence after the import, you'll need to remove those references directly from the Confluence database. See Alternative Methods of Deleting Application Links in Confluence.


Troubleshooting

There are a few known issues that you might encounter when importing your Cloud site. 

Can't load pages in your new site

If you experience problems loading pages after the import, head to 

Error rendering macro 'excerpt-include'

User 'null' does not have permission to view the page.

 to check your base URL as the port may have changed. 

User management admin screens are missing

This is a fairly uncommon problem caused by a dark feature flag that is included in your Cloud site export file. See CONFSERVER-35177 - Getting issue details... STATUS  for a workaround.

Jira issues macros are broken

If your Confluence Cloud site has macros that depend on the Application Links back to a Jira Cloud instance, and you are migrating Jira as well, these references will need to be updated to work properly. See Unable to locate Jira server for this macro. It may be due to Application Link configuration.  for a workaround. 

You can also edit the XML file prior to importing it into Confluence Server or Data Center, or by bulk editing those references in Confluence database. See How to bulk update JIRA Issue Macro to point to a different JIRA instance .

User mentions are broken

When a page with user mentions is migrated from Confluence Cloud to Confluence Server or Data Center using either site or space migration, the mentions display as "broken link". For a Cloud-to-Cloud migration via Confluence Data Center, the mentions display as "@unlicensed user". See CONFSERVER-79583 - Getting issue details... STATUS  for the workaround.

Broken anchor links

Confluence Cloud replaces anchor macros with web links that are not compatible with Data Center versions after migration. See CONFSERVER-79006 - Getting issue details... STATUS for the workaround.

Users' favourites (starred pages, or saved for later) are missing

If you find that some of your users' favorites (pages saved for later) are missing due to CONF-36348 - Getting issue details... STATUS . See How to restore missing favorites after import from XML for more information.

Full-width space templates cause failed or incomplete space imports

If you import an XML space from Confluence Cloud containing space templates with the full-width property it will result in a failed import, or only a partial import. See CONFSERVER-80146 - Getting issue details... STATUS  for a workaround.

Some user accounts are missing or created without user details

Users in Confluence Cloud have the ability to change their profile visibility settings. To ensure all user data is included in the export, ask a site admin to perform the export.

Last modified on Feb 16, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.