Today we were forced to transfer all our services from one server to another.

One of those services is Jira.

From what I have seen, there is no good documentation on our to migrate an instance of Jira from one Ubuntu server to another. Yet it is actually not that complicated.

Step 1. Make sure your current instance is not running

In order to avoid changes that would not make it to the new instance, make sure to stop Jira in the existing system. If you can, just stop Apache2 or whatever front end you are using.

Step 2. Copy the Data

Jira saves data in two locations: your database and /var/atlassian/application-data/jira/*

The database is generally used to save all the issues and comments. The application data folder is used to save attachment and alike. It also saves information about the Jira installation such as how to connect to the database.

We use PostgreSQL pg_dump, but any dump function for your database will do.

To make sure, because there are some setups in the conf directory (in most cases the defaults do not work.) You also want to get a copy of the /opt/atlassin directory. That way you will get everything the same. If you want to upgrade later, you can always do that, just make sure to keep a copy of all the backups...

pg_dump -Fc -f database-dump.pgsql jira
tar czvf jira-data.tar.gz /var/atlassian/application-data/jira/
tar czvf jira-app.tar.gz /opt/atlassian/jira

Note: tar will give you a warning about the fact that it does not want to save the leading '/' in the tarball. That's normal and it still creates a valid tarball.

The two tarball require you to be root. This is important to capture all the file permissions and ownership.

Step 3. Transfer to new server

Now you can transfer the files to the new system and restore the data. On my end, I created a new ssh key (see ssh-keygen) and copied the public key on the other side, in the autorized_keys file, then used scp as in:

scp database-dump.pgsql 1.2.3.4:.
scp jira-data.tar.gz 1.2.3.4:.
scp jira-app.tar.gz 1.2.3.4:.

On my end I also have a file to start jira. It was /etc/init.d/jira, but now we converted that to systemd. Either way, you need such a file if you want to auto-start/stop the process. Thus I copied that file on the end too.

Finally, I have an apache configuration file: jira.conf. So I copied that too.

Step 4. Restore on new server

This step is about restoring the content of your files.

WARNING: It is important to note that the jira application is expected to be run by a specific user which needs to be created on the new platform if it does not exist there yet. It has to be done first or the tar x command won't work right.

The stand alone files (jira.conf for Apache2 and the init.d file) can simply be copied where they need to be. Also make sure to setup their ownership and permissions correctly so they work as expected.

The jira data and application can be extracted using tar from / and while you are root. It is important to be root to restore all the ownership and permissions properly.

Since both got files from the root directory, you have to extract from there, so:

sudo su -
cd /
tar xf ~me/jira-data.tar.gz
tar xf ~me/jira-app.tar.gz

If you prefer, you can use the -C command line option instead of the cd /.

For the database, you can just run a restore command. You may need to create the database first, especially if you use a specific user (i.e. you would have to create that user too.) With PostgreSQL, something like this:

psql template1
CREATE USER jira WITH UNENCRYPTED PASSWORD password1;
CREATE DATABASE jira WITH ENCODING 'UNICODE' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;
\q

The encodings are as specified by Jira. This may change in the future.

Once the new database exists, we can restore the data:

pg_restore -f database-dump.pgsql jira

Step 5. Start Apache2 / Jira

First you probably want to start Apache2 and make sure it runs as on your old server. Assuming that works, you should be able to enter your jira URL and get an error saying that the application is not working. Something of the sort. This is because Jira is still down.

Now you can start Jira and see whether it does indeed get started. If no problem occurred, then it should just start. You may see errors in the latest logs generated by Catalina and Jira. These are found under the Jira home directory. Use ls to find the latest files and then check then out with less -S.

ls -ltr /opt/atlassian/jira/logs
...ls output...
less /opt/atlassian/jira/logs/catalina.out

I have no clear idea of the difference between catalina and localhost and access_log. Well. The access_log* seems to only be used when a user accesses Jira. Something similar to the apache2 logs.

Even though your IP address will have changed, we had nothing to modify to get the new instance to work. They do save the server IP address somewhere in the database, but it seems that it does not need to be updated manually.

Step 6. Enjoy!

Now you have moved Jira from one computer to another.