Purpose

Sometimes modifying Jira's internal file structure is required, for example, when you need to customize an email template in Docker. When editing inside a container manually, changes are destroyed when the container is modified. This article describes how to apply such customizations in a way that will persist after the container is recreated. 

Solution

In Docker, individual files or directories can be mapped to files and directories on the host operating system. This can be leveraged to edit files much like you would do if not running in a container.

If using docker run

1. Create a copy of the file you wish to modify, and store it on the host operating system

2. Modify the file contents as desired

3. Destroy your existing container with docker rm
   
   1. Please note that this will remove any data in the container that is not explicitly mounted externally through volumes or bind mounts

4. Modify your docker run syntax to add a -v element containing the file mapping. The syntax is -v path_on_host:path_in_container. For example:

   docker run -v jiraVolume:/var/atlassian/application-data/jira -v /home/user/docker/issueassigned.vm:/opt/atlassian/jira/atlassian-jira/WEB-INF/classes/templates/email/subject/issueassigned.vm  --name="jira" -d -p 8080:8080 atlassian/jira-software

If using docker-compose

1. Create a copy of the file you wish to modify, and store it on the host operating system
2. Modify the file contents as desired
3. Create or edit the volumes section of your docker-compose file to map the file on the host to the file in the container. The syntax is: path_on_host:path_in_container. As an example:

volumes:
      - /home/user/docker/issueassigned.vm:/opt/atlassian/jira/atlassian-jira/WEB-INF/classes/templates/email/subject/issueassigned.vm

Restart the container via docker-compose down and docker-compose up to apply changes. This command will result in the container being rebuilt, which results in any direct modifications to the container to be lost.

Important note

Certain files inside the container are replaced by the template engine in order to apply environment variables settings. For example, server.xml is replaced with the content of template file server.xml.j2, with variables ATL_PROXY_NAME, ATL_PROXY_PORT, and so on replaced.

We recommend you leverage environment variables to customize these files where available. If there is a customization you with to apply that is not exposed as an environment variable, you can simply copy, customize, and mount the  .j2 version of the file as per the instructions in this article, which will be copied across to the correct location upon container start. However, do note that any environment variable customisation will be lost, so you may need to set these explicitly in your customized file.

For more information, see Jira on Docker Hub