Wednesday, January 30, 2013

Confluence Configuration Error

That's a broad title. A configuration error could be anything. It is unfortunately the best description I have for a problem that made no sense to me in its genesis, and will probably never happen again.

We're running Confluence version 3.3. One of our Marketing folks wanted to add a new Global Space to the Dashboard for a project he was working on but couldn't see a way to do it. There was no link to "Add New Space" or anything, so I told him I'd look into it. I wasn't all that familiar with Confluence beyond some basic administrative tasks, but I figured it was probably just hidden somewhere in the settings.



The first thing I did was to check permissions for the various groups set up in Confluence. I read through some quick documentation on how to create Spaces and what permissions were necessary to do so, and verified that everything in our setup was correct. All users had the Create Space permission, and there should have simply been a link to allow them to do that, but it was missing.

At this point it was clear that this was going to be more time-consuming than expected and since I was in the middle of trying to get Salt Stack set up for a major software/hardware deployment we're doing soon, I delegated the task of figuring out what was going on to our part-time Help Desk employee. He came to me a little later to explain that he had found a workaround which involved editing the default Dashboard page to add the link. Apparently "we" had edited that page at some point and taken out the lines that display a welcome message that also contains a link to creating a Space. The content looks like this:


Our edited template had removed a block of code that displayed this, so his idea was to put it back in. Unfortunately once he had done that, Confluence no longer worked. Instead there was a System Error page that reported an issue with a line in the file it called; it appeared to be a syntax error. The file in question was /decorators/global.vmd. The result was that you could get to the login page and enter your credentials, but you were immediately taken to this error page and couldn't go anywhere from there, meaning you also couldn't undo your changes.

I figured that we could log into the server itself, locate this file and edit it manually to put it back the way it was since he had copied and pasted the original into a text file on his machine, so we had something to reference. The first challenge was finding out where this file lived. I found it under /opt/atlassian, but editing it didn't change the error. It was still pointing to a syntax error at line 50 of the file, and no matter how we changed it it didn't remove or alter the error at all. I tried restarting Confluence just in case that was necessary to commit the change (although I doubted this since a restart wasn't necessary to make the change in the first place), and that yielded no results either.

At this point I figured that I was simply missing something simple in the configuration file, some closing tag that I wasn't seeing, so I enlisted the assistance of one of our developers. He determined that we weren't actually working on the live file after making some edits and also not seeing any changes. I did a locate for global.vmd and found that there were no fewer than 6 of these in different directories. Some of them were in directories whose labels indicated they were purely backups, but others could have been live. It turns out we also had two versions of Confluence installed, although only one was active. After editing multiple files (making backups of each before starting) it became clear that none of them were the file needed. I was stumped.

The developer then sent a link to these pages: https://confluence.atlassian.com/display/CONF30/Disable+Velocity+Caching and https://confluence.atlassian.com/display/DOC/Customising+Site+and+Space+Layouts. The first link talks about Velocity, which I was unfamiliar with, and how to disable caching so that you don't have to restart the server to see changes. Restarting Confluence wasn't a blocker for us though so it didn't seem applicable. The second link explained the differences in how Confluence implements changes to the templates when you do it from within Confluence versus changing it on disk which was interesting to know, but still didn't give us information the information we needed. We didn't have problems restarting the server at this point; it was finding the appropriate file to edit.

On that same page however was a link that proved to be the solution we needed. By navigating directly to
http://<confluence base url>/admin/resetdecorator.action?decoratorName=decorators/main.vmd
I was able to get into the GUI beyond the Dashboard, and then go back into the Layout section and edit the file from there. It turned out that in copying and pasting the Help Desk guy had missed a couple of lines. 

/adventure

No comments:

Post a Comment