Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Back to Developer Guide
What is the Module Management Tool?
The module management tool (MMT) helps manage [[AMP Files | AMP
(Alfresco Module Package)]] modules installed in a standard Alfresco WAR file.
The module management tool supports the following: installation of AMP modules including upgrades to later versions, enabling and disabling of installed modules, de-install of installed modules and listing of currently installed modules.
AMP Modules are packaged and installed as AMP files. An AMP File relates to a specific module and version. During the installation of an AMP the module and version are taken into consideration.
Since v2.1, the Module Management Tool is available as a separately downloadable JAR file from the Alfresco release download area (e.g. alfresco-mmt-2.1.jar).
As of v3.1.1 (and possibly earlier), alfresco-mmt.jar is available in the 'bin' directory of your Alfresco installation.
Running the MMT
Via the apply_amps Script
Alfresco provides a ${ALFRESCO_HOME}/bin/apply_amps.[sh|bat] script that avoids the need to manually construct MMT command lines and also takes care to clean up Tomcat properly.
It is recommended that you use this script rather than executing MMT manually.
To use this script, create the following two folders underneath ${ALFRESCO_HOME}:
- amps
- amps_share
Any AMPs that you wish to install into the repository can be placed in the amps subdirectory, and those destined for Share in amps_share. The apply_amps script will pick up all of the AMPs in both folders, and apply them to the appropriate WAR file in a single operation.
Manual Execution
Run the following command:
java -jar alfresco-mmt-<version>.jar [args]
It is compatible with Alfresco v2.0 and above.
Note that in some cases you must run $ALF_HOME/scripts/setenv.sh before this command, and to set $ALF_HOME and $CATALINA_HOME (as in $ALF_HOME/bin/apply_amps.sh) is also recommended. Otherwise you may get confusing Java class errors.
MMT Commands
The MMT has a number of commands. Details of these are outlined below:
install
usage: install <AMPFileLocation> <WARFileLocation> [options]
valid options:
-verbose : enable verbose output
-directory : indicates that the amp file location specified is a directory.
All amp files found in the directory and its sub directories are installed.
-force : forces installation of AMP regardless of currently installed module version or file overrides
-preview : previews installation of AMP without modifying WAR file
-nobackup : indicates that no backup should be made of the WAR
Install installs the files found in the AMP file into the Alfresco WAR, updating it an older version is already installed. If the module represented by the AMP is already installed and the installing AMP is of a higher release version, then the files relating to the older version will be removed from the WAR and replaced with the newer files.
It is the responsibility of the module developer to provide the appropriate Module components to bootstrap or patch any data as required when updated WAR is run.
If the installing module version is less than or equal to the version already installed in the WAR then installation will be aborted unless the -force option is specified. In this case the installing AMP will always replace the currently installed version. This option is especially useful when developing an AMP.
Before an AMP is installed into a WAR a copy of the original WAR is taken and placed in the same directory. Specifying the -nobackup option prevent this from occurring.
Example:
$ java -jar alfresco-mmt-4.2.0.jar install /root/alfresco-recordsmanagement-2.1.0.amp /usr/jboss-4.0.3SP1/server/default/deploy/alfresco.war
list
usage: list <warFile>
Lists the details about all the modules currently installed in the WAR file specified. The output is directed to the console.
uninstall Note: available since Community 4.2.
usage: uninstall<moduleId> <warFile>
disable Note: this command is not yet implemented.
usage: disable <moduleId> <warFile>
enable Note: this command is not yet implemented.
usage: enable <moduleId> <warFile>
Best (and Worst) Practices
It is good practice to do a preview install prior to installing an AMP, particularly if it's a 3rd party AMP that you didn't develop yourself. This reports the modifications that will be applied to the WAR, without making any actual changes to it.
It is bad practice to overwrite an existing file in the alfresco.war via an AMP, and by default MMT will prevent AMP files that override existing files from being installed (excluding, of course, files that a previous version of the same AMP installed - AMP upgrades are fully supported by MMT). Rarely, however, overrides are required (e.g. with some kinds of Share extension), and can be allowed via the '-force' flag. In this case MMT will make a backup copy of the file being overridden and will attempt to restore it if the AMP is uninstalled at a later time. Problems will occur if multiple installed modules override the same file however, hence the recommendation to avoid overriding existing files.
Note that some app servers (notably Tomcat) do a poor job of cleaning up their temporary working files, and this can (and often does) interfere with successful installation of an AMP file. To remedy this situation, it is recommended to delete (or move) the tomcat work and temp directories while Tomcat (Alfresco) is shut down, and prior to restarting it (you can use the clean_tomcat.sh script in 'bin'). You will also have to remove the ~/tomcat/webapps/alfresco directory (make sure to backup any file you have modified in this directory).
Administration
AMP
Deployment
Packaging
