Configuration Files Location

With the release of Confluence 2.6.0, many files have been moved inside the main .jar file, which means they can no longer be edited by simply opening and saving a file.

Background

For those not familiar with the terminology, a .jar file is a Java ARchive file. It's like a Unix .tar file (or a Windows .zip file), and is managed by a very similar command-line tool jar which is included with the JDK. Essentially, it 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.

Instructions

To edit a file that exists inside a .jar file, you need to unpack the archive, perform the desired edits, then re-pack the archive:

For a shortcut, drop the file in the WEB-INF/classes directory, creating the appropriate parent directories if necessary. This will take priority over what's in the jar file and allow you to edit the file more easily.

Special Note for Websphere

It's a bit inconvenient to modify files - add patches or configure velocity or xml files - if you have to rebuild and redeploy the war file. Websphere requires deploying Confluence as a built .war archive originally. After that, however, you can drop files in the exploded war directory and restart the application in the Websphere Console to pick up changes. For the case of Velocity (vm or vmd) files or jsp files, you don't even need to reload the application - just refresh your page!

A typical exploded war directory might be found in a path similar to:

/usr/lib/IBM/WebSphere/AppServer/profiles/AppSrv03/installedApps/serverName-laptopNode01Cell/confluence-2_10_2_war.ear/confluence-2.10.2.war/

Keep in mind that this isn't a technique for deploying war files, but rather for modifications after deploy.

Unix or Linux
  1. Shut down Confluence
  2. Create a new working directory, e.g. /tmp/confluence-working
  3. cd into that directory
  4. Extract the contents of the .jar: jar xf </path/to/file.jar>. To edit the main confluence .jar: jar xf $CONFLUENCE/confluence/WEB-INF/lib/confluence-2.6.0.jar. You now have a directory structure, or at least a set of files, which are the contents of the .jar archive
  5. Edit the file or files
  6. Ensure the original .jar is not in the working directory. If you copied or moved it there for unpacking, delete it or move it elsewhere, to prevent it becoming part of the new archive.
  7. Repack the archive: from within the working directory, issue the command jar cf </location/of/new/archive/file> * to produce a new archive under /tmp. The asterisk is significant, as that tells jar to include all files and directories within the working directory. E.g. jar cf /tmp/confluence-2.6.0.jar *, in our example here. Some operating systems will allow you to create a zip archive and rename .zip to .jar. Make sure you're bundling the contents of the directory, not the contents within the directory.
  8. Take a backup copy of the original .jar file. It's often convenient to leave it in the main Confluence directory and just rename it to something like confluence-2.6.0.jar.original. Make sure the file name does not end with a .jar extension.
  9. Copy the new .jar into <confluence-install>/confluence/WEB-INF/lib/. Make sure the old version of the jar has been removed.
  10. Restart Confluence
Windows or OS X

If you're familiar with the command line, you can use the Unix instructions above on a Windows or OS X system as well. Alternatively, you can use just the OS User Interface:

  1. Shut down Confluence
  2. Copy the <confluence-install>/confluence/WEB-INF/lib/confluence-x.y.z.jar file.
  3. Extract the contents of the .jar file using an unzipping utility like Winzip, 7-zip, Stuffit or the OS X Archive Extractor.
  4. Edit the file or files
  5. Ensure the original .jar is not in the working directory. If you copied or moved it there for unpacking, delete it or move it elsewhere, to prevent it becoming part of the new archive.
  6. Repack the archive: from within the working directory, rezip the files using your utility. Make sure you are zipping the contents of the file, not the "confluence-x.y.z" parent folder that encloses all the files.
  7. Take a backup copy of the original .jar file. It's often convenient to leave it in the main Confluence directory and just rename it to something like confluence-2.6.0.jar.original. Make sure the file name does not end with a .jar extension.
  8. Copy the new .jar into <confluence-install>/confluence/WEB-INF/lib/. Make sure the old version of the jar has been removed.
  9. Restart Confluence
RELATED TOPICS

Installing Patched Class Files
Where are the files that used to be in my Confluence installation directory?

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.