Configuring Jira services

Introduction

This page describes how Alexis Huxley installed, upgraded, migrated and configured Jira. It was last used to upgrade and migrate to 8.7.1.

Installing or migrating

  1. If migrating then upgrade the old system to the latest Jira first (see separate procedures below).
  2. Collect the following prerequisites:
    1. Jira software with the same version as the old installation (see https://www.atlassian.com/software/jira/download)
    2. Jira developer license (see https://id.atlassian.com/login?application=mac&continue=https://my.atlassian.com, requires a password, and click ‘View Developer License’)
    3. Determine the database host, database name username, password that the Jira software should use to access its database.
    4. MySQL Connector/J in tar.gz format (see https://dev.mysql.com/downloads/connector/j/)
    5. List of desired plugins.
  3. If migrating then backup the old Jira installation as follows:
    1. Export an XML backup of the Jira database (Cog–>System–>Import & Export–>Backup System) and note the directory you are told and the filename you specified.
    2. Shutdown Jira by running: 
      service jira stop
    3. Tar up /var/atlassian/application-data/jira by running something like this: 
      cd /var/atlassian/application-data/jira
tar cf ~/var-atlassian-application-data-jira.tar .
    4. Backup the MySQL database: 
      mysqldump jira > jira-db-dump.sql
    5. If the new installation will be on the same machine as the old installation then rename /opt/atlassian/jira.
    6. Backup the following files and directories:
      • /opt/atlassian/jira/conf/server.xml
      • /var/atlassian/application-data/jira/data
  4. Install the following prerequisite packages:
    • fontconfig
  5. Run the Jira installer (.bin) file as root, accepting all defaults: 
    ./atlassian-jira-software-8.7.1-x64.bin

    but do not allow it to start the Jira server (we do this in order to facilitate checking if JRA-42000 has been fixed yet, which we’ll do in the next step).

  6. Reboot the machine, log in and see if any processes are running as the ‘jira’ user. If not then:
    1. Note that JRA-42000 has still not been fixed.
    2. insert the following in /etc/init.d/jira, after the ‘#!/bin/bash’: 
      ### BEGIN INIT INFO
# Provides: jira
# Required-Start: $network $local_fs $syslog
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: JIRA Server
# Description: Jira is a ticketing thing. It runs on java.
# It sometimes needs to be stopped and/or started.
### END INIT INFO
    3. Run: 
      systemctl enable jira
    4. Reboot again.
    5. Log in as root and verify that there are now processes running as the ‘jira’ user.
    6. Run ‘top’ and wait for the load to drop.
  7. Stop Jira.
  8. SKIP THIS!!! If migrating then:
    1. Rename the new Jira home to make space for the old home to be restored by running: 
      cd /var/atlassian/application-data
mv jira jira.delete-me-soon
mkdir jira          #  no need to fix owner/group/perms; tar will do that
    2. Restore the old Jira home to the new server by running something like: 
      cd /var/atlassian/application-data/jira
tar xf <path-to-the-tar-file-you-made-earlier>
  9. If the Jira server is behind a front-end webserver then configure the back-end and front-end as follows:
    1. Run: 
      service jira stop
    2. If the URI path is not ‘/’ then edit /opt/atlassian/jira/conf/server.xml change change ‘path=””‘ to ‘path=”<uri-path>” (e.g. ‘path=”/jira/”‘). For me, this means do nothing.
    3. In the same file comment-out and comment-in the appropriate default/http/https blocks and correct the server’s FQHN. For me, this means:
      1. Comment out the ‘DEFAULT’ block
      2. Uncomment the ‘HTTPS’ block
      3. Correct the FQHN in the ‘HTTPS’ block to jira.pasta.freemyip.com.
    4. Run: 
      service jira start
    5. This step is probably obsolete:
      1. Log in as the Jira admin.
      2. You should see the following warning:
        jira-installation-screenshot-08-apache-jira-config-warning
      3. To clear this warning complete the following sub-procedure:
        1. Go to Cog–>System–>Edit Settings.
        2. Set ‘Use gzip compression’ to ‘Off’
        3. Set ‘Base URL’ to the actual URL that users will use (i.e. the one Apache is presenting).
        4. Click ‘Update’ (at the bottom of the page.
        5. Verify that the warning is now gone.
  10. Create a database for Jira as follows:
    1. Note that MariaDB is not supported but that MySQL is not included in Debian 10. Attempting to use MariaDB results in a webpage displaying: 
      Database: Supported database
MySQL 5.5 is not supported. 
...
If you want to ignore these warnings and start Jira, you need to use the -Djira.startup.warnings.disable startup flag that will ignore the warnings.

      But setting that flag (-Djira.startup.warnings.disable or -Djira.startup.warnings.disable=true) makes no difference. Therefore we have no option but to use MySQL.

    2. Run: 
      wget http://repo.mysql.com/mysql-apt-config_0.8.13-1_all.deb
dpkg -i mysql-apt-config_0.8.13-1_all.deb
apt-get update

      Be sure to choose version 5.7  as version 8 does not work with Jira.

    3. Install the database server and connectors: 
      groupadd mysql
useradd -r -g mysql -s /bin/false mysql
apt-get -y -qq install mysql-server
    4. Create /etc/mysql/conf.d/jira.cnf containing: 
      [mysqld]
default_storage_engine=INNODB
character_set_server=utf8mb4
innodb_default_row_format=DYNAMIC
innodb_large_prefix=ON
innodb_file_format=Barracuda
innodb_log_file_size=2G

      (Note that the official documentation says default-storage-engine – i.e. with hyphens instead of underscores – but this is wrong.)

    5. Restart mysql by running: 
      systemctl restart mysql
    6. Install Connector/J where Jira can find it by running: 
      tar xzf mysql-connector-java-5.1.48.tar.gz
cp mysql-connector-java-5.1.48/mysql-connector-java-5.1.48.jar /opt/atlassian/jira/lib/
    7. Run: 
      mysql
CREATE DATABASE jira CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
CREATE USER 'jira'@'localhost' IDENTIFIED BY '<PASSWORD>';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,REFERENCES,DROP,ALTER,INDEX on jira.* TO 'jira'@'localhost';
flush privileges;
\quit
  1. If you want to use the wizard to configure the database connection then:
    1. Start Jira by running: 
      systemctl start jira
    2. At the ‘Jira setup’ page, when prompted to choose between ‘Set it up for me’ or ‘I’ll set it up myself’, choose the latter and click ‘Next’.
    3. At the ‘Database setup’ page, when prompted to choose between ‘Built In’ or ‘My Own Database’, choose the latter, fill in the connection parameters (which only appear once you select ‘My Own Database’), click ‘Test connection’ and then click ‘Next’. This can take about 10 minutes to complete.
  2. If you want to do it manually configure the database connection then:
    1. Create /var/atlassian/application-data/jira/dbconfig.xml (preferably by copying an old version of the file).
    2. Start Jira by running: 
      systemctl start jira
  3. If migrating then:
    1. If using a front-end proxying webserver then:
      1. modify its configuration to proxy to the new Jira server instead of the old Jira server
      2. increase its timeout from 300 to 3600 by adding ‘timeout=3600’ to the ProxyPass line (this is needed during database construction)
    2. At the ‘Set up application properties’ window, click ‘Import your data’.
    3. Copy over the exported XML backup (actually a zip file) to the directory /var/atlassian/application-data/jira/import and make sure it is readable by jira.
    4. At the ‘Import existing data’ window:
      1. enter the XML backup filename
      2. paste in the developer license
      3. enable outgoing mail
      4. click ‘Import’
      5. wait up to 15 minutes.
    5. In order to avoid the Jira server throwing 500 errror when viewing versions page, reboot the system now.
    6. Restore the contents of /var/atlassian/application-data/jira/data.
    7. Verify projects, issues and workflows look correct, including the presence of avatars and images attached to tickets.
    8. Review the server logs.
    9. If using a front-end proxying webserver then:
      1. remove access restrictions on the front-end web proxy.
      2. revert its timeout from 3600 to 300 (this was needed during database construction)
  4. If installing for first time then:
    1. Note that the screenshots below are from version 6.1, so things might look different now!
    2. Set the Application Name to just ‘Jira’ and the Mode to ‘Private’ and click ‘Next’. (Leave the base URL alone, we will handle that shortly.)
    3. The screen should now look like this:
      jira-installation-screenshot-03-license-keys
    4. Select ‘I have a key’ and the system’s Jira server ID will be displayed.
    5. Visit https://id.atlassian.com/login?application=mac&continue=https://my.atlassian.com and click ‘View License’.
    6. Enter the server ID and click ‘Save’, the license will be displayed.
    7. Back in the install wizard, enter the license and click ‘Next’.
    8. The screen should now look like this:
      jira-installation-screenshot-04-admin-account
    9. Enter your full name and email address. (Do not change the user name from ‘jira’.)
    10. The screen should now look like this:
      jira-installation-screenshot-05-atlassian-analytics
    11. Click ‘Yes’ or ‘No’ according to you desire (I click ‘No’).
    12. The screen should now look like this:
      jira-installation-screenshot-06-email-notifications-now-or-later
    13. Select ‘Now’ and fill in the parameters for your SMTP server. Be sure to change the from address to ‘jira@…’ instead of the default (which is probably your own address).
    14. I should have clicked Test Connection.
    15. Click ‘Finish’ and wait a couple of minutes.
  5. Install desired plugins as follows:
    1. Log into your JIRA instance as an admin.
    2. Click the admin dropdown and choose Add-ons. The Manage add-ons screen loads.
    3. Click Find new add-ons from the left-hand side of the page.
    4. Locate JIRA Subversion Plugin via search. Results include add-on versions compatible with your JIRA instance.
    5. Click Install to download and install your add-on.
    6. Click jira-cog –> Addons –> Subversion Repositories.
    7. Enter the Display Name and the Repository Root and click ‘Add’; this will take a while to process.

Adding users

All actions are done through the web interface as a user with Jira administrator privileges.

  1. Click jira-cog, then ‘User Management’ (or just type .users).
  2. The easiest way to add users is to send them invites by clicking on ‘Invite Users’.
  3. Once you have signed up, then you might want to rationalise the list of users (I had my full name assigned both the ‘jira’ account and my personal account). This may require assigning users to sufficient groups so that somebody is still has administrator rights.
  4. Note that all users must be in the jira-users group else they can’t log in. (This applies even to those users in jira-administrators, else they can’t make dashboards.)

A word about objects and object schemes

A workflow is a set of states and state transitions (e.g. “Begin work” could be a state transition between states “To do” and “In progress”). A workflow scheme is a set of workflows, one for each type of issue in a project (e.g. Bugs may follow one workflow, whereas feature requests may follow another).

More genertally, this relationship between an object and an object scheme applies to:

  • workflows
  • field configurations
  • issue types
  • screen, permissions
  • notifications
  • …

When creating a project, Jira creates project-specific objects based on what sort of project you define (e.g. Simple Issue Tracking, Software Development Project, …). If you have many projects that should always use the same object even if that workflow needs to be modified (e.g. workflow for for software projects) then it makes most sense for them to use one common object and object scheme, rather than the project-specific ones that Jira instantiated.

Much of what follows is about creating and tuning new objects, so that when a new project is created it can be configured to use these objects.

Text renderers

All actions are done through the web interface as a user with Jira administrator privileges.

  1. Click jira-cog –> Issues –> Field Configurations (the list of fields and which can use which renderer).
  2. Copy the “Default Field Configuration” to “Software Development Field Configuration” and copy it again to “Simple Issue Tracking Field Configuration”.
  3. Repeat the above steps for Field Configuration Schemes (the list of which issue types will use which fied configurations).
  4. Click jira-cog –> Issues –> Field Configurations Schemes and set each of the just-added field configuration schemes to use the correspondingly-named field configuration.
  5. Click jira-cog –> Issues –> Field Configurations and for each of the just-added configurations:
    1. click ‘Configure’
    2. for the ‘Software Development Field Configuration’, for the ‘Description’ and ‘Comment’ fields, change the renderer to ‘Wiki Style Renderer’
    3. for the ‘Simple Issue Tracking Field Configuration’, for the ‘Description’ and ‘Comment’ fields, change the renderer to ‘Default Text Renderer’

Workflows

All actions are done through the web interface as a user with Jira administrator privileges.

  1. Click jira-cog –> System –> Time Tracking.
  2. Click ‘Deactivate’.

Note that once a workflow has been written, then it may be impossible to add transitions from “final” states!

Permission schemes

Issue type schemes

Disabling logging work

Comments entered as logged work do not appear in the print-view of a ticket because they are really meant for accountancy purposes only. However, this isn’t necessarily apparent to users. So it may be appropriate to disable this kind of accountancy.

  1. ?

Facilitating anonymous read-only access

  1. Cog –> Issues –> Permission Schemes
  2. There should be one permission scheme listed, entitled ‘Default Permission Scheme’
  3. Copy this scheme to make a new scheme entitled ‘Default permission scheme but with read-only anonymous access’
  4. There should now be two permission schemes listed.
  5. Click ‘Permissions’ next to the new scheme.
  6. In the ‘Browse Projects’ row, click ‘Add’, then ‘Group’ and from the pulldown menu select ‘Anyone’, then click ‘Add’ to confirm

The above is enough to allow anonymous users to be able to browse only specific projects, but it is not enough to stop them from making state transitions (e.g. To Do –> Fixed). That is handled below.

This section is based on message <4475336.375721303343141354.JavaMail.j2ee_forums.atlassian.com@atlassian12.managed.contegix.com> posted to the Jira Users mailing list on Wed, 20 Apr 2011 18:45:11 CDT:

> Aside from adding a condition to each transition to check if you are a registered user, are there
> any ways to set a universal permission to not allow anonymous users to make any changes to status?
> This seems like a strange thing to allow out-of-the-box, so I feel that I'm missing something somewhere.

I suspect it was the same before, but more obvious now.  You should be including a condition on every
workflow transition, no matter what it is, if you allow any form of anonymous access.  (This is something
that I don't feel is well signposted in the docs - it *is* written up, but not as a big red "gotcha")

The steps below deal with that are as follows:

  1. Cog –> Issues –> Workflows
  2. Note the list of workflows
  3. Log out, view projects using each of the noted workflows, try changing the state of an issue, note whether it was possible, log back in.
  4. Cog –> Issues –> Workflows
  5. For each workflow listed:
    1. Click Edit
    2. For each transition (and there will be several for each step):
      1. Click the name of the transition
      2. Click the ‘Conditions’ tab and then click ‘Add’
      3. Select ‘User Is In Group’ and the click ‘Add’
      4. From the pulldown menu select ‘jira-users’ and click ‘Add’
    3. Click ‘Publish Draft’
    4. Select to save a backup copy, give it a suitable name and click ‘Publish’
  6. Log out, view projects using each of the noted workflows, try changing the state of an issue, note whether it was possible.

Adding projects

All actions are now done through the web interface as a user with administrator privileges.

  1. Click ‘Projects’ and ‘Create Project’.
  2. The screen should now look like this:
    jira-installation-screenshot-09-creating-projects
  3. Click ‘Simple Issue Tracking’ (I might change this later) and click ‘Next’.
  4. To change the project avatar, select the project, click the ‘Administration’ tab, click the ‘Edit Project’ button, click the existing avatar, then click the ‘Browse’ button.
  5. To change the workflow scheme … (don’t forget to then delete the automatically created but no longer needed workflow scheme and workflow)
  6. To assign users to roles …
  7. jira-users should be removed from the project (because all users must be in jira-users, but you don’t necessarily want all users to be able to access your project.
  8. Change the permissions scheme?
  9. Click jira-cog –> Project –> <project-name> –> Fields –> <name-of-current-field-configuration-scheme> –> Actions –> Use a different scheme.
  10. Choose ‘Software Development Field Configuration Scheme’ or ‘Simple Issue Tracking Field Configuration Scheme’, based on the type of project.
  11. If anonymous read-only access to issues is to be allowed then:
    1. from the project administration interface, in the ‘Permissions’, then ‘Actions’ and ‘Use a different scheme’, and from the pulldown menu select ‘Default permission scheme but with read-only anonymous access’ and then click ‘Associate’ to confirm
    2. test by logging out and checking what projects are visible.

Upgrading from 6.1 to 6.2

  1. The upgrade can be reasonably on-the-fly, according to the rapid upgrade method.
  2. However, afterwards Jira failed to load with the following error:

    Oops, you’ve found a dead link.

    • Bug tracking and project tracking for software development powered by Atlassian JIRA (v6.2#6252-sha1:aa34325)
    • About JIRA
    • Report a problem
  3. Because the target of that ‘Home Page’ link is not correct, it suggests that Jira has forgotten that it is meant to be proxied. Therefore I re-ran the instructions in the ‘Proxying Jira’ section above. Then it started working.

Upgrading from 6.2 to 6.4

  1. Rerun the instructions in the ‘Proxying Jira’ section above.

Upgrading from 6.4 to 7.1.4

  1. Rerun the instructions in the ‘Proxying Jira’ section above.
  2. Update add-ons:
    1. Go to Cog–>Add-ons–>Manage Add-ons; from the pulldown menu select ‘Action required’ and then click ‘Update all’.
    2. The ‘Atlassian Universal Plugin Manager Plugin’ add-on had to be done in a second pass of updating add-ons.
  3. A database re-index is suggested (and can be done with a click).

Upgrading from 7.1.4 to 7.3.2

  1. Rerun the instructions in the ‘Proxying Jira’ section above.
  2. Update add-ons:
    1. Go to Cog–>Add-ons–>Manage Add-ons; from the pulldown menu select ‘Action required’ and then click ‘Update all’.
    2. The ‘Atlassian Universal Plugin Manager Plugin’ add-on had to be done in a second pass of updating add-ons.
  3. A database re-index is suggested (and can be done with a click).

Upgrading from 7.3.2 to 7.11.1

  1. Download a new version from https://www.atlassian.com/software/jira/download.
  2. If the system is a VM then:
    1. shut down the VM
    2. backup the disk image
    3. restart the VM
  3. Backup the MySQL database: 
    mysqldump jira > jira-db-dump.sql
  4. Make local copies of the following files:
    • /opt/atlassian/jira/conf/server.xml
  5. Run: 
    systemctl stop jira
  6. Make the download executable and run it.
  7. Answer as follows: 
    This will install JIRA Software 7.11.1 on your computer.
OK [o, Enter], Cancel [c] <ENTER>
Express Install [1], Custom Install [2], Upgrade existing installation [3, Enter] <ENTER>
[/opt/atlassian/jira] <ENTER>
Back up JIRA home directory? Yes [y, Enter], No [n] n
[Enter] <ENTER>
Do you want to proceed? Upgrade [u, Enter], Exit [e] <ENTER>
  8. At this point, before allowing the installer to restart Jira, backup server.xml and then apply all necessary edits.
  9. Then continue answering the installer as follows: 
    Start JIRA Software 7.11.1 now? Yes [y, Enter], No [n] <ENTER>
  10. Run ‘top’ and wait for the CPU usage to drop.
  11. Log in to Jira.
  12. Update add-ons:
    1. Go to Cog–>Add-ons–>Manage Add-ons; from the pulldown menu select ‘Action required’ and then click ‘Update all’.
  13. At this point I encounted a UPM error, but did the following to clear it: 
    systemctl stop jira
rm -fr /var/atlassian/application-data/jira/plugins/.bundled-plugins
rm -fr /var/atlassian/application-data/jira/plugins/.osgi-plugins/
systemctl start jira
  14. As the Jira web interfaces advises, then do a database reindexing.

Upgrading from 7.11.1 to 8.7.1

  1. Following the upgrade a notification reported: 
    The Attachments health check has failed in your system.

    It looks like the directory /var/atlassian/application-data/jira/data, which has subdirectories attachments and avatars, does not get exported into the XML backup. I adjusted the procedure above accordingly.

  2. /var/lib/mysql contained enormous REDO logs: 
    gometi# ls -lh /var/lib/mysql/ib_logfile*
-rw-r----- 1 mysql mysql 2.0G Feb 20 12:09 /var/lib/mysql/ib_logfile0
-rw-r----- 1 mysql mysql 2.0G Feb 20 11:03 /var/lib/mysql/ib_logfile1
gometi#

    which I cleaned these according to these instructions as follows:

    gometi# mysql
mysql> SET GLOBAL innodb_fast_shutdown = 0;
mysql> ^D
gometi# mysqladmin shutdown
gometi# rm /var/lib/mysql/ib_logfile*
gometi# systemctl start mysql
gometi#

    but that just recreated the REDO logs. i should consider moving /var/lib/mysql to a larger file filesystem.

Disabling Google Analytics

This does not seem to be possible. The documentation for Jira 6.3 (not 6.2) says:

Versions of JIRA prior to 6.3.3 and some Atlassian add-ons for JIRA had different analytics settings to those described below. Regardless of those settings data from those implementations is no longer being received by Atlassian.

Workaround for JRASERVER-66593

  1. Add the following to root’s crontab: 
    SHELL=/bin/bash
45 * * * * mysql jira <<<"delete from clusteredjob WHERE job_runner_key = 'com.atlassian.jira.plugin.ext.bamboo.service.PlanStatusUpdateJob';"

See also