Or, why you don’t want to use the Alfresco admin console in production
The Alfresco admin console—to config, or not to config? Such is the dilemma for the administrator: to suffer the noble but outrageous fortune of restarting the server for every change to alfresco-global.properties? Or seize the admin console to put an end to his tribulations?
Luis Colorado
Alfresco Software
Engineer at Zia
More senior Alfresco administrators seem to be inclined to using the traditional configuration files, but more adventurous administrators prefer the admin console. Who is right?
There are several ways to set the properties in Alfresco. The most common methods are:
- Putting the properties in the file alfresco-global.properties. Changing settings here always requires a restart to make them effective.
- Setting the properties using the admin console. This is a friendly, and less error-prone, way to change settings. As an extra bonus, in many cases, the changes become effective immediately (which often means that no restarts are needed!) and will apply to all the servers in a cluster. Those features sound pretty sweet, but there are some other important gotchas that you must know.
Gotchas Galore!
Catch 1: Properties set in alfresco-global.properties will be ignored
Has it ever happened to you? You keep trying different values for a setting in alfresco-global.properties, but Alfresco seems to ignore your changes! If you have had that problem, it is likely that you (or someone else) set those values using the admin console. The properties set using the admin console will always override the settings in alfresco-global.properties.
Catch 2: What you set in the admin console stays there…forever! (well, almost)
When you save a setting using the admin console, jconsole, or some other JMX client, it is saved to the JMX backend which is ultimately stored in the database. Once you save a set of properties using the admin console, from that point on you will have to use the admin console to change them again because Alfresco will ignore those changes to those properties in alfresco-global.properties.
Catch 3: All or nothing
If you edit a single value on a page of the admin console, it doesn’t only write that one value to the database but all the other settings on that page as well. For example, even if you change only the Solr host name in the Search Service, the Solr ports, Solr base URL, etc. will also be saved to JMX.
Catch 4: Servers in a cluster may need different settings
Although in most cases it is desirable to have all the servers running with the same settings, that can be a problem in some situations. In a clustered environment, each server will have an alfresco-global.properties file. Those files can have differences (for example, each server may point to a different Solr server) as some scenarios may require it.
Catch 5: Reverting is possible but not always easy
If you ever want to use alfresco-global.properties again to set properties, you have several options to revert those settings:
- Using jconsole or some other JMX client.
- Alfresco’s admin console has a revert feature named “JMX Settings,” but unfortunately it doesn’t work correctly at the moment. Due to a yet-to-be-fixed bug, it reverts to the last setting listed on the page even if you selected something else.
Catch 6: Settings can’t be deployed to another environment
If I have failed so far to dissuade you from using the Alfresco admin console in production, this may do the trick: Although the humble file alfresco-global.properties may seem pretty low-tech and cumbersome, it can easily be copied and deployed to other environments. Good luck trying that with your settings in admin console.
So, what is the admin console good for?
The admin console, so shiny, so convenient…is it useless after all? No!
Some Admin Console Tips
Although the admin console should not be used to configure production under normal circumstances, there are cases where it is really handy!
Logging
A notable exception are the log4j logging settings. This is the only place where you want to use the admin console in production. The settings here have an immediate effect which allows you to debug issues in the logs. Furthermore, the settings are automatically reverted to the values in your log4j.properties file upon restart.
Testing and Troubleshooting
When you need to test some settings or troubleshoot an issue without having to restart a non-production server, the admin console is a great tool. However, at the end of your testing session, it would be a good idea to revert those settings to avoid surprises.
Documenting your settings with a JMX dump
JMX dumps are a treasure trove of information about an Alfresco system. They contain most of the actual settings and internal properties plus other valuable information that will help you diagnose and troubleshoot problems in your system. Learn more about generating and analyzing JMX dumps in our other article.
Conclusion
You should never use the Alfresco admin console to make changes in production, except in the case of emergencies and adjusting the logging levels. The console remains a great tool to quickly test the effects of different settings, but, as those settings can’t be exported or imported, the admin console can’t part of a proper deployment workflow.