Module Management Tool
Back to Developer Guide
What is the Module Management Tool?
The module management tool (MMT) helps manage 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.
As of v3.1.1 (and possibly earlier),
alfresco-mmt.jar is available in the "bin" directory of your Alfresco installation.
Running the MMT
Run the following command:
java -jar alfresco-mmt-2.1.jar [args]
It is compatible with V2.0 WAR files 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.
The MMT has a number of commands. Details of these are outlined below:
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 -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.
- java -jar alfresco-mmt-2.1.0.jar install /root/alfresco-recordsmanagement-2.1.0.amp /usr/jboss-4.0.3SP1/server/default/deploy/alfresco.war
usage: list <warFile>
Lists the details about all the modules currently installed in the WAR file specified. The output is directed to the console.
disable Note: this command is to be done and is not yet available.
usage: disable <moduleId> <warFile>
enable Note: this command is to be done and is not yet available.
usage: enable <moduleId> <warFile>
uninstall Note: available since Community 4.2.
usage: uninstall<moduleId> <warFile>
Best (and Worst) Practices
It is good practice to do a -preview install prior to doing the install for real. This reports the modifications that will occur on the WAR without making any physical changes. The changes that are of most importance to note are those that are going to update existing files.
As a general rule it is considered bad practice to overwrite an existing file in an AMP, however it is sometimes necessary. The MMT makes a backup copy of the updated file and stores it in the war. When an update of the module occurs and the old files are removed, this backup will be restored prior to the installation of the new files. Problems may occur if multiple installed modules modify the same existing file. In these cases a manual restore may be necessary if recovery to an existing state is required.
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).