How to edit files in Confluence JAR files
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 relates to platforms that are not supported by Confluence. Consequently, Atlassian can't guarantee providing any support for the steps described on this page. Please be aware that this material is provided for your information only, and that you use it at your own risk.
The files in Confluence JAR files need to be customized. Follow the instructions below.
Solution
In Confluence, many files are contained inside a JAR file. This page tells you how to customize such a file:
Extract the contents of the JAR file into a working directory.
Edit one of the files extracted from the JAR.
Place the updated file in a location that Confluence will recognize. Files in this location will override the version of the file in the JAR.
Note that by using the instructions below, you don't need to bundle the updated file back into the JAR.
About JAR Files
A JAR file is a Java ARchive file. It is similar to a UNIX tar file (or a Windows zip file). To manage a JAR file, you can use the jar
command-line tool which is included with the JDK. The jar
tool takes several files or an entire directory structure, and compresses them together into a single file. This saves a little space, and makes it much easier to manage that group of files as a single unit. The terms 'file' and 'archive' can be used interchangeably in this context, as they refer to the same collection of bytes.
Customizing a File Contained within a Confluence JAR File
These instructions assume that you already know which JAR file contains the file you need to edit.
To customize a file contained with a JAR:
Shut down Confluence.
Create a new working directory, for example
/tmp/confluence-working
.Change directory (
cd
) to your working directory.Extract the contents of the JAR:
jar xf </path/to/file.jar>
For example, to edit the main Confluence JAR file for Confluence 3.5:
1
jar xvf $CONFLUENCE/confluence/WEB-INF/lib/confluence-3.5.jar
You now have a directory structure, or at least a set of files, which is the contents of the JAR archive.
Find the file that you need to update, edit the file and save it.
Examine the structure of files and folders in your working directory, which was created when you extracted the content of the JAR.
Files in the root level of your structure can be recognized by Confluence if you put them in the
/WEB-INF/classes/
folder. For example, if you modify theschedulingSubsystemContext.xml
file, you can place it in<confluence install>/confluence/WEB-INF/classes/schedulingSubsystemContext.xml
.Files in a subdirectory of your structure need to be placed in a similar subdirectory under
<confluence install>/confluence/WEB-INF/classes/
. For example, if you modify thefonts/verdanaz.xml
file, you must put it in<confluence install>/confluence/WEB-INF/classes/fonts/verdanaz.xml
.
Re-compress the contents of the JAR:
jar uvf </path/to/file.jar>
For example, to recompress the edited files within the main Confluence JAR file for Confluence 3.5:
1
jar uvf $CONFLUENCE/confluence/WEB-INF/lib/confluence-3.5.jar <path to edited file>
Restart Confluence.
Notes
As an alternative to the jar
utility, you can extract the JAR file using an unzipping utility like Winzip, 7-zip, Stuffit or the OS X Archive Extractor.
Additionally, text editors such as EMACS and VIM support being able to edit files directly within the .jar without expanding the contents first.
Related Topics
Was this helpful?