Installing and Configuring Jira Data Center on AWS

 ·  ☕ 10 min read
🔖
  • Man Pages

    • Or at least how I did it

    Disclaimer

    This is my experience and steps I performed, YMMV.
    Some of these steps might not be required for your environment and some other steps might be.
    Some of the values might be different for you, where I think that might be the case they will appear as variables like so: ${VARIABLE}.
    This guide is to help you, not tell you want to do, so I take no responsibility if you screw up. OK?

    Official Documentation can be found Here1

    The Goal

    We hope to achieve an instance of Jira running on a cluster of nodes.

    Side-note: The only important difference between Jira and Jira Datacenter is that the Datacenter version is a cluster of nodes.
    It is exactly the exact same piece of software, but using a different licence.

    We will be using:

    • Jira version 8.6
    • RHEL7.5
    • c5.xlarge (4 vCPU, 8 GB Mem) for nodes
    • 60 GB for node storage
    • Oracle 12c se for the database running on RDS with type db.t3.medium (2 vCPU, 4 GB Mem)
    • 200 GB of Database storage
    • EFS for the shared storage
    • ALB for the load balancer that serves to the cluster

    The Load Balancer will be using HTTPS between both the client and the Jira nodes.

    The subnets, number of nodes and other various configurations not listed are likely of no importance to the build.

    Useful Information

    Here is some information that could prove useful.

    These are the defaults and might be assumed below; if the values are different for you, then you would likely know, substitute appropriately.

    Home Directory ${JIRA_HOME} = /var/atlassian/application-data/jira/

    Install Directory ${JIRA_INSTALL} = /opt/atlassian/jira/

    The keytool is located in ${JIRA_INSTALL}/jre/bin/

    If when you navigate to Jira, you use the same hostname as when using Confluence then timing issues can occur that result in being logged of for inactivity. This can happen if you are installing on the same node and not using different URLs for using ssh tunneling and therefore accessing both Jira and Confluence using ’localhost’. Using separate hostname of different browsers can get around this issue.

    Pre-install steps

    There are a number of tasks that are recommended to perform prior to the installation of Jira. These should be done on all the nodes

    • Update hostname of your nodes
    • Update the proxy settings of the node
      • This is particularly important to do for your package manager (e.g. yum) as the install step may require some additional packages
      • Don’t forget the proxy bypass list too
    • Join the domain
    • Mount the EFS file system.
      1. Create the shared directory. e.g. /jira-shared
      2. Add to /etc/fstab. e.g.
    1

    ${IP/HOST OF EFS MOUNT}:/ ${SHARED DIRECTORY} nfs4 defaults,_netdev 0 0
    • Download the installers and upload to each node
      • Make the installer executable
    1

    chmod +x ${INSTALLER}
    • Download and upload the Oracle DB drivers
      • Extract the tar.gz file
    1

    tar -xf ${DRIVERS ARCHIVE}

    Command-line installation

    These steps need to be done on all the nodes.

    Now we can install Jira:

    1

    sudo ${INSTALLER}

    When prompted, enter the following values:

    1. y # Install fontconfig
    2. o # Start installation
    3. 1 # Express installation, use defaults
    4. y # Start Jira service

    Next we need to add the Oracle DB drivers

    1

    sudo cp -r ${DB DRIVERS FOLDER}/* ${JIRA_INSTALL}/lib/

    Next we want to ensure that permissions are set sufficiently, we will do this by setting the owner to a user called ‘jira’ that was created as part of the install.

    1
2
3

    sudo chown -R jira ${JIRA_HOME}
sudo chown -R jira ${JIRA_INSTALL}
sudo chown -R jira ${SHARED DIRECTORY}

    Finally, to ensure that these post installation changes are picked up, we want to restart the jira service

    While you can use systemctl to start and stop the service, using the below method is both recommended by Jira documentation and it provides output to the command line.

    1
2

    sudo /etc/init.d/jira stop
sudo /etc/init.d/jira start

    Web Interface Configuration

    This is done on a single node, so it is a good idea that you stop the Jira service on all but one node first.

    This is done as a series of forms with ‘points of no return’. Thus if you make a mistake and are unable to go back, you can start again by deleting the file ‘dbconfig.xml’ in the Jira home directory and restarting the Jira service. You can then start the Web interface configuration again.

    1. Using a web browser, navigate to the node still running Jira on http (default port is 8080).

    2. First page

      • Select “I’ll set it up myself”

    3. Database setup

      • Select “My Own Database”
      • Fill in the other fields with your own appropriate values
      • It is a good idea to test the connection
      • If you previously went through this setup and are doing it again, then you may be advised that the database contains existing data. Continue with the setup anyway.

    4. Application properties

      • Mode = “Private”
      • Base URL: A good idea is to use the URL you are using to connect for the setup, which may not be the final URL. This can be changed later once setup has been finished. (In fact, if you connect via a different URL after the setup, a notification will complain about it and take you to the setting where you can change it)

    5. Licensing

      • You can use an evaluation license for now and upgrade later

    6. Admin Account

      • I’ll let you decide what you want to put here

    7. Email Notifications

      • Select “Later”

    8. Log in

      • Log in with the admin account you created earlier

    9. Language

      • Select “English US”, which is the default

    10. Avatar

      • Really not important

    11. Create a first project

      • Create a sample project. This can be deleted later, but it gets you up and going.

    Increasing Memory

    At this point, you have Jira installed on all nodes, but only configured on one of them.

    1. Open the file ${JIRA_INSTALL}/bin/setenv.sh
    2. Modify the values ‘JVM_MINIMUM_MEMORY’ and ‘JVM_MAXIMUM_MEMORY’.
      • Due to the way Java works, this setting does not limit the maximum amount of memory that will be used. There is additional overhead for managing the Java Virtual Machine as well.
      • Setting these parameters to the same value may reduce the memory management overhead.

    Adding to the Load Balancer

    At this point, you have Jira installed on all nodes, but only configured on one of them.

    Tomcat (which is the server that powers Jira) needs to be told about the proxy/reverse proxy that users will be connecting from if not going directly, this is therefore important for clustering. If you don’t then a POST request could return a 403 error.2

    1. Open ${JIRA_INSTALL}/conf/server.xml
    2. Comment out the default http connector (Comment blocks start with ‘<!–’ and end with ‘–>’)
    3. Uncomment the HTTPS behind proxy connector
      • Also change the value for proxyName to the url you will use to connect to the load balancer

    Clustering

    At this point, you have Jira installed on all nodes, but only configured on one of them.

    1. Stop the Jira service on all nodes
    2. Copy the Install directory and home directory from the node you performed the web configuration on to the remaining nodes (be careful around preserving permissions).
    3. Copy the following folders from the home directory to the shared directory
      • Data
      • plugins
      • logos
      • import
      • export
      • cache
    4. In each of the nodes local home folder, create the file ‘cluster.properties’ with the following contents:
    # This ID must be unique across the cluster
jira.node.id = ${UNIQUE ID}
# The location of the shared home directory for all Jira nodes
jira.shared.home = ${SHARED DIRECTORY}

    Where ${UNIQUE ID} is an arbitrary but different value for each node, I would recommend ‘Node 1’, ‘Node 2’, etc.

    Enable HTTPS

    If you need to have end-2-end encryption and off-loading the ssl-termination to the Load Balancer is not sufficient.

    These instructions assume that you have a certificate chain, a signed certificate and a private key for the certificate.

    1. Stop the cluster

    2. Generate a keystore using the keytool

    1

    keytool -genkeypair -keysize 2048 -alias tomcat -keyalg RSA -sigalg SHA256withRSA

    The prompted information is not important as we will be deleting the key soon anyway, but it does generate a keystore which we will use.

    1. Move it to the appropriate directory and change the ownership if required
    1
2

    mv ~/.keystore ${JIRA_HOME}/jira.jks
chown jira ${JIRA_HOME}/jira.jks
    1. Delete the cert currently in the keystore
    1

    keytool -delete -alias tomcat -keystore ${JIRA_HOME}/jira.jks
    1. Create a temporary pkcs12 keystore using the certs and key you have
    1

    openssl pkcs12 -export -in ${SIGNED CERTIFICATE} -inkey <${PRIVATE KEY} -out tmpkeystore -name tomcat -CAfile ${CERT CHAIN/BUNDLE/ROOT} -caname root
    1. Import the temporary keystore into the real keystore
    1

    keytool -importkeystore -deststorepass ${KEYSTORE PASSWORD} -destkeypass ${KEYSTORE PASSWORD} -destkeystore ${JIRA_HOME}/jira.jks -srckeystore tmpkeystore -srcstoretype PKCS12 -srcstorepass ${SOURCE KEYSTORE PASSWORD} -alias tomcat

    ${SOURCE KEYSTORE PASSWORD} will be the password you gave in step 5

    The default password is ‘changeit’

    You can also delete the temporary keystore ‘tmpkeystore’

    1. Modify the file ${JIRA_INSTALL}/conf/server.xml

      • On the HTTPS connector, add the properties:
        • keystorePass="${KEYSTORE PASSWORD}"
        • keystoreFile="${JIRA_HOME}/jira.jks"
        • clientAuth=“false”
        • sslProtocol=“TLSv1.2”
        • sslEnabledProtocols=“TLSv1.2”
        • SSLEnabled=“true”
        • And make sure the protocol is: protocol=“org.apache.coyote.http11.Http11NioProtocol”

    2. Copy to other nodes both the server.xml and jks file

    3. Start the cluster back up

    Install Trusted CA

    These steps should be done on each of the nodes

    If you are using private certificates you might need to install the certificate, intermediary or root Certificates onto the servers.

    To add to the Trust Store of the OS.

    1
2
3
4
5

    sudo yum install ca-certificates
sudo cp ${CERTIFICATE FILE} /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust enable
sudo update-ca-trust extract
sudo update-ca-trust

    In Jira, you might have gadget errors, 500 errors etc.. This might be because adding to the OS Trust Store is not sufficient and the certificates need to be added to Java’s Trust Store as well. This can be done with the commands:

    1
2

    sudo ${JIRA_INSTALL}/jre/bin/keytool -import -alias Jira -keystore ${JIRA_INSTALL}/jre/lib/security/cacerts -file ${CERTIFICATE FILE}
sudo /etc/init.d/jira restart

    Single Sign-On

    Official documentation here3.

    Adding a Directory

    1. In the Jira Console, go to Settings > User Management > User Directories
    2. Click “Add Directory”
    3. Configuration
      • Name: I recommend the name of the domain like ’example.com’
      • Directory Type = Microsoft Active Directory
      • Hostname: The Hostname or IP of the server running LDAP service. A good practice is to make all the Domain Controllers accessible to your Jira nodes in which case you can use the domain name (e.g. example.com) as this should return the IPs of all the Domain Controllers.
      • Port: 389 is the default but 636 is the default when using ssl. Using SSL is recommended but if your LDAP service is not configured for it, then this is obviously not an option. I suggest you try it anyway and then use non-ssl if that fails.
      • Username & Password: Use your own values
      • LDAP Schema Parameters: These will be particular to your setup
      • LDAP Permissions: Select “Read Only with Local Groups”
      • Default Group Memberships = “jira-users”
      • User Schema Settings: Depending on the configuration of your SAML provider you might need to change parameters: ‘User Object Filter’ and ‘User Name Attribute’. For example, the default is to have the shortname; but in my case the SAML provider used the full email of the user, thus I had to change the values as below:
        • User Object Filter = “(&(objectCategory=Person)(userPrincipalName=*))”
        • User Name Attribute =" userPrincipalName"

    Adding a SAML provider

    This is not a tutorial on how to configure your SAML provider, but how to configure Jira to use it

    1. In the Jira Console, go to Settings >System > SSO 2.0
    2. Configure as such:
      • Authentication Method: Select “SAML single sign-on”
      • The ‘SAML SSO 2.0 Settings’ parameters would be dependant on your SAML provider settings
      • Login mode: This determines if when accessing Jira, you will be automatically redirected to your SAML provider (e.g. ADFS) or you need to use a special url to sign on with that method (this is the “Assertion Consumer Service URL” at the bottom of the page). Keeping SAML as the secondary method is recommended while performing initial configuration and testing so you can still use the local directory (e.g. the primary admin account).

    1. https://confluence.atlassian.com/adminjiraserver/installing-jira-data-center-938846870.html ↩︎

    2. https://mangolassi.it/topic/17879/error-creating-project-xsrf-check-failed-on-jira ↩︎

    3. https://confluence.atlassian.com/enterprise/saml-single-sign-on-for-atlassian-data-center-applications-857050705.html ↩︎

    Kieran Goldsworthy
    WRITTEN BY
    Kieran Goldsworthy
    Cloud Engineer and Architect

    See Also

    ©2023, All Rights Reserved

    What's on this Page