Post-installation configurations

The post-installation configuration steps are optional, depending on your needs and environment. If you set up JIRA for evaluation purposes, you probably do not need to perform any of the following steps, but it is always a good practice to be familiar with these as a reference.

Note

You will need to restart JIRA after making the changes discussed in the next section.

Increasing JIRA's memory

The default memory setting for JIRA is usually sufficient for a small to medium-sized deployment. As JIRA's adoption rate increases, you will find that the amount of memory allocated by default is no longer enough. If JIRA is running as a Windows service, as we described in this chapter, you can increase the memory as follows:

1. Find the JIRA Windows service name. You can do this by going to the Windows services console and double-clicking on the Atlassian JIRA service. The service name will be the part after //RS// in the Path to executable field, for example, JIRA150215215627.
2. Open a new Command Prompt and change the current working directory to the JIRA_INSTALL/bin directory.
3. Run the following command by substituting the actual service name for JIRA:

   tomcat7w //ES//<JIRA Windows service name>
   

4. Select the Java tab, update the Initial memory pool and Maximum memory pool sizes, and click on OK.
   

5. Restart JIRA to apply the change.

If you are not running JIRA as a Windows service, you need to open the setenv.bat file (for Windows) or the setenv.sh (for Linux) file in the JIRA_INSTALL/bin directory. Then, locate the following lines:

set JVM_MINIMUM_MEMORY="384m" 
set JVM_MAXIMUM_MEMORY="768m" 

Change the value for the two parameters and restart JIRA. Normally, 4 GB (4096m) of memory is enough to support a fairly large instance of JIRA used by hundreds of users.

Tip

Make sure that you have enough physical RAM available before allocating instances to JIRA.

Changing JIRA's port number and context path

As part of the installation process, the installation wizard prompted us to decide which port JIRA should listen to for incoming connections. If you have accepted the default value, it is port 8080. You can change the port setting by locating and opening the server.xml file in a text editor in the JIRA_INSTALL/conf directory. Let's examine the relevant contents of this file:

<Server port="8005" shutdown="SHUTDOWN"> 

This line specifies the port for the command to shutdown JIRA/Tomcat. By default, it is port 8005. If you already have an application that is running on that port (usually another Tomcat instance), you need to change this to a different port:

<Connector port="8080" protocol="HTTP/1.1"> 

This line specifies which port JIRA/Tomcat will be running on. By default, it is port 8080. If you already have an application that is running on that port, or if the port is unavailable for some reason, you need to change it to another available port:

<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false" useHttpOnly="true"> 

This line allows you to specify the context that JIRA will be running under. By default, the value is empty, which means JIRA will be accessible from http://hostname:portnumber. If you decide to specify a context, the URL will be http://hostname:portnumber/context. In our example here, JIRA will be accessible from http://localhost:8080/jira.

Configuring HTTPS

By default, JIRA runs with a standard, non-encrypted HTTP protocol. This is acceptable if you are running JIRA in a secured environment, such as an internal network. However, if you plan to open up access to JIRA over the Internet, you will need to tighten up the security by encrypting sensitive data, such as usernames and passwords that are being sent, by enabling HTTPS (HTTP over SSL).

For a standalone installation, you will need to perform the following tasks:

1. Obtain and install a certificate.
2. Enable HTTPS on your application server (Tomcat).
3. Redirect traffic to HTTPS.

First, you need to get a digital certificate. This can be obtained from a certification authority, such as VeriSign (CA certificate), or a self-signed certificate generated by you. A CA certificate will not only encrypt data for you, but also identify your copy of JIRA to the users. A self-signed certificate is useful when you do not have a valid CA certificate and you are only interested in setting up HTTPS for encryption. Since a self-signed certificate is not signed by a certification authority, it is unable to identify your site to the public and users will be prompted with a warning that the site is untrusted when they first visit it. However, for evaluation purposes, a self-signed certificate will suffice until you can get a proper CA certificate.

For the purpose of this exercise, we will create a self-signed certificate to illustrate the complete process. If you have a CA certificate, you can skip the following steps.

Java comes with a handy tool for certificate management, called keytool, which can be found in the JIRA_HOME\jre\bin directory if you are using the installer package. If you are using your own Java installation, then you can find it in JAVA_HOME\bin.

To generate a self-signed certificate, run the following commands from a Command Prompt:

keytool -genkey -alias tomcat -keyalg RSA
keytool -export -alias tomcat -file file.cer

This will create a keystore (if one does not already exist) and export the self-signed certificate (file.cer). When you run the first command, you will be asked to set the password for the keystore and Tomcat. You need to use the same password for both. The default password is changeit. You can specify a different password of your choice, but you then have to let JIRA/Tomcat know, as we will see later.

Now that you have your certificate ready, you need to import it into your trust store for Tomcat to use. Again, you will use the keytool application in Java:

    keytool -import -alias tomcat -file file.cer
JIRA_HOME\jre\lib\security\cacerts

This will import the certificate into your trust store, which can be used by JIRA/Tomcat to set up HTTPS.

To enable HTTPS on Tomcat, open the server.xml file in a text editor from the JIRA_INSTALL/conf directory. Locate the following configuration snippet:

<Connector port="8443" maxHttpHeaderSize="8192" SSLEnabled="true" 
maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 
enableLookups="false" disableUploadTimeout="true" 
acceptCount="100" scheme="https" secure="true" 
clientAuth="false" sslProtocol="TLS"     useBodyEncodingForURI="true"/> 

This enables HTTPS for JIRA/Tomcat on port 8443. If you have selected a different password for your keystore, you will have to add the following line to the end of the preceding snippet before the closing tag:

keystorePass="<password value>" 

The last step is to set up JIRA so that it automatically redirects from a non-HTTP request to an HTTPS request. Find and open the web.xml file in the JIRA_INSTALL/atlassian-jira/WEB-INF directory. Then, add the following snippet to the end of the file before the closing </web-app> tag:

<security-constraint> 
  <web-resource-collection> 
    <web-resource-name>all-except-attachments</web-resource-name> 
    <url-pattern>*.js</url-pattern> 
    <url-pattern>*.jsp</url-pattern> 
    <url-pattern>*.jspa</url-pattern> 
    <url-pattern>*.css</url-pattern> 
    <url-pattern>/browse/*</url-pattern> 
  </web-resource-collection> 
  <user-data-constraint> 
    <transport-guarantee>CONFIDENTIAL</transport-guarantee> 
  </user-data-constraint> 
</security-constraint> 

Now, when you access JIRA with a normal HTTP URL, such as http://localhost:8080/jira, you will be automatically redirected to its HTTPS equivalent, https://localhost:8443/jira.