How to use custom images in Jira and share them in a cluster
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
The content on this page includes steps to customize or extend Atlassian software (adding/changing CSS rules, HTML, JavaScript, etc.). Per the Atlassian Support Offerings, support does not include customizations made to Atlassian products. Be aware that this material is provided for your information only and using it is done so at your risk.
If you have any questions about this or any customization, please ask the community at Atlassian Community or consider working with an Atlassian Solution Partner.
By default, Jira stores static files in the working directory configured in Tomcat.
This folder is by default local to each node, and located at the install path:
1
${catalina.home}/atlassian-jiraIt's configured on the server.xml file on each node, on the Context docBase attribute:
1
2
3
4
<Engine name="Catalina" defaultHost="localhost">
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false" useHttpOnly="true">
...So any file put into an existing or new folder inside the /atlassian-jira/ directory can be accessed in HTML code (if enabled) inside Jira, like in Dashboards, Announcement Banner or Custom Field descriptions.
In a clustered environment, the static file must be replicated in each node's respective installation folder.
Environment
Any version of Jira Software or Jira Service Management, Data Center or Server.
Solution
To use custom images
Save the file into an existing or new folder inside the <Jira_Install>/atlassian-jira/ directory
You can then reference the file in HTML
For example, if Jira doesn't have a context path configured and you save the image to the ${catalina.home}/atlassian-jira/customImages/image1.png directory, you can reference it using <img src=/customImages/image1.png>.
If Jira does have a context path, you can reference it using <img src=/<contextPath>/customImages/image1.png> (eg. <img src=/jira/customImages/image1.png>)
To share custom images in a cluster
You may configure another Context in Tomcat with a different path and the docBase pointing to the shared-home folder:
1
<Context docBase="/path-to-shared-home/sharedimages" path="/sharedimages"></Context>You may add it right above or below (careful not to add inside) the existing Context in the server.xml.
You may then create the sample sharedimages folder on the shared-home path and every resource you add there would be available at each node on the path:
1
https://jira-base-url/sharedimages/some-image.pngKeep in mind you'll need to consider this customization to server.xml and the shared-home folders when re-installing or migrating Jira to another server.
Was this helpful?