Migrating Confluence Between Servers

This page describes how to move Confluence between physical servers. It is distinct from other functions. It does not cover database migration, application server migration, or upgrading. Atlassian suggests doing each of these steps separately. See also:

On this page:

How to Create a Test or Development Site

Administrators may need to move a Confluence site from one server to another for upgrades or downtime. This page tells you how to copy a Confluence site from one server to another. For example, you may want to transfer your current production snapshot to a test server as permitted in the licence agreement.

  • Avoid upgrades while migrating. If you are planning to switch databases, application servers or Confluence versions, firstly perform the application transfer in isolation, and test that it was successful before making other changes.
  • Development licenses are available for any Commercial or Academic license. Create one or contact Atlassian for help.

Transferring Confluence To Another Server Using The Same Operating System

If the operating systems on both servers are the same, then the home and install folders can be copied straight into an identical external database and user management setup.

  1. On the original server, create zips of the Confluence install and home directories. Copy the zips to the new server.
  2. On the new server, unzip the install and home directories. Windows users should avoid unzipping with the Windows built-in extractor, instead use Winzip or the free 7Zip.

    If you are changing the location of the home directory, open the Confluence install\confluence\WEB-INF\classes directory and edit confluence-init.properties by changing the line starting with 'confluence.home='.

  3. If you are using the EAR/WAR distribution, modify the location of your war file if need be. If using Tomcat, this is likely in /Conf/Catalina/localhost. You'll want to make sure the docbase attribute is pointing to the right location.
  4. This next step is dependent on your database: 
    • For users of the internal database, the database content is stored inside the home directory. You should switch to an external database after the transfer is successful. The internal database is for evaluation only and is not recommended for use in Production systems.
    • For external databases stored on another server: change the user account or datasource permissions so that the new server has the same network access permissions as the original. Then confirm from the new server that the hostname can be resolved and is listening for database connections on the expected port.
    • For external databases hosted locally (ie. localhost): on the original server, create a manual database backup using a native db dump backup tool. Copy the database backup to the new server.
  5. On the new server, install or upgrade the database version to match the original server.
  6. Import the database backup.
  7. Add a database user account with the same username and password as the original.
  8. Provide the database user with the full access to the imported database.
  9. Use a database administration tool to confirm that the user can login from the localhost.
  10. This step depends on your database connection:
    1. If you use JDBC (the default option) to connect to the database, to modify any database connection information, go to the Confluence home directory and edit confluence.cfg.xml. The connection URL is set under hibernate.connection.url. Ensure it does not point to your production database server.
    2. If you use a data source, follow the instructions for your database type and ensure the data source points to the new database: PostgreSQLMySQLSQL Server or Oracle.
  11. If you are using internal user management, skip this step. For users who have JIRA or LDAP integration, provide the new server with network or local access to the same hosts as the original. If this is a true test site, set up a test of your JIRA site or LDAP server so as not to disrupt production systems and change the server.xml or atlassian-user.xml files (Confluence 3.4 and below), or modify the directory settings in Confluence Admin > User Directories (Confluence 3.5 and above) to point to the appropriate test servers. Note that it might be acceptable to use a production connection here, as users won't be logging on to the test system in high volume.
  12. If appropriate, make sure no emails are sent out from the test system.
  13. If you have previously installed Confluence using the guided installer and plan on starting Confluence using the startup or start-confluence scripts in the Confluenceinstall/bin/ directory, check setenv.sh (Unix/Linux) or setenv.bat (Windows) in the same directory. If there is a JRE_HOME set, ensure that the path to the JRE is up to date in regards to the new environment.
  14. Start Confluence.
  15. Go to Administration > License Details and add your development license key. You can generate one at http://my.atlassian.com. There are more details in How to get a Confluence Developer license.
  16. If you configured Confluence as a Windows service, repeat those instructions.
  17. Add your development license key.
  18. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you perform a rebuild of your content indices after performing a migration.

Transferring Confluence To Another Server Using a Different Operating System

Migrating from Windows to Linux

You will need to replace the backslash with forward slash in the following lines in confluence.cfg.xml:

    <property name="attachments.dir">${confluenceHome}/attachments</property>
    <property name="lucene.index.dir">${confluenceHome}/index</property>
    <property name="webwork.multipart.saveDir">${confluenceHome}/temp</property>

Using database tools (preferred option)

If you are using the Production backup strategy, follow these steps:

  1. Download the proper distribution (the same one you have from your original site) from the Download Archive.
  2. Copy your Confluence home (not install) directory from your original server (even if it was a different OS).
  3. If you are changing the location of the home directory, open the Confluence install\confluence\WEB-INF\classes directory and edit confluence-init.properties by changing the line starting with 'confluence.home='.
  4. For external databases stored locally, on the original server, create a manual database backup using a native db dump backup tool.
  5. Copy the database backup to the new server.
  6. On the new server, install or upgrade the database version to match the original server.
  7. Import the database backup.
  8. Add a database user account with the same username and password as the original.
  9. Provide the user with the full access to the imported database.
  10. Use a database administration tool to confirm that the user can login from the localhost.
  11. To modify any database connection information, go to the Confluence home directory and edit confluence.cfg.xml. The connection URL is set under hibernate.connection.url. Ensure it does not point to your production database server.
  12. If you are using internal user management, skip this step. For users who have JIRA or LDAP integration, provide the new server with network or local access to the same hosts as the original.
  13. Copy server.xml, atlassian-user.xml, osuser.xml, any patches, and any other customized files velocity or properties files. If this is a true test site, set up a test of your JIRA site or LDAP server so as not to disrupt production systems and change the server.xml or atlassian-user.xml files to point to the appropriate test servers. Note that it might be acceptable to use a production connection here, as users won't be logging on to the test system in high volume.
  14. If appropriate, make sure no emails are sent out from the test system.
  15. If you have previously installed Confluence using the guided installer and plan on starting Confluence using the startup or start-confluence scripts in the Confluenceinstall/bin/ directory, check setenv.sh (Unix/Linux) or setenv.bat (Windows) in the same directory. If there is a JRE_HOME set, ensure that the path to the JRE is up to date in regards to the new environment.
  16. Start Confluence.
  17. Go to Administration > License Details and add your development license key. You can generate one at http://my.atlassian.com. There are more details in How to get a Confluence Developer license.
  18. If you configured Confluence as a Windows service, repeat those instructions.
  19. Add your development license key.
  20. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you perform a rebuild of your content indices after performing a migration.

Using XML data backups (only for small to medium sized installations)

Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There are a number of third party tools that may be able to assist you with the data migration. If you would like help in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian Experts.

If you're not yet using the Production backup strategy, you can migrate Confluence to a different server machine by creating an XML data backup as usual, and then importing that to Confluence on the new server.

  1. Create an XML data backup from Confluence as follows:
    1. Choose the cog icon , then choose General Configuration under Confluence Administration
    2. Select Backup & Restore.
    3. Check the Backup Attachments option and click Backup.
  2. Identify the version of Confluence that you are currently using. This is displayed at the bottom of each Confluence page.
  3. Download Confluence to the new server. Get the version of Confluence that you identified above, but for the operating system of the new server. You may be using either the latest Confluence version, or an older version.
  4. Install Confluence on the new server.
  5. Go to Administration > License Details and add your development license key. You can generate a license at http://my.atlassian.com. You can find more details in How to get a Confluence Developer license.
  6. Restore your XML data backup from Administration > Backup and Restore.
  7. If appropriate, make sure that no email contact can be made with the test system.
  8. Re-install any third party add-ons (including Atlassian add-ons such as Team Calendars or Questions for Confluence), and apply relevant licenses. 
  9. Some customers have experienced problems with Confluence's search functions after performing a migration, or that the content of their {recently-updated} macro is not being updated correctly. Errors in the atlassian-confluence.log file corroborate such problems. Hence, to avoid these issues, it is strongly recommended that you rebuild your content indices after performing a migration.

Ensuring no contact with production systems

To ensure no contact with external systems, you will need to disable both inbound and outbound mail services.

  1. Disable global outbound mail by running the following database query:

  2. Disable space-level mail archiving by running the following database query:

Change 'SELECT *' to 'DELETE' in the above queries once you are sure you want to remove the specified accounts.

Once this is done, you can start your test site without any mails being sent or retrieved. Think carefully about other plugins which may access production systems (SQL macro, JIRA macro, etc.). If these write content, or create unwanted load on external systems, they should be disabled promptly after starting the test site.

Migrating from HTTPS to HTTP

You may want to migrate from a server secured by SSL to one which is not secured by SSL. For example, this may be useful if you are copying a Confluence site from a production to a test site.

To migrate from HTTPS to HTTP, undo the HTTPS-specific settings that are described on this page: Adding SSL for Secure Logins and Page Security.

Notes

  • If you wish to merge two Confluence sites, you can consider using the remote import plugin. This plugin is currently not supported. The supported method would be to export a space and then import each space one by one. The two Confluence sites must be running the same version of Confluence.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport