This page last changed on Feb 21, 2007 by rosie@atlassian.com.

This document outlines the procedures you need to follow to upgrade from one version of Confluence to another. You can download the latest version of Confluence from here.

Before you begin
Always check the release notes for the version of Confluence you are installing for upgrade instructions specific to that version.

Step One: 1. Backing up

We strongly recommend that you backup your Confluence home and install directories. If you are using an external database, you should perform a manual database backup before proceeding.

Things you need to backup

  • Confluence Home Directory
  • Your database - If you are not using the embedded database
  • osuser.xml - If you running Confluence 2.0 or earlier and have your user management delegated to JIRA or any other user management system.
    The osuser.xml file is located in the WEB-INF/classes directory.
  • server.xml- If you are running Confluence Standalone, and have modified your server.xml file (for example to add a datasource).
    The server.xml file is located in the Conf directory.
  • WEB-INF/lib directory - If you have deployed any themes, macros or other plugins.


Step Two: Things you need to check ...

  • Check out the Configuration Guide for your application server and database, to make sure there isn't anything extra you need to do to get Confluence running
  • Especially, Resin 3 users should remember they need to update web.xml

Step Three: Performing the upgrade

Please note, if you are upgrading from a 1.x version to a 2.x version of Confluence, you must use Method Two.

There are two ways to perform the upgrade:

Method One

Pointing the new webapp to existing Confluence home
  1. unzip the new release
    If you have downloaded the WAR version and are using Tomcat, you need to update either your confluence.xml or server.xml to point to the location of the new version. Else, if you have deployed Confluence by copying it to your Tomcat webapps directory, please do not copy the new version over your existing install, as this may cause old files from previous versions to be left behind causing unpredictable problems. Instead, remove the old version first from webapps and then copy the new one in.
  2. change the confluence-init.properties file to point to your existing confluence home directory (make sure you've already backed this up)
  3. if you are not using the embedded database, remember to copy over the jdbc driver jar. In a stand-alone configuration, it needs to go in confluence-X.Y.Z-std/common/lib.
  4. restart the application server
    This method is the most convenient and will allow you to reuse your existing Confluence home directory and database.

Method Two

Exporting and Restoring to a Brand New Instance
  1. From Confluence, go to Administration -> Backup & Restore and create a manual backup that includes attachments.
  2. Create the new, separate install directory. We recommend including the version number in the install directory ie ..\confluence<VERSION> and that users avoid putting spaces in the install path. Windows users may wish to use C:\confluence\conf2.2.0 (set it to the version you downloaded).
  3. Download the Confluence standalone version and setup a new installation of Confluence, create a new clean database and proceed with setup wizard.
  4. when asked to restore existing data, specify the backup created in step 1
  5. if you have made modifications to your osuser.xml file, this is the time to shutdown your confluence instance, copy the osuser.xml file into the WEB-INF/classes directory and start up Confluence.
    • If you are unsuccessful with upgrading using the first method outlined above, you may give this approach a go. Occasionally, starting afresh will fix the problem.
    • If you are upgrading from a version older than 2.0, we recommend using this method to obtain significant performance improvements from indexes we added in the 2.0 release (these indexes will not get added if you upgrade using the first method)


Post-install Notes

  • If you have delegated user management to JIRA and are running Confluence 2.0 or earlier, read the release notes to see if osuser.xml has been updated. If it has, you will have to move your changes over from your old osuser.xml to the new one or copy your old osuser.xml into the WEB-INF/classes directory and just override the one there.
  • Remember to restore the server.xml or plugin jar files you backed up earlier.
  • If you have previously installed Confluence/Tomcat as a Windows service, you may have to uninstall and reinstall the service, as described here.
  • If you're using AtlassianUser LDAP integration, remember to copy over your old atlassianUserContext.xml file over to the confluence/WEB-INF/classes in the new version.
  • You should re-download the latest version of each plugin you are using from the Confluence Extension space
RELATED TOPICS


Upgrade (text/xml)
Upgrade (text/xml)

Which osuser.xml file... atlassian-jira/WEB-INF/classes/osuer.xml or confluence/WEB-INF/classes/osuer.xml?

Posted by at Jun 10, 2004 15:55

existing confluence home directory == the home directory you were pointing to in the previous version of Confluence you were using. The idea is that you use the same home directory, even after you upgrade.

The home directory contains among other things a config file that stores information collected when you first set up Confluence using the wizard. As a result, you don't have to go through this setup process again when you upgrade if you point Confluence to this directory.

Posted by dave@atlassian.com at Jun 16, 2004 22:30

The (avoid copying over your existing install) comment is what threw me off. You can make a backup of your confluence webapp, but you do need to copy over the existing webapp to avoid the mysql driver missing problem.

Posted by at Sep 17, 2004 01:08

yes

Posted by at Sep 17, 2004 01:09

I would still avoid copying over an old installation, or you could end up with old Jars and config files lying around that are either unused or cause problems. The better way is to keep track of the jars you have added and copy them over when you upgrade. Alternately, you can put them in the 'shared library' space on your webserver (on Tomcat it is the '/common/lib' dir under the Tomcat installation directory). I've done this with my JDBC driver.

Posted by david@randombits.org at Dec 20, 2004 00:21

If you're using Resin 3, you also have to update web.xml - Running Confluence on Resin 3.x

Posted by ben@walding.com at Oct 08, 2005 17:10

I've upgrade from confluence 1.4.4 to 2.0, but it seems that when I edit a page, the "page resitriction"  and "label edit" cannot function well. I hit the button but get no response. Could you tell me how to resolve?

Posted by nybon at Nov 18, 2005 21:13

This is probably related to a missing library in JDK 1.5. Please have a look at the Release Notes for Confluence 2.0 where we point out the problem with JDK1.5

Cheers,
Jens

Posted by jens@atlassian.com at Nov 20, 2005 22:48

Could a bit more detail be given on the steps for upgrading when user management is being done by JIRA? I've tried a clean "backup-restore" upgrade from 1.4.2 to 2.0 and it has not gone well. (some pages render, some do not, even though they are listed - also the themes appear to be messed up)

Posted by ahayes@gcrc.carleton.ca at Nov 21, 2005 11:24

The only difference in the process when you have JIRA user management enabled is that you must copy your modified osuser.xml file to the upgraded Confluence installation.

Any problems you are having with viewing content are most likely unrelated to JIRA user management – you should open a support request on http://support.atlassian.com, preferably attaching the backup that was not restoring successfully to the issue so we can test it locally. Once we find out what the problem is, we'll be able to update the documentation to ensure it doesn't happen to anyone else.

Posted by cmiller at Dec 06, 2005 00:49

There is no mention of what to do if you are running it as an XP service - that would be helpful to include here.

Thanks

Posted by donald.thompson@microsoft.com at Dec 08, 2005 09:40

Thanks Donald, I've added that to the "post-install" section.

Posted by jeremy@atlassian.com at Dec 11, 2005 23:55

if use reins,don't forgot update web.xml

Posted by scud at Dec 20, 2005 04:41

In Method Two, Step 2 above, what does this mean: "unpack a new webapp, create a new clean database" ????

Posted by djsmitherman at Apr 24, 2006 16:35

Please refer to the updated documentation. If the documentation should still not be clear enough about the procedure, please let us know about it.

Cheers,
Jens

Posted by jens@atlassian.com at Apr 27, 2006 23:51

Hi,

I upgraded from 2.1.3 to 2.2.8 following the instructions and when I restarted Confluence the homepage looks like this:
Where do I start?

All content in Confluence is organised into spaces. So to start browsing content, simply click on one of the spaces listed below.

Error rendering macro: org.springframework.jdbc.BadSqlGrammarException: Bad SQL grammar in task 'Hibernate operation'; nested exception is java.sql.SQLException: Column not found: S.SPACETYPE in statement select distinct s.SPACEID as SPACEID0_, s.SPACENAME as SPACENAME0_, s.SPACEKEY as SPACEKEY0_, s.SPACEDESCID as SPACEDES4_0_, s.HOMEPAGE as HOMEPAGE0_, s.CREATOR as CREATOR0_, s.CREATIONDATE as CREATION7_0_, s.LASTMODIFIER as LASTMODI8_0_, s.LASTMODDATE as LASTMODD9_0_, s.SPACETYPE as SPACETYPE0_ from SPACES s, CONTENT_LABEL lc, LABEL l where s.SPACEDESCID = lc.CONTENTID and lc.LABELID = l.LABELID and (l.NAME = 'favourite' OR l.NAME = 'favorite') and l.OWNER = ? and l.NAMESPACE = 'my'

Add Space Create a space - share information with your team.

This is just using the embedded database. I pointed the new version's home dir to my old homedir, updated the registry for the NT service and kablooey!

Posted by kelsey at Aug 10, 2006 14:58

Please open a support request at http://support.atlassian.com and attach your log files.

Thanks,
Tom

Posted by tom@atlassian.com at Aug 10, 2006 15:12

Under Post-install notes where it says

If you're using AtlassianUser LDAP integration, remember to copy over your old atlassianUserContext.xml file over to the confluence/WEB-INF/classes in the new version.

the filename should be atlassian-user.xml and not atlassianUserContext.xml

Posted by sudhakar@co.brazos.tx.us at Aug 10, 2006 21:31

In regard to backup Method 1, If we point to the previous doc base for all future versions can we rename the directory to something more generate remove the reference to a particular version?

Posted by rwagner at Aug 16, 2006 14:21

Ooops! I meant generic not generate.

Posted by rwagner at Aug 16, 2006 14:23

Ross,

If you are referring to the Confluence home directory, then yes, you can make it more generic. The home directory does not have to indicate the version of Confluence it is associated with.

Cheers,
Dave

Posted by dave@atlassian.com at Aug 16, 2006 18:26

I believe "If you're using AtlassianUser LDAP integration, remember to copy over your old atlassianUserContext.xml file over to the confluence/WEB-INF/classes in the new version." should refer to atlassian-user.xml instead.

Posted by bob.swift@lakeviewtech.com at Sep 17, 2006 07:23

I followed method 1 to upgrade from 2.1.5a EAR/WAR deployment w Postgresql.

After restarting Tomcat, the Admin-->System Information still shows me running 2.1.5a

 It seems to me that the docBase attribute in the confluence.xml file should be updated to point at the new version, but that is not explicitly stated in the upgrade info above, and is way down in the "Installation" info on the linked page. Is this a missing step for the upgrade?

Thanks

Steve

Posted by steven.peacock@thesolutiondesigngroup.com at Oct 18, 2006 14:49

Hi Steve,

You're correct. We've updated the document to make this clearer for people using the WAR version.

Thanks,
Dave

Posted by dave@atlassian.com at Oct 26, 2006 20:01

Hi, I just upgraded to Confluence 2.3 from 2.2.10 with DB2 running as external DB. Problem is, that the class com.atlassian.util.DB2Dialect was renamed to com.atlassian.hibernate.dialect.DB2Dialect.

After I changed that in my (old) confluence.cfg.xml the update worked for me.

Another problem: Errors concerning this issue were only visible after I reconfigured log4j to use ConsoleAppende, not RollingFileAppender.

Jan

Posted by jstrohbehn at Jan 17, 2007 01:53

Thanks for that Jan. We are aware of the issue with log4j as the necessary lines have not been uncommented to provide appropriate logging messages. Also thankyou for pointing out the other problem with DB2 dialect. I have filled a bug report for that in JIRA already. Please see CONF-7690 to follow the progress there.
Ib

Posted by ivan@atlassian.com at Jan 17, 2007 21:50

Hi

I'm currently running Confluence 2.2.9 and attempting to upgrade it to 2.3.1.

The 2.2.9 installation was configured to authenticate against our Active Directory. This was done by replacing the atlassian-user.xml with the "hibernate" version, browsing to the /admin/osuser2atluser.jsp URL and doing the migration process. I then replaced the atlassian-user.xml file with a version of the ldap_hibernate file, with changes specific to our local AD settings.  I then installed a bunch of plug-ins, made lots of spaces and then we poured a lot of content into it, and all was fine...

I'm now trying to upgrade from 2.2.9-std to 2.3.1-std, and having problems.  I'm trying to use Method 1.

To wit:  I've cloned our Confluence machine, downloaded 2.3.1-std, unpacked it, edited the confluence-init.properties file and pointed confluence.home at the existing data directory.  I then copied in the MySQL java connector.

I start confluence and can then log in as "admin". I can see spaces and bring up the Repository client etc and see the plug ins.  I had a problem with "Builder", which wasn't listed as installed, and which I could only re-Buy. This was remedied by uninstalling it, and then installing it again.

I went to Admin -> Manage Users and it lists only the local users.  This struck me as strange, as I assumed that the users would be located in the database, so oughtn't they appear?  I tried stopping confluence, copying my customised atlassian-user.xml file and restarting confluence.  It crashes upon start up.  I replace the original atlassian-user.xml file and it's fine.

I've tried to re-do the migration process with the hibernate file mentioned above, but that doesn't work. 

The logs/atlassian-confluence.log contains gory stack traces and errors regarding plugins. 

The Builder site advises uninstalling plug ins before upgrading confluence, but uninstalling them from 2.3.1-std doesn't seem to be working too well.  Is uninstalling plugins prior to upgrading something which Atlassian would recommend?

Should I go back to 2.2.9, uninstall all the extras, and try this again? 

Should I give up on option 1 and try option 2 instead?  

 cheers

andy 

Posted by andyjones at Feb 12, 2007 20:22

Hi Andy,

you should probably open a issue at http://support.atlassian.com. Let us know there the details you gave above and attach the content of you confluence logs directory (zipped). Someone will then come back to you as soon as possible.

Thanks,
SaM

Posted by sleberrigaud at Feb 13, 2007 16:35
Document generated by Confluence on Mar 22, 2007 20:59