Below is a complete walkthrough on how to set up and configure a new client Jira from start to finish, taking information from previously created pages and bringing it all under one place.
Where applicable, there will be links to previously used pages.
Create the client Jira container¶
Start with opening the terminal.
DON'T CLOSE THE TERMINAL AT ANY POINT!
Not until you are 100% sure Jira is ready. Also ensure you have "Limit Scrollback to" disabled (see image below) so that you can view all details required.
- Ssh into Cluster 2 by entering
ssh cluster2into the terminal.
- Change the directory with
Pick a client name for the Jira that is short but recognisable
- It'll be a good idea to input the command
containerListso that you have a list of names already in use.
- Normally we try aim for 4 or less characters.
- It'll be a good idea to input the command
You then need to input the following command, changing the "clientname" to the name you have chosen.
- For example:
bash .run.bash ecis what we might use for Edmonds Commerce.
bash ./run.bash clientname
- For example:
You will then see the terminal going through the script and eventually reach a point where it asks you the following:
Enter the number 1 in the terminal and press enter to continue.
When the script is finished, go to
jira.CLIENTNAME.edmondscommerce.net, replacing "CLIENTNAME" with the client name you assigned to the container earlier on.
REMEMBER, keep the terminal open!
Setting up the Jira database¶
Now that we have the container set up and you've followed the correct link, you should see the following in your browser.
- Click on "I'll set it up myself" and hit "Continue to MyAtlassian". You'll be taken to the database setup.
Scroll up in your terminal until you see the following.
Note: Using Shift+Ctrl+F and searching for "You can now access" will jump to the terminal lines you need.
Select MySQL 5.6 and enter the database details from the terminal in the corresponding fields in your Jira tab.
For the "Username" and "Password" entries at the bottom, you'll need to run another command in the terminal.
Open a new tab and do
sshContainer clientname-jirato access the Jira container you made, and then do
cat ~/.my.cnf. This will display the following information below.
When all entries are done, hit "Test Connection". If you've entered the details correctly, you should see the following confirmation.
Upon confirmation, hit "Next".
Set Up Application Properties¶
On the next screen, enter the name of the client's Jira you are creating. For example, for Edmonds Commerce, we would call it "Edmonds Commerce Jira". For this page, we'll call it "Set Up Example Jira".
Make sure "Mode" is set to "Private" and keep the base URL the same.
Hit next when done.
Specify Your License Key¶
The next part of the set up requires assistance from the client. You'll need the License Key that the client obtained after they purchased Jira, but they will require the Server ID you see on this page in order to view it.
Head over to the client's shared folder on the google drive (or create one if needed) and create a folder called "Jira".
Inside the "Jira" folder, create a blank Google doc and call it "Access Details".
Inside the doc, enter "Server ID:" and "License Key:" and paste the Server ID as shown below.
The client will then need to paste the License Key into this document for us to use.
Send them an email explaining that we are setting up their Jira and that we require this key from them. They should already have access to the file you created since it's in a shared folder. If not, then share it with them. Below is an example of an email regarding this. The link the the article that we included above also has instructions on how to find the License Key in their Jira account.
I've started the set up for Jira and I'm now at the stage where I require the license key to continue.
You should have received an invitation to the shared Google folder I've put together for you.
Inside it, you'll find another folder called "Jira". Inside that folder is a file called "Access Details" where you will find the Server ID needed to receive the key.
When you have the key, please paste it into that same file and I'll pop in for it and continue the set-up.
You'll want to purchase the $10 license with no aditional products, which can be found here.
Feel free to check out the following page in our online handbook for a step-by-step walkthrough showing what you need to select on the purchase screen.
The link in the article that we included above also has instructions on how to find the License Key in their Jira account.
Once you receive an email from the client informing that they have added the Key to the doc, paste it into the box we saw earlier on and hit "Next".
Set up Administrator Account¶
On this page, we'll set up the "Admin" account for the Jira. Enter the fields with the following information shown below.
Note: Set the password to the current master password. If unsure, speak to admin team.
When done, hit "Next".
Set Up Email Notifications¶
Next, we'll be asked to configure outgoing emails.
This can be done later on in Jira, so for now, select "Later" and hit "Finish".
You'll then be asked which language you'll like to use with Jira.
Obviously, select "English (UK)". Hit "Continue" when ready.
Choose An Avatar¶
Since this is the admin account, we use the EC logo as our avatar. You can download a coy of it here.
- Click "Choose Avatar" and then navigate to where you downloaded the logo after clicking on "Choose file".
If that went through okay, resize the draggable box to it's full width then hit "Confirm".
Hit "Next" when done.
Unknown Server Error¶
Follow these steps below if you've received the following error after trying to upload the logo.
- Open the terminal and ssh to the Jira's container using
- Use the following command:
vim /opt/atlassian/jira/conf/server.xmlto open the config.
- You'll see the following lines of code, starting on line 31.
Add the following just under the last line, keeping within the corner brackets.
proxyname="jira.[client_name].edmondscommerce.net" proxyPort="443" scheme="https"
It should look like the following:
With that done, stay in the terminal and use the command
systemctl restart jirawhist still root.
This will restart the container and refresh the server config.
Wait for the command to finish and refresh your Jira page.
Log into Jira with the account information we created earlier on.
Select your language and follow the "Choose An Avatar" steps again.
Hit "Next" When done.
Create a New Project¶
Next, we'll need to create our first project.
1. Select "Create New Project" form the middle option.
2. Select "Kanban Board Development" from the window that appears and click on "Next" and then "Select" on the next window.
![Kanban Software Development](New-Jira-Setup-Images/Kanban-Software-Development.png)
- Next we need the name and Key for the project. If it's a Magento site we're working on, call it "Magento". If not, then name it after the client The key will be created automatically. Hit "Submit" when you're happy.
Live Jira Config¶
That's all the initial set up done for the new Jira! We now move onto configuring the live instance of Jira, giving it the functionality it requires.
New Jira Template Tasks¶
To make sure we're setting up everything we need for these Jiras, we follow a task template in the admin Jira which contains a set of subtasks. Each of these subtasks represent a feature that we need to enable.
You can find the template here.
This will need to be cloned for each new Jira we make.
Click on "More" and then click "Clone".
Replace "CLONE" with the new Jira name, tick "Clone Links" and hit "Create".
When these tasks have been cloned and are ready to be worked on, you will be directed to the page of your newly cloned task and subtasks.
Start following the list set out down below.
Jira Template Task List¶
Note: These tasks that you made aren't in a specific order to follow, and some will have to be completed before others. The following steps will take you through the order they should be completed in.
- Create Project for Client Site
- Create "Jira Itself Project"
- Create Info Sharing Project and Disable Notifications
- Create Custom Issue Scheme
- Create Cancelled Status
- Set Up Email Sending
- Set Up Slack Web Hook
- Install Plugins
- Set Up Users
- Make Internal Users Jira Admin
- Create and Implement Custom Dashboards
- Look and Feel
- Get Licence Installed With client
- Give the Client a Tour
Create Project for Client Site¶
During the initial set-up, we already did half of this by creating the "Magento" project.
On the op bar of the Jiira page, click on the cog icon on the top right and click "Projects" from the drop down menu.
![Projects Administration](New-Jira-Setup-Images/Projects Administration.png)
You'll see a list of projects. To the right of the "Magento" project, click on the three dots and then "Edit" from the drop down menu.
We want to add the Magento logo to the project. Save a copy of the image down below.
Click on "Select Image" from the edit window and upload the logo.
Resize the logo so we can see it all and then hit "Confirm"
Back in the "Details" window, hit "Save Details" at the bottom.
Create Jira Itself Project¶
The next project we need to make is for discussing and sharing anything that we or the client need to know for Jira.
Click on the "Projects" drop down menu at the top of the page and click on "Create Project".
Under the "Business" section, click on "Task Management" and hit "Next", followed by "Select" on the next window.
Set the name to "Jira Itself" and the key to "JI", then hit "Submit".
Create Info Sharing Projects and Disable Notifications¶
This project is used to share information such as login credentials and any other sensitive information we require for the work.
We disable notifications to prevent these details being included in any Slack integration updates and the emails that Jira send out.
Create a new project using the "Task Management" type, the same we we just did with "Jira Itself" and call it "Info Sharing".
You will be directed to the projects "Issue Viewer", with a few links on the left hand side of the page. At the bottom of this collumn, click on "Project Settings".
You'll now see another list of links under where it says "Project Settings". Further down the list, click on "Notifications".
On the "Notifications" page, click on "Actions" at the top right and hit "Use a Different Scheme".
Select "None" from the "Scheme" drop down menu and then "Associate" underneath it.
For disabling notifications in Slack, please see the "Set Up Slack Webhook" section of this guide.
Create Custom Issue Scheme¶
Here is where we determine which issue types are going to be used for the Magento project.
Firstly, we need to make the "Question" issue type.
Click on the "cog icon again in the top right and click "Issues".
On the right hand side of tha page, click on "Add Issue Type".
Set the name as "Question" and the type as "Standard Issue Type". When ready, hit "Add".
You'll be redirected to the "Issue Types" screen. To the right of the new "Question" entry in this list, click on "Edit".
Click on "Issue Type Avatar" and then select the green "?" image from the row provided.
When done, click on "Update".
We now need to create the Issue Scheme itself.
On the left hand side of the screen, near the top of the column, click on "Issue Type Schemes".
On the right, click on "Add Issue Type Scheme".
Name the Issue Scheme after the client and state it's a custom one. So, for this one, since this is "Example Jira" we'll call it "Example Custom Issue Scheme".
Next, we'll choose which issue types we want in this scheme. In the box shown below, click on "Add All".
In the box on the left side, drag "Story" over to the box on the right to exclude it from the collection of issues we want to use. When that's done, hit "Save".
After doing this, you'll be taken back to the collection of Issue Type Schemes. On the right hand side next to the Scheme you created, click on "Associate".
From the list of projects, select "Magento" and then click "Associate".
That's the Issue Type Scheme taken care of for the question issue type. You now need to repeat the steps above for improvement and new feature. Improvement logo is an up arrow and the new feature logo is a plus.
Create Custom Workflow and Cancelled Status¶
We now want a custom workflow creating the the "Magento" project and include the "Cancelled" status as part of it.
Click on the cog in the top right of the page and click on "Issues".
When you've been taken to that page, click on "Workflows" in the column on the left.
Within the list of workflows, you should see the one shown in the image below:
To the right of that entry, click on "Copy".
- Rename it to match the name of the Jira as well as stating that it's a custom workflow.
You'll be taken to the diagram of the workflow, which shows us the structure of the workflow statuses and how they
transition into each other.
To create the "Cancelled" status, click on "+ Add Status" at the top left above the diagram.
Type in "Cancelled", select it from the menu when it appears, make sure "Allow all statuses to transition to this one" is checked, and then click "Add".
In the new window, make sure "Category" is set to "Done" and then hit "Create".
You'll now see the status included in the diagram.
Click on the arrow next to the green "Cancelled" block and then click on "Post Functions" which can be found at the right hand side of the screen.
When you've been taken to the next page, click on "Add Post Function" on the top row of the table towards the bottom of the page.
Make sure the last option, "Update Issue Field" is selected and then click "Add".
Set the "Issue Field" to "Resolution" and then the "Field Value" to "Won't Do".
You'll now see that what we've just done has been added to the post functions for this status.
Now, we want to associate this Workflow with the Magento project.
Click on "Workflow Schemes" in the left column.
Click on "Add Workflow Scheme" at the top right, and then name the Scheme after the Jira, as well as stating that it's a custom one. When ready, click "Add.
You'll then be redirected to the page for that Workflow Scheme. Click on the "Add Workflow" drop down menu and then select "Add Existing".
In the new window, click on the Workflow we made earlier on. If you've selected the correct one, you should see the cancelled status in the diagram preview. When you're happy with your selection, click on "Next".
On the next window, make sure all Issue Types are checked and then click "Finish".
Now at the top of the page, click on the "Projects" tab and then select the "Magento" project.
Select "Workflows" from the list of options under "Project Settings".
At the top right on the next page, click on "Switch Scheme".
Select the Workflow Scheme you made and click "Associate". Keep clicking "Associate" until that goes through.
That's it for the custom workflow and cancelled status.
Configure Time Tracking and Add to Tickets.¶
We need our time estimates for pending tasks displayed on each ticket in Jira.
To do this, head over to the system setting by clicking on the "Cog" icon and then clicking on "System".
In there, hit the full stop button and search for "Time Tracking" in the search filed that appears at the top of the screen.
Click it to start configuring this option.
In order to edit this, you'll need to deactivate it first.
Change the values and selection options to match the image below and then re-activate it.
Now, head over to the main project for the Jira you are activating this for and click on "Create" at the top of the page.
In the "Create Issue" window, click on "Configure Fields" and then "Where is my field?"
In the new window that open up, type "Time Tracking" in the search box and click on the result.
You'll then see the following display if Time Tracking isn't visible on the ticket creation window.
To fix this, click on the link labelled "MAG: Kanban Default Issue Screen' Screen configuration" where it says "Field Screen" with the red X next to it.
You'll be redirected to a configure screen for the issue creation fields.
Scroll to the bottom of the page and enter type "Time Tracking" in the text field. Click on the result when it appears and then click on "Add".
We can now set correct time estimates in this client's Jira.
Setup Email Sending¶
Next, we need to configure the settings for the emails that Jira sends out.
Head into the "System Settings" by clicking on the cog again and clicking "System".
in the left hand column again, scroll down and click on "Outgoing Mail".
Once you're on that page, click on "Configure new SMTP mail server".
Next, you'll need to fill in the following fields below:
Follow the information in this document to fill in the fields.
When that's done, click "Test Connection" to make sure it's working. If all is good, click "Add".
Setup Slack Web Hook¶
The following task requires you to have admin privileges in Slack. If you don't have this, please speak to the admin team.
Head over to the System Settings by clicking on the cog and clicking "System".
In the column on the left, scroll down and click on "Webhooks".
On the top right, click on "Cr2eat2e Webhook".
Name the Webhook after the Jira and keep the Status as "Enabled".
Now, on another screen, head to Slack, click on the drop down menu in the top left, go down to "Administration" and click on "Apps".
This will open a window in your browser displaying the apps that Slack is using.
Scroll down and select the "Jira Server Alerts (Legacy)" app.
Click on "Add Configuration" to start the integration.
Pick the quest channel from the drop down menu that we made for the client. For the purpose of this example, I'll be linking this webhook to my personal slack message feed.
- The guest channel name starts with "#guest-", followed by the client's name
- If the client doesn't currently have a Slack channel, create one by clicking on "Create New Account" and then invite them to it at a later time.
When you're happy, click "Add Jira Integration".
When you've been taken to the setup instructions, scroll down to "Step 3" and copy the red URL.
Paste this into the URL field back on the Webhook page in Jira.
Next, we want to configure what we want the intergration to send through Slack.
We only want certain updates from the project for the client website (typically the "Magento" project).
In the "Events" field, type in
project = Magento AND project != "Info Sharing". The "project = Magento" part gives the webhook access to the "Magento" project, and the "AND project != Info Sharing" part tells the webhook to exclude the Info Sharing project.
Next, we need to tell the webhook what updates we want to see from the Magento project.
Tick the boxes in the "Events" section so that they match up with the ones down below.
When you've done this, hit "Create".
You'll get a confirmation at the top of the screen telling you that the webhook has been created.
To make sure this works, head over to the client site project in Jira, create a new ticket called "Test Ticket for Slack" and keep your eye on the Slack channel you linked the webhoko too. If it worked, then it should appear in the channel.
Since we also added a rule for the Info Sharing project, head into there and create a ticket with the same name, "Test Ticket for Jira". If this has been set up correctly, you shouldn't see anything come through into the channel.
Plugins can be found in the Atlassian Marketplace and can either be purchased for Cloud and Software platforms, or added free for either one of them.
We'll go over implementing a free one.
Click on "Get it now" towards the top of tha page.
Click on "Get it now" under the hosting type you want to install the plugin on (typically Server).
You'll then be asked to download the plugin. Save it somewhere memorable as we'll need it later on.
Now head over to the Jira you'd like the plugin on. When you've logged in (and assuming you have admin privilages) press fullstop ,type "Manage Apps" and hit enter.
You'll see a list of the plugins that we already have installed currently. Above the list, click on "Upload App".
Then click "Choose file" and select the plugin file we downloaded earlier. When ready, click "Upload".
You'll see a brief progress bar showing that the plugin is being installed, followed by a confirmation popup.
Set Up Users¶
Now we need to create an account for the Internal users (Admin team and developers).
Click on the cog and click on "User Management".
In the top right, click on "Create User".
We want to make the accounts for the following people:
- The developer working on the project (Is decided and is not Ken or Dan).
We had already created an "Admin" account at the beginning of this walkthrough.
Go ahead and enter the information to create these accounts. Make sure "Application Access" is set to "Jira Applicaiton" and that "Create Another" is ticked. Keep this ticked until you've created the final account.
The password is the master pass. Ask admin if you're unsure.
Make Internal Users Jira Admin¶
Now that we have all our current internal users created, we need to add them to the "Jira Administrators" group.
By default, the Admin user we create at the start is added to the "Jira Administrators" group.
- You are able to view which group each user in this list under "Group name". Next to that, to the right, click on the 3 dots and select "Edit User Groups".
Type "Admin" into the bar at the top of the new window and then click it to add it to the list below.
Click "Join Selected Groups" to add them to the "Current Groups" list.
1 2 3
That window will close, however, you should see that the new group as been added to the list we saw earlier. ![Group Name](New-Jira-Setup-Images/Group-Name.png)
Rinse and repeat this for all internal users.
Create and Implement Custom Dashboards¶
The "Dashboard" is the landing page you come to when visiting a Jira. We're able to add widgets to this page so that we can present project information at a glance.
Head over to System settings using the cog in the top right.
Under "User Interface" in the left hand side column, click on "System Dashboard".
You'll now see a preview of the dashboard.
At the top right of the dashboard preview, click on "Add Widget".
To start with, you'll only see 2 options in the new window that appears. To view more of these widgets to add, click on "Load All Gadgets".
On the left hand side, search for "Pie" in the search field. This will automatically display the "Pie Chart" in the window. We want 3 copies of this widget, so click the "Add Widget" button 3 times.
These will now appear on the dashboard preview.
These 3 widgets all need to display slightly different information for the Magento/Client site project. The information we need to display is "Status", "Assignee" and "Issue Type".
In the first widget, type "Magento" or the name of the client site project into the "Project or Saved Filter" field.
From the drop down menu below that, choose "Status". Make sure you also check "Auto Refresh" to get accurate updates from this widget.
It should look like the following:
Click "Save" to add that to the dashboard. You'll then see it load up on the preview.
Repeat this step for the other 2 widgets to display "Assignee" and "Issue Type".
Remeber the test ticket we made for Slack? If you left that in the project, it will now display in the widget, showing you that that has worked as intended. If you no longer had the ticket, create a new test on to see if this updates the widget.
Check this for all 3 widgets. They should look like the following:
Finally, since we added them pie charts, it pushed the "Introduction" widget to the bottom of the page. Click and drag the move symbol in the top right of the widget and drag it to the top of the page above the pie charts.
Look and Feel¶
The final part of the live Jira config is the overall "Look and Feel" of the Jira. We can change the logo used as well as the colours in Jira to reflect that of the client, giving it more of a personal touch for the client.
Firstly, head over to "System Settings" and click on "Look and Feel" under "User Interface" on the left hand side.
The first thing we can do is upload the company logo to the Jira, which will be displayed on the header bar at the top of the page. Head to the client's website and save a copy of their logo. Then, click on "Choose File" to upload it.
When you've selected the logo, you'll see the file name displayed next to the "Choose File" button.
When ready, hit "Upload Logo".
The page will refresh, and you'll see that the logo has been uploaded as well as a confirmation informing you that, subsequently, the Jira colour scheme has also been changed to match that of the logo.
(Optional) We also have the choice to set a new Favicon for the Jira. If you have a decently sized image for this, click on "Choose File" and upload the image. When one is selected, click on "Upload Favicon".
Scrolling further down, you'll see setting for customizing the colours of certain elements in Jira. These will of been changed after uploading the new logo, but there is one colour which we need to change our self.
Under "Gadget Colours", the default colour for the widget background is blue. If this fits the colour scheme for the client, then it's safe to leave that as is. However, if not, simply click on the colour box next to "Color 1 (Default)" and pic the colour you require. When ready, click "Update" on the right hand side.
Head over to the Jira's dashboard to see if that has worked as intended.
Get Licence Installed With client¶
Now that the Jira is up and running, we need to get the client to install the certificate needed for them to access it, as well as creating an account for them. But first, we need to do some terminal work to obtain the correct certificate.
Open the terminal and enter
cd ~/Downloads/and then
- Replace [CLIENTNAME] with the begining part of their Jira container. For example, for the admin jira is on "admin-jira",
so for this one, we'd do
- Replace [CLIENTNAME] with the begining part of their Jira container. For example, for the admin jira is on "admin-jira", so for this one, we'd do
This will download the certificate onto your machine. Head over to "Home" in your file viewer and look for the ".cert" folder.
- If you can't see this folder in your "Home" folder, click on the drop down icon at the top right and make sure "Show Hidden Files".
Once you've found the certificate you need in the ".cert" folder, head over the client's Google Drive shared folder and upload this to their "Jira" folder.
Next, you'll need to add 3 files to this folder. These files are instructional documents that tell the client how to install these certificates depending on which internet browser and OS they are using (Chrome, Firefox and Mac OS).
We have created templates for these files which you can find here.
Shift click the top file and then the bottom file to select them all. Right click on the and select "Make a Copy".
Right click and rename these copies, replacing "Copy of" with the client name followed by "Jira".
Head into each file you've copied and replace "CLIENTNAME" (remember to change the link text AND the hyperlink) with the first part of the Jira container name "like we did when obtaining the certificate."
After you've edited all 3 files, we can go ahead and move them to the client's shared folder. Select the 3 files you need to move, right click and select "Move to".
Navigate backwards in the pop up window to get to "Client SHARED FOLDERS" and within that, find the client folder you're looking for.
Find the "Jira" folder within that client shared folder and click on "Move Here" to move these files.
We now need to create the Jira account for the client. Head back over to Jira, and navigate to "User Management".
Click on "Invite Users" at the top right.
Enter the email address for the person you're creating the account for, **BUT DO NOT** click "Invite Users" yet!
Until they have installed the certificate, they won't be able to follow their email invitation to create the account.
Head over to the email thread that you've been discussing Jira in with the client. We want to inform them that their Jira is up and running and requries the certificate installation BEFORE the accept the invitation to create an account.
Send an email to them based off of the example below:
I've been working through the Jira set up today and it's almnost ready for you to view.
You'll soon receive an invitation to Jira asking you to create an account. Before you can do this though, you'll need to install the certificate in your internet browser before you can access the Jira.
We've added a few instructional files, as well as the certificate to the client shared folder we have with you.
You can find it here.
include hyperlink in word "here"
Once you've installed that, head back to the email and use the invitation to create your account.
If you require any assistance with this, do feel free to get in touch and we'll look at helping you out with this.
Also, we like to offer virtual tours of Jira over Skype via screenshare to give you a better understanding of what we use it for and where you can find certain parts of the software. If you would like us to conduct one of these with you. please let us know and we'll get that booked in!
Once you have sent this email, click on "Invite User" on the Jira page that should still be open.
Give the Client a Tour¶
As we mentioned in the email we sent in the last step, the client may take up our offer of a tour of Jira.
We'll need to get them added on Skype, but below is a list of things to go through during the tour.
- Basic explanation of what we use Jira for.
- Show them the client site project.
- Talk about creating tickets, commenting and attachments, ticket types and the kanban board/workflow for the project.
- Show and talk about info sharing and Jira itself projects.
- Any other questions they may have.