Document custom configurations
Managing Activator typically involves making custom changes to fit your processing needs. This can mean editing system files or adding your own scripts and Java classes for purposes such as post-processing, in-line processing, parsing, pluggable transports or other custom changes.
The extent of custom changes depends on the complexity of your configuration. Regardless of the complexity, the best practice is to document your changes and keep copies of custom scripts or code files.
Activator provides a file system directory to help in documenting custom changes. The directory is <install directory>\site. A readme text file there provides an overview. An advantage of using the site directory is that upon upgrading to a new version, the contents of the site directory from the old installation directory tree are copied to the new version as part of the installation process.
The site directory has subdirectories with the following recommended uses.
- bin – Store copies of your post-processing scripts, other scripts or executable files. Where possible in the user interface, use a relative path to point to this directory (for example, for a post-processing script). After upgrading to a new version, you do not have to alter the path in the UI.
- conf – Store copies of custom configuration files. Your source code should refer to this directory as
../site/conf.
- doc – Store text documents containing notes about custom changes. These can be notes about any changes that would be a useful reference for someone performing an upgrade or disaster recovery.
- For example, if you edit the
alerts.xml or events.xml file in <install directory>\conf, document the changes in a text file and save it here. When upgrading, use the notes to make the same changes to the alerts.xml or events.xml in the new version.
- Note that it is not recommended to make backup copies of changed system files for the purpose of substituting the backed up files for ones in a newly installed application. This is because system files may have been changed by the software developers between an old and new version of the application. This is especially true of the
filereg.xml file. The filereg.xml file installed with a new version should always be used.
- Custom changes for some values in system files do not require documenting because they are forwarded during an upgrade by the application installer. This includes the
commonPath entry from filereg.xml.
- JARs – Store Java archive (JAR) files and class files for in-line processors, pluggable transports, JMS, and custom parsers. Any classes in this directory are included automatically in the classpath before
<install directory>\jars. This includes JAR files; there is no need to explicitly add them to the classpath.
- webapps – Custom web applications developed by users that are to be deployed upon server startup.
Related topics