Page tree
Skip to end of metadata
Go to start of metadata

This page describes how to upgrade JIRA installations that don't support the rapid upgrade method or fallback method. You should use this method to upgrade JIRA if you meet any of the following criteria:

  • You use a WAR distribution of JIRA version 4.0.0 or later.
  • You use JIRA 4.0.0 or later on Solaris.
  • You use JIRA 4.0.0 – 4.2.x on Windows or Linux.

See Upgrading JIRA Manually for more information on the methods you can use to upgrade JIRA.



1. 시작하기 전에

  • Read about the new version - Review the release notes and upgrade notes for the version of JIRA that you are upgrading to. See Production Releases. If you plan to skip a few JIRA versions during your upgrade, we strongly recommend that you read the upgrade guides for all major versions between your current version and the version to which you are upgrading. Refer to Important Version-Specific Upgrade Notes for quick links to these guides.
  • Check your license - Verify that your license support period is still valid.
  • Check for known issues - Use the JIRA Knowledge Base to search for any issues in the new version that will affect you.
  • Check for compatibility:
    • Confirm that your operating system, database, other applicable platforms and hardware still comply with the requirements for JIRA 7.1. The End of Support Announcements for JIRA page also has important information regarding platform support for future versions of JIRA.
    • If you have installed JIRA plugins (i.e. not included with JIRA), verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information from the the plugin's home page on the Atlassian Plugin Exchange.

Some anti-virus or other Internet security tools may interfere with the JIRA upgrade process and prevent the process from completing successfully. If you experience or anticipate experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before proceeding with the JIRA upgrade.


We strongly recommend performing your upgrade in a test environment first. Do not upgrade your production JIRA server until you are satisfied that your test environment upgrade has been successful.

  • If you have any problems with your test environment upgrade which you cannot resolve, create an issue at our support site so that we can assist you.
  • If you have any problems during the upgrade of your production JIRA server, do not allow your users to start using this server. Instead:
    • Continue to use your old JIRA server — this will help ensure that you do not lose production data.
    • Also create an issue at our support site so that we can help you resolve the problems with your upgrade.


2. 백업하기

Before you begin the JIRA upgrade, we strongly recommend that you back up your existing JIRA installation.

2.1 사용자가 JIRA 데이터 업데이트 하지 못하도록 하기

During the upgrade process, you'll export JIRA's database from your existing JIRA installation (via an XML backup) and then restore this backup into a new JIRA installation. To ensure that the data in the XML backup is consistent with the latest data in the system, you must temporarily restrict access to JIRA so users can't update the data. Refer to the upgrade_Backup page for more information.

(warning) Be aware! Inconsistent XML backups cannot be restored!

2.2 데이터베이스 백업

Perform an XML backup of your existing JIRA installation's external database. For large JIRA installations, this process may require several hours to complete.

The 'embedded database' is the HSQLDB database supplied with JIRA for evaluation purposes only. If you accidentally use the HSQLDB database in a production system, perform an XML backup of this database and continue on with this procedure.

2.3  JIRA Home directory 백업하기

  1. Shut down JIRA.
  2. Locate the JIRA Home directory. You can find information about the location of the directory by navigating to the <jira-application-dir>/WEB-INF/classes/ file in your upgrade_Backup. Alternatively, you can open the JIRA Configuration Tool to see the directory that is set as your JIRA Home.
  3. Navigate to the directory specified in the configuration file and create a backup of it in another directory.

2.4 첨부 및 인덱스 디렉터리 백업하기 (JIRA Home 디렉터리 밖에 위치한 경우)

If the attachments and index directories are located outside of your upgrade_Backup, you must back them up separately. These pages describe how to find out where these directories are located in your implementation:

  • Your attachments directory — Refer to upgrade_Backup page in the documentation for your version of JIRA.
  • Your index directory — Refer to upgrade_Backup page in the documentation for your version of JIRA.

Also refer to upgrade_Backup for more information about backing up attachments in JIRA.

2.5 JIRA 설치 디렉터리 백업하기

The 'JIRA Installation Directory' is the directory into which the JIRA application files and libraries were extracted when JIRA was installed.



3. 새로운 JIRA 설치 셋업하기

If you are running a 'mission-critical' JIRA server, we highly recommend performing the remaining steps of this guide in a test environment (e.g. using a separate test JIRA database and a copy of your JIRA Home directory) before performing the upgrade in production.  

3.1 JIRA의 새로운 버전 설치하기

Download and extract the JIRA distribution you require to a new directory. Do not overwrite your existing JIRA installation. Ensure this has been shut down and install the new JIRA version to a new location.

Follow the installation instructions for either:

(info) If you are using JIRA WAR, remember to build your new JIRA web application and deploy it to your server. For specific instructions, refer to the JIRA WAR installation page for your application server within the Upgrading JIRA Manually section.

3.2 새로운 JIRA를 기본 JIRA Home directory (복사본)을 가리키도록 설정하기


If your new JIRA 7.1 installation is on a new server, copy the backup of your existing JIRA Home Directory from the old server to the new server before proceeding.

To set up a "recommended" (not WAR) distribution:

  1. Open the JIRA Configuration Tool.
  2. Click the JIRA Home tab.
  3. Update the JIRA Home Directory field:
    • If your JIRA 7.1 installation is on a new server, update the JIRA Home Directory field to the path of your copied JIRA Home directory.
    • If your JIRA 7.1 installation is on the same server, update the JIRA Home Directory field to the path of your existing JIRA Home directory.
      (info) For more information about this directory, see upgrade_Point JIRA to JIRA Home.

To set up a WAR distribution:

  1. Edit the file located within the <jira-application-dir>/WEB-INF/classes subdirectory of your new JIRA 7.1 Installation Directory upgrade_Point JIRA to JIRA Home.
  2. Update the jira.home property in this file to the path of the new JIRA Home Directory:
    • If your JIRA 7.1 installation is on a new server, update the jira.home property to the path of your copied JIRA Home directory.
    • If your JIRA 7.1 installation is on the same server, update the jira.home property to the path of your existing JIRA Home directory.
      (info) For more information about this directory, see upgrade_Point JIRA to JIRA Home.
  3. Remove the '#' at the beginning of the jira.home line (so that JIRA no longer regards this line as a comment).
  4. Save your updated file.

(tick) You can also set your JIRA Home Directory's location by defining an operating system environment variable JIRA_HOME. This value of this variable takes precedence over the value of the jira.home property in the file in your upgrade_Point JIRA to JIRA Home. See upgrade_Point JIRA to JIRA Home for details.


3.3 새로운 JIRA 버전을 새로운 빈 데이터베이스와 연결하기

Create a new, empty database that your new JIRA installation will use to store its data.

Follow the appropriate 'Connecting JIRA to...' instructions for your database from stage 2, although from stage 4 of that procedure, be aware of the yellow note below:

If you are using a database (called jiradb, for example) with your existing JIRA installation and the database for your new JIRA installation is running on the same machine or database server, create your new database with a different name (e.g. something intuitive like jiradb_440 for JIRA 4.4.0). However, ensure the new database has identical access permissions to the old JIRA database. Consult your database administrator if you need assistance with this.

(info) You do not need to create a new database if you are using the embedded HSQL database.


3.4 기존의 JIRA 설정을 새로운 JIRA 설치버전에 반영하기

If you have modified properties in configuration files of your existing JIRA installation, make the same modifications in your new JIRA installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.

For each file you have modified in your existing JIRA installation, you need to manually edit each equivalent file in your new JIRA installation and re-apply your modifications. If a file is not present in your new JIRA installation (for example, osuser.xml in recent JIRA versions), then simply copy that file over to your new JIRA installation.

The table below lists the most commonly modified files and their locations within your upgrade_Migrate JIRA configs:


'recommended' (이전의 'Standalone') JIRA 배포본에서의 위치

JIRA WAR 에서의 위치




Location of the upgrade_Migrate JIRA configs and Advanced JIRA Configuration in JIRA 4.3.x and earlier.

Any custom property values defined in the file of your existing JIRA 4.3.x (or earlier) installation must be migrated across to the file of your new JIRA 7.1 installation before you start your new JIRA installation.

Upon starting your new JIRA installation, any custom property values in the file will automatically be migrated across to either the JIRA database or file. jira.home is the only property of the file subsequently used by JIRA.

setenv.bat (Windows) or (Linux)


Application server's bin directory

upgrade_Migrate JIRA configs

(not required if upgrading from JIRA 4.3.0 or later)



Modified if you have integrated LDAP with JIRA, integrated Crowd with JIRA, or if you are using a custom form of external user management or user authentication.




Modified if you have integrated Crowd with JIRA.



Application server's conf directory

Modified in the following situations:

(tick) The version-specific upgrade notes contain details on properties which may have changed in these commonly modified files.

In addition to the files above, you should also consider and/or perform the following configurations as part of the upgrade process:

  • Using JIRA with Atlassian's Crowd? — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
  • Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA memory.
  • Plugins — For any plugins that you had installed in your old JIRA, download the plugin version for your new version of JIRA from the site.
  • Character encoding — Ensure that character encoding (i.e. locale) is the same on the new and old locations. Your new version of JIRA may not function correctly if attachments are moved between two system with incompatible encoding.
  • Customisations — If you had made any customisations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organisation who made the customisations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your upgraded JIRA installation.)
  • (Optional) Running JIRA on a different port — If your new JIRA is installed on the same machine as your old JIRA, you may wish to make sure it runs on a different port (in case you ever need to restart your old JIRA). See Changing JIRA's TCP Ports for details.


3.5 새로운 JIRA 버전 시작하기

  1. Verify that your old JIRA installation is shut down — if this JIRA server is still operating, shut it down.
  2. If you installed the JIRA WAR distribution within Tomcat, delete the Tomcat work directory before restarting JIRA. If you do not do this, users may encounter errors when they try to display JIRA pages.
  3. Start up your new version of JIRA. For:
    • 'Recommended' distributions — follow the Starting JIRA instructions.
    • WAR distributions — follow the instructions for starting JIRA for your application server within the upgrade_Start new JIRA version section.
      (info) During the startup process, your new JIRA installation will create any required database indexes. If you created any custom database indexes, please check them afterwards and remove any that duplicate the indexes added by JIRA.

Do not restart your old JIRA installation...

If your new JIRA 7.1 installation is on the same server as your old one, it may still be configured to use the same JIRA Home directory as your new JIRA installation. Running two separate JIRA installations which share a common JIRA Home directory can lead to serious data corruption.

Nevertheless, we recommend that you do not delete any aspect (or backed up component) of your old JIRA installation, until you are satisfied that your upgraded JIRA installation is functioning as expected.

3.6 Import your old JIRA data into your new JIRA

After you have started your new JIRA installation, import the data from your old instance into the new instance. You will need the backup file of data from your old JIRA that you created earlier in these instructions (above).

To import your old JIRA data into your new JIRA:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Select Administration > System > Import & Export > Restore System (tab) to open the 'Restore JIRA data from Backup' page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'rest'
  3. In the File name field, specify the XML backup file you created previously during the export process (above). That zipped file should contain two xml files: activeobjects.xml and entities.xml. Both of these files must be included in the zipped file for the import process to work.
  4. Restore the attachments directory that you backed up previously, into the attachments directory of your new JIRA. (See upgrade_Import old JIRA data.)
    (info) Avoid passing through a proxy when performing an XML restore, especially if your JIRA instance is very large. Using a proxy may cause timeout errors.
  5. Access JIRA via your web browser again and log in using a username from your previous JIRA installation.
  6. Take a quick look around your JIRA site to confirm that your projects and issues are present and everything looks normal. You should see the new JIRA version number in the page footer.


4. 업그레이드후 체크사항 및 작업

새로운 JIRA를 구동한 후에는 다음의 체크사항 및 작업을 수행할 것을 권장합니다.

  1. JIRA가 정상적으로 동작하는 것처럼 보여도, server logs에 에러메시지가 있는지 여부 확인하십시요. 해결할 수 없는 에러가 발생한 경우 로그파일과 함께 https://support.atlassian.com으로 기술지원 요청하십시요.
  2. 이전에 External User Management를 사용하였다면, 새로운 JIRA 에서도 사용설정하십시요.
  3. 업그레이드 하면서 서버하드웨어를 변경하였다면, 인덱스, 첨부, 백업 디렉터리 경로를 JIRA의 관리자 항목에서 확인하고 필요한 경우 변경하십시요.
  4. 테스트 기간동안 메일을 사용중지하였다면, 메일을 사용설정하십시요.
  5. 과거의 JIRA에서 새로운 JIRA로 이전을 한 경우, 테스트가 충분한지 확인하십시요.
    1. 새로운 JIRA에 대한 플러그인을 개발하였다면, 새로운 JIRA 버전으로 다운로드한 JAR 파일을 설치 하시고 플러그인을 위한 다른 요구사항이 있는지 확인하십시요.
    2. 플러그인이 속성파일을 가지고 있다면, 과거의 속성파일의 변경사항을 동일하게 새로운 속성파일에 적용하십시요.
  6.로 로그인
    1. 적절한 라이센스 정보 확인.
    2. Server ID를 새로운 production Server ID로 수정하고 저장.
    3. 새로운 서버에 production 라이센스 업데이트.

Congratulations! You have completed your JIRA migration/upgrade.


Disabling Auto-Export
Restoring Data
Upgrading JIRA
Switching Application Servers to Apache Tomcat
Switching Databases




  • No labels