Difference between revisions of "Module Management Tool"

From alfrescowiki

Jump to: navigation, search
(Mention that uninstall command is now available)
m
 
(2 intermediate revisions by the same user not shown)
Line 16: Line 16:
 
== Running the MMT ==
 
== 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:
 
Run the following command:
   java -jar alfresco-mmt-2.1.jar [args]
+
   java -jar alfresco-mmt-<version>.jar [args]
It is compatible with V2.0 WAR files and above.
+
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.
 
'''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.
Line 36: Line 47:
 
   -directory : indicates that the amp file location specified is a directory.
 
   -directory : indicates that the amp file location specified is a directory.
 
                 All amp files found in the directory and its sub directories are installed.
 
                 All amp files found in the directory and its sub directories are installed.
   -force    : forces installation of AMP regardless of currently installed module version
+
   -force    : forces installation of AMP regardless of currently installed module version or file overrides
 
   -preview  : previews installation of AMP without modifying WAR file
 
   -preview  : previews installation of AMP without modifying WAR file
 
   -nobackup  : indicates that no backup should be made of the WAR
 
   -nobackup  : indicates that no backup should be made of the WAR
Line 50: Line 61:
  
 
Example:
 
Example:
#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
+
$ 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'''
 
'''list'''
Line 60: Line 71:
 
Lists the details about all the modules currently installed in the WAR file specified.  The output is directed to the console.
 
Lists the details about all the modules currently installed in the WAR file specified.  The output is directed to the console.
  
'''disable'''    <font color='red'>'''Note:''' this command is to be done and is not yet available.</font>
+
'''uninstall'''    <font color='red'>'''Note:''' available since Community 4.2.</font>
  
 
<pre>
 
<pre>
usage: disable <moduleId> <warFile>
+
usage: uninstall<moduleId> <warFile>
 
</pre>
 
</pre>
  
'''enable'''    <font color='red'>'''Note:''' this command is to be done and is not yet available.</font>
+
'''disable'''    <font color='red'>'''Note:''' this command is not yet implemented.</font>
  
 
<pre>
 
<pre>
usage: enable <moduleId> <warFile>
+
usage: disable <moduleId> <warFile>
 
</pre>
 
</pre>
  
'''uninstall'''    <font color='red'>'''Note:''' available since Community 4.2.</font>
+
'''enable'''    <font color='red'>'''Note:''' this command is not yet implemented.</font>
  
 
<pre>
 
<pre>
usage: uninstall<moduleId> <warFile>
+
usage: enable <moduleId> <warFile>
 
</pre>
 
</pre>
  
 
== Best (and Worst) Practices ==
 
== 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.
+
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.
  
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 warWhen 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.
+
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).
 
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).

Latest revision as of 00:48, 4 July 2014

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. 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}:

  1. amps
  2. 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).

Personal tools
© 2014 Alfresco Software, Inc. All Rights Reserved. Legal | Privacy | Accessibility