[ACE-3025] consider moving all the config back to WEB-INF/classes/alfresco Created: 03-Oct-14  Updated: 14-Jan-16

Status: Open
Project: Alfresco One Platform
Component/s: Build
Affects Version/s: 5.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Romain Guinot Assignee: Mark Howarth
Resolution: Unresolved Votes: 4
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: HTML File alf-extract-config     File beansnapshot.json    
Issue Links:
is duplicated by ALF-21120 Alfresco community 5.0.a - missing fi... Closed
is related to by ACE-3324 vti.properties missing from Community... Verified
Cloud or Enterprise: Enterprise Only



I've noticed that in recent 5.0 builds, most of the config files that used to be in WEB-INF/classes/alfresco/... are now inside several jars instead.

I believe this is less convenient for several reasons :

  • accessing the reference config that would be needed to override such and such parameter now needs unzipping and searching across several jars
  • support will less easily spot customers who've modified stuff in the wars

Could we consider shipping all the config in WEB-INF/classes/alfresco again ?

Comment by Mehdi Belmekki [X] (Inactive) [ 03-Oct-14 ]

I would suggest either we ship the config in WEB-INF/classes/alfresco or as sample files in shared/classes/alfresco/extension/ so we can have an overview of what can be configured in the product.

Since repository.properties is as well shipped in the jars, I suggest we make available all properties (commented out) in alfresco-global.properties.sample

Comment by Samuel Langlois [X] (Inactive) [ 03-Oct-14 ]

Moved to ACE - this is a product issue, even if it's "only" its packaging...

The reason why configuration files are now embedded inside the jar files is that it's the standard in Maven, for resources.
The reason why it's the standard is that it's much easier to manage from a build point of view: the classes cannot work without the config, and the config cannot work without the classes, so let's stick them together instead of having to copy them separately.
For instance, the config of data-model is needed in alfresco.war, in the file-transfer-receiver, in solr, etc. Extracting it out of the jar would require copying it again and again.

This said, I understand the reason for this ticket.
There may be middle ground solutions, such as extracing the config resources just for alfresco.war (by duplicating them into WEB-INF/classes), or providing a separate zip, or documenting them better, or displaying them in the UI, etc.

The decision is a business decision, not a technical one, and I will happily hand over to POs, who know what the value of this would be for our beloved users

Comment by Peter Monks [X] (Inactive) [ 03-Oct-14 ]

Brian Remmington you'll be shocked to know that I do indeed have thoughts on this!

First up, I'm not clear on what precisely we're talking about. To my mind there are, at a high level, two different types of configuration setting (property in a .properties file, to be technical):

  1. those that are purely internal and where changes would put the customer into an unsupported state - let's call those ones "Private Configuration Settings"
  2. those that administrators are allowed to change (assuming they know what they're doing) - let's call these ones "Public Configuration Settings"

The former, as Mike said above, should be as hidden as possible, to discourage / prevent faffing. If extension developers wish to peruse these settings in order to understand how Alfresco works they should do so the same way they would for Java code i.e. by reviewing the source (which, with the Alfresco SDK, is easy to do in an IDE via the source JARs).

The latter is where things get a bit more complicated. At a minimum I think all Public Configuration Settings should be documented - I personally don't believe that the properties files themselves are an appropriate place for this, since it's hard to include large amounts of explanatory text (i.e. the circumstances under which an administrator would modify a given property, the valid values for that property, the default value, it's impact or relationship to other properties and features etc. etc.) without obscuring the properties themselves. Instead the properties files (both inside the WAR and, potentially in WEB-INF/classes) should include a very short description, along with a link to the relevant documentation, for each Public Configuration Setting.

In terms of actually placing the Public Configuration Settings in a readily accessible location, I don't particularly like the idea of duplicating a myriad of .properties files (whether "live" or as .properties.sample or wotnot) in WEB-INF/classes. I'd prefer to see the default values "embedded" in .properties files solely within the alfresco.war file (i.e. inside the JARs, as is currently the case), and then have customers apply their specific overrides in alfresco-global.properties. This makes it easier for support to obtain an accurate and complete snapshot of how the customer has customised their install. Adding every single available Public Configuration Setting to alfresco-global.properties, commented out, is a possibility, but I suspect there are too many of them for that to be practical.

It's also worth pointing out that this problem goes beyond .properties files - Spring context files have all of the same problems.

So in terms of next steps, I'd suggest that we:

  1. Expand the discussion to include all configurable elements (i.e. properties, Spring beans, JMX, etc. etc.)
  2. Ensure there is a clear, comprehensive and unambiguous internal list of which configurable elements are Public vs Private, so that we're all on the same page (not to be shared publicly)
  3. Ensure all Private configurable elements are sufficiently hidden, to prevent (or, at minimum, discourage) customer faffing
  4. Come up with a consistent and comprehensive plan on how the Public configurable elements should be documented by us, and modified by customers when necessary. Today we have a bit of a Wild West situation, and that makes support's job harder than it should be.

I realise this isn't the quick answer Romain Guinot may be hoping for, but I think this is too important a topic to half-bake, and that there are other dependencies (e.g. on the installer) that we haven't considered yet. I also suspect that we don't have time to address this for 5.0, so would suggest we leave things as-is for that release, and make this a high priority for vNext (5.1 or wotnot).

Comment by Richard Esplin [X] (Inactive) [ 16-Oct-14 ]

This is a very useful discussion about how developers can find configuration properties in our software. Is there any reason why all of the comments are restricted to Alfresco?

Comment by Levin Ulrich [ 17-Oct-14 ]

From my (support) point of view this change does not make our lives easier. I guess even more complicated since it is:

  • more complicated to figure out if something in the jars has been changed
  • needed to explain customers where to get the default values from to copy them
  • an additional place to look at for configuration changes

It means also that we either have to have the source code for all service packs and all hotfixes to check default values against customer set values or we need to know (from an internal documentation) for all properties files in which jar file they are located (if they are all in one "configuration jar" that would be good and easy accessible)

Please keep in mind that a lot of customers administrators are not engineers or developers. To ask them to get the source code or to extract jar files will be in such cases difficult and would increase the time support spends in cases or on calls explaining this.

  • For reference configuration access: Don't we have or can't we have somehow a way to access those properties and context files in an online resource? This would at least solve this problem.
  • For changes inside jar files we would still need an easy way to spot those. But someone here might have a solution for that as well in mind
Comment by Peter Monks [X] (Inactive) [ 17-Oct-14 ]

Corentin Roux [X], Levin Ulrich - thanks for the feedback - I understand (and share) your concerns. The unfortunate reality is that this issue came to light pretty late in the 5.0.0 release cycle, so as a fallback we're going to work on documenting how supported configuration changes should be made. That documentation will describe approaches that are entirely outside the webapp (i.e. don't require anyone to look at or modify JARs or WARs).

We'll take another look at this once 5.0.0 is released and we have the luxury of time to address configuration properly.

Comment by Peter Monks [X] (Inactive) [ 22-Oct-14 ]

To expand on my last comment (since this continues to come up):

For 5.0.0 we'll be leaving the on-disk layout alone, and sysadmins will be able to read the documentation that describes most (ideally all) supported configuration tasks. Developers (who are not a primary audience for this functionality) will be able to view any configuration file in the system via the source code (which the Alfresco SDK makes trivially available). If we do get support tickets on this, we’ll be able to address them quickly by updating the documentation (which doesn’t require any kind of development or product release cycle) - a nice tight feedback loop.

I’ll be the first to admit it’s not a great solution (especially for existing customers who are familiar with the legacy approach), but the quick assessment we performed concluded that it’s the best compromise for 5.0.0 given:

  • the high risk of changing anything in the 5.0.0 code, configuration or build at this late stage
  • that the legacy mechanism is fundamentally flawed (i.e. it amplifies support costs, as Gab explained)
  • the lack of clarity right now around which configuration options are Public (supported for customer modification) vs Private (internal implementation details that invalidate support if modified by a customer)
  • the incomplete understanding of customer requirements - the recent feedback we’ve received on this has all been internal, and internal folks do not accurately represent our target audience i.e. customer sysadmins

Rest assured that everyone involved understands that this is a sub-optimal solution, and work has already commenced on what a better mechanism might look like beyond 5.0.0. What we don’t need right now is anyone undermining these tactical decisions - there’s been plenty of confusion already.

Comment by Richard Mcknight [ 12-Feb-15 ]

From a developer standpoint, I have not been able to search for a particular bean by bean ID or by class. The *-context.xml files are buried in the jar files and search does not seem to extend into the jars. Unless I am missing something in configuring Eclipse

Comment by Peter Monks [X] (Inactive) [ 13-Feb-15 ]

Richard Mcknight source JARs are automatically configured into Eclipse by the Alfresco SDK v2.0. At that point you can do a resource (or file or whatever) search to find the files you need, either by name or by content.

Comment by Peter Monks [X] (Inactive) [ 13-Feb-15 ]

My apologies - it's a "file search", not a "resource search". The Eclipse documentation for this feature is at http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Freference%2Fref-45.htm

Comment by Gethin James [X] (Inactive) [ 13-Feb-15 ]

Perhaps another option?

As of Spring 3.1 there's a feature called "Live Beans Graph", we couldn't use this on Alfresco until 5.0. I followed the instruction here to see them in STS. Its a bit slow but...it appears to make an Mbean available in "Default Domain -> attributes -> SnapshotAsJson". This json snapshot has all the bean definitions and where they are loaded from (I have attached it to this issue).

Perhaps all you need to do is search the attached json to find the bean you are interested in?

Comment by Richard Mcknight [ 13-Feb-15 ]

This seems like a useful feature – what might be more useful is to add this to the admin console (or create a webscript) that can find the location of a bean. I will have a look.

Generated at Thu Jul 09 10:12:12 BST 2020 using JIRA 7.6.3#76005-sha1:8a4e38d34af948780dbf52044e7aafb13a7cae58.