How-to setup a secured Jira Software 7.9.0 on Ubuntu 16.04.4 in less than 30 minutes

Summary

This article is about to install Jira Software 7.9.0 from scratch on an out-of-the-box Ubuntu 16.04.4 Server, that will listen on HTTPS.  Downloading the packaged does not count to the 30 minutes. Of cause you can take this article to install another version combination, but then not all commands will work with copy & paste.

nginx-jira-mysql.png

Requirements

Your Skills

  • you know how to login to a (remote) Linux server
  • you know how to edit configuration files with nano, vim, emacs, ...

How  to use this article

You can copy and paste all the commands (in code blocks) just to your root shell. The text around is for explaining the "why". If there are important instructions to read, then the text is bold.

Are you ready to rumble?  Start your watch now ... 3.2.1

Part 1 - Prepare MySQL Database

Download and install MySQL from Ubuntu Repository. (Confirm with 'Y')

apt-get install mysql-server

You get asked to set a password for root - you will need it the next steps.

Create the database named 'jira'.

mysqladmin -u root -p create jira

Connect to the database.

mysql -u root -p

Modify the created db, create a news user called 'jira' and grant permissions.

The next 4 commands have to be pasted into the mysql shell. Use another password for the 'jira' db user than for 'root'.

alter database jira character set utf8 collate utf8_bin;
create user 'jira'@'localhost' identified by '<password used by jira>';
grant all on jira.* to 'jira'@'localhost';
exit;

Tune mysql to fit to the requirements of Jira.

echo "innodb_log_file_size = 256M" >> /etc/mysql/mysql.conf.d/mysqld.cnf
echo "max_allowed_packet = 34M" >> /etc/mysql/mysql.conf.d/mysqld.cnf

The tuning requires a restart of MySQL.

systemctl restart mysql.service

Part 2 - Java installation

Change to the directory, where everything gets installed.

cd /opt

Extract the JRE tar-ball.

tar xzf /root/jre-8u172-linux-x64.tar.gz

Create a sym-link. Avoids changing configurations when upgrading Java.

ln -s jre1.8.0_172/ java

Part 3 - nginx and SSL 

Download and install nginx from Ubuntu resources. (Confirm with Y)

apt-get install nginx

Create the nginx proxy configuration. This will forward calls to 443 to internal port 8080 where Jira's tomcat is listening. Additionally SSL is configured and the maximum size of an uploaded attachment is set to 30 Mb. Also gzip compression is activated - make sure not to activate gzip compression later in Jira.

Copy & paste the next full code block into your shell.

cat << EOF | sudo tee /etc/nginx/sites-available/jira
server {
listen 443 ssl;
server_name jira.mycompany.com;
keepalive_timeout 70;
ssl_certificate /etc/nginx/ssl/jira.crt;
ssl_certificate_key /etc/nginx/ssl/jira.pem;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
large_client_header_buffers 4 32k;
gzip on;
gzip_min_length 10240;
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml;
location / {
proxy_pass http://localhost:8080;
proxy_set_header X-Forwarded-Host \$host;
proxy_set_header X-Forwarded-Server \$host;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
client_max_body_size 30M;
proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;
send_timeout 300;
}
}
EOF

Enable the configuration to be loaded next restart.

ln -s /etc/nginx/sites-available/jira /etc/nginx/sites-enabled/jira

Create the directory to store the SSL certificates and change inside.

mkdir /etc/nginx/ssl
cd /etc/nginx/ssl

If you have already a valid signed SSL certificate and your SSL key at hand, then copy the key to jira.pem and the certificate to jira.crt. Skip the next steps and continue at #MARKER#. If you need to create some new self-signed certificates, continue here.

Create your own SSL key. 

openssl genrsa -des3 -out jira.key 2048

You will get asked the set a passphrase - remember/note it.

Remove the passphrase from the key. This is required so that nginx can start unattended (without entering the passphrase).

openssl rsa -in jira.key -out jira.pem

Now the site details for the certificate are added.

openssl req -new -key jira.pem -out jira.csr

Replace the bold text with your own data.

Country Name (2 letter code) [AU]:XY
State or Province Name (full name) [Some-State]:My Country
Locality Name (eg, city) []:My City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Company
Organizational Unit Name (eg, section) []:Operations
Common Name (e.g. server FQDN or YOUR name) []:jira.mycompany.com
Email Address []: <<-- leave empty
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []: <<-- leave empty
An optional company name []: <<--leave empty

Self-sign your certificate. It will be valid for 777 days from now.

openssl x509 -req -days 777 -in jira.csr -signkey jira.pem -out jira.crt

Now the certificate is added to the JRE default keystore. This is required, so that Jira can talk to itself without getting an SSL certificate authorization error.

/opt/java/bin/keytool -import -alias jira.mycompany.com:443 -keystore /opt/java/lib/security/cacerts -file jira.crt

The password of the keystore is 'changeit'.

#MARKER#

Nginx needs to be restarted so that all changes can take effect.

systemctl restart nginx

Part 4 - Jira binary installation

Back to our installation directory.

cd /opt

Extract Jira Software.

tar xzf /root/atlassian-jira-software-7.9.0.tar.gz

Create a sym-link for future Jira upgrades.

ln -s atlassian-jira-software-7.9.0-standalone jira

Create the Jira-Home directory

mkdir jira-home

Edit tomcat settings to fit to the proxy configuration. (in this case with nano)

nano jira/conf/server.xml

At line 36 (Connector block) add the following behind 'bindOnInit="false" ':

proxyName="jira.mycompany.com" proxyPort="443" scheme="https"

Save & exit editor.

Download the MySQL driver that works with Jira 7.9.0 directly from maven repository.

wget http://central.maven.org/maven2/mysql/mysql-connector-java/5.1.45/mysql-connector-java-5.1.45.jar -O jira/lib/mysql-connector-java-5.1.45.jar

Change the ownership of all files to the same system user, the service is started later.

chown -R www-data:www-data atlassian-jira-software-7.9.0-standalone jira-home

Create Systemd configuration to be able to start/stop Jira.

Copy & paste this full code block into your shell.

cat << EOF | sudo tee /etc/systemd/system/jira.service
[Unit]
Description = Atlassian Jira Software
After=syslog.target network.target

[Service]
Type=forking
Environment=JIRA_HOME=/opt/jira-home
Environment=JAVA_HOME=/opt/java
PermissionsStartOnly=true
User=www-data
Group=www-data
ExecStart=/opt/jira/bin/startup.sh
ExecStop=/opt/jira/bin/shutdown.sh
TimeoutStartSec=120
TimeoutStopSec=600
PrivateTmp=true

[Install]
WantedBy = multi-user.target
EOF

Make the systemd configuration known to the system.

systemctl daemon-reload

Make the Jira service persistent (starting at boot-up).

systemctl enable jira.service

Start Jira now!

systemctl start jira.service

Note: depending on your remote system, start-up can take some time. You can have a look inside Jira log file, meanwhile: /opt/jira-home/log/atlassian-jira.log

Congratulations! Setup on command line is now finished. Continue with your Browser.

Stop your watch! Has it taken longer than 30 minutes?

 

Part 5 - Finish installation

Point your browser to https://jira.mycompany.com. If you have used a self-signed SSL certificate, you have now manually to trust the certificate.

Select "I'll set it up myself"  and  "next". Then enter the data like seen in this screen shot:

mysql-setup-screen.jpg

"Test Connection". If its green you can proceed. Now again, this can take some time before you get asked to enter your license.

You have reached the end of this how-to. Hope you were successful. If you are facing problems, let me know.

Post installation tasks (not part of this how-to)

  • log rotate jira/tomcat
  • block port 8080 from outside connections
  • increase JVM memory settings
  • monitoring
  • backup mechanism

14 comments

@Thomas Deilernice article. I wish I could bookmark this article.

Great article!

One caveat, in server.xml you have to comment the default connector (which is uncommented by default) and uncomment the SSL connector, otherwise Jira will complaint about a misconfiguration in server.xml

Thomas Deiler Community Champion Apr 26, 2018

Dear @Adolfo Casari,

unfortunately you are wrong. The configuration steps, as described in the article, are correct. Jira works as expected.

In the default server.xml there are some commented sample configuration available that could be used instead. I decided not to use them and to keep the changes to this configuration file as simple as possible.

So long

Thomas

In the default server.xml there are some commented sample configuration available that could be used instead.

Hi @Thomas Deiler - That is what I did. Reason for that is when going to line 110 (using ALT-G in nano) , it's the end of server.xml . I also checked with cat -n server.xml. Please let me know if I am missing something here. Thanks!

Thomas Deiler Community Champion Apr 29, 2018

Dear@Adolfo Casari,

you are totally right - it seems to be a typo. Its line 36. Fixed it.

Thanks for noting me

Thomas

Great article :)

Hello @Thomas Deiler,

Great work on this how-to. I'm having a problem and would be really grateful if you could help.

I already have 3 certificates from GoDaddy (wildcard cert) 2x crt and 1x crt.pem files

I've changed the nginx configuration to use the bundle.crt file and the pem.

After enabling the config and restarting nginx, i received this msg in the log;

-- Unit nginx.service has begun starting up.
Sep 07 11:56:09 AZR-JIRASD nginx[14925]: nginx: [emerg] SSL_CTX_use_PrivateKey_file("/etc/nginx/ssl/gdig2.crt.pem") failed (SSL: error:0906D06C:PEM routines:PEM_read_bio:no start line:Expecting: ANY PRIVATE KEY error:140B0009:SSL routtines:SSL_CTX_use_PrivateKey_file:PEM lib)
Sep 07 11:56:09 AZR-JIRASD nginx[14925]: nginx: configuration file /etc/nginx/nginx.conf test failed
Sep 07 11:56:09 AZR-JIRASD systemd[1]: nginx.service: Control process exited, code=exited status=1
Sep 07 11:56:09 AZR-JIRASD systemd[1]: nginx.service: Failed with result 'exit-code'.
Sep 07 11:56:09 AZR-JIRASD systemd[1]: Failed to start A high performance web server and a reverse proxy server.
-- Subject: Unit nginx.service has failed
-- Defined-By: systemd
-- Support: http://www.ubuntu.com/support
--
-- Unit nginx.service has failed.
--
-- The result is RESULT.
Sep 07 11:56:09 AZR-JIRASD sudo[14921]: pam_unix(sudo:session): session closed for user root
Sep 07 11:56:30 AZR-JIRASD sudo[14973]: wtsparadigm : TTY=pts/1 ; PWD=/home/wtsparadigm ; USER=root ; COMMAND=/bin/journalctl -xe
Sep 07 11:56:30 AZR-JIRASD sudo[14973]: pam_unix(sudo:session): session opened for user root by wtsparadigm(uid=0)

 

Thanks

Thomas Deiler Community Champion Sep 08, 2018

@Jean-Marc Frappier, seems that nginx has a problem in reading the certs. Try to create some self-signed certs for test purpose. If that will work, most probably the certs are corrupted or in a format nginx does not understand.

So long

Thomas

@Thomas Deiler Figured it out. The person that ordered the wildcard certificate from Godaddy, didn't provide a key. After requesting a rekey, it was working fine on Friday and Saturday.

Now i'm getting a 502 bad gateway. Nginx log shows "[error] 13273#13273: *3 connect() failed (111: Connection refused) while connecting to upstream, client: 184.162.53.200, server: jira.mydomain.com, request: "GET /favicon.ico HTTP/1.1", upstream: "http://127.0.0.1:8080/favicon.ico", host: "jira.mydomain.com", referrer: "https://jira.mydomain.com/secure/Dashboard.jspa"

Thanks

JM

Thomas Deiler Community Champion Sep 09, 2018

Dear @Jean-Marc Frappier

a 502 is in most cases a call from nginx to the tomcat port of Jira that does not exist / is not open / is blocked by a firewall.

Check with

telnet localhost 8080

first in a shell of your server. If the server doesen't respond, then probably Jira is not running, or the port is a different one or some other service is already running at 8080 or a firewall rule is blocking local traffic from nginx to tomcat.

Please check also the configuration of this how-to, twice. Probably in the nginx configuration (/etc/nginx/sites-available/jira) the hostname is not the right one pointing to your server.

So long

Thomas

Hi @Thomas Deiler,

Awesome article! Just wanted to tell you that I learned a lot with this.

Thank you so much for sharing!

Cheers,

Matt

Thomas Deiler Community Champion Oct 16, 2018

Thanks, @Matheus Fulginiti Schonarth! Have you used a more up-to-date version of Jira than 7.9.0?

Thomas Deiler Community Champion Oct 16, 2018

Thanks, @Matheus Fulginiti Schonarth! Did you take a more recent version of Jira than 7.9.0?

Hi @Thomas Deiler,

You're welcome! I'm testing stuff with 7.9.0, but will test with other versions later.

Cheers!

Comment

Log in or Sign up to comment
Community showcase
Posted Mar 28, 2018 in Jira Software

Can a company’s culture make or break agile adoption?

Can a new-to-agile team survive and thrive in a non-agile culture? If so, what advice would you give to those trying to be agile in a non-agile culture? What's the key(s) to success? Share your thoug...

17,655 views 18 20
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you