mirror of
https://github.com/Alfresco/alfresco-sdk.git
synced 2025-05-26 17:25:11 +00:00
ccee83f92d
Reorganise the documentation content to fix the required folder structure and file naming for the migration to ABN.
235 lines
9.8 KiB
Markdown
235 lines
9.8 KiB
Markdown
---
|
|
Title: Working with AMPs
|
|
Added: v3.0.0
|
|
Last reviewed: 2019-01-14
|
|
---
|
|
# Working with AMPs
|
|
|
|
Since the early days of the Alfresco SDK, the Alfresco Module Packages (AMP) have been the way customizations were packaged. In Alfresco SDK 4.0 everything
|
|
is packaged as a JAR by default, while the AMPs are still available as an optional assembly. This gives you much more control over packaging, and simple
|
|
modules can easily be deployed as JARs.
|
|
|
|
The [Maven Assembly Plugin](http://maven.apache.org/plugins/maven-assembly-plugin/) allows you to control the final artifacts that Maven builds. You add the
|
|
plugin configuration and point it to an XML file that contains the full configuration on the artifact we want to produce.
|
|
|
|
## Building AMPs with Alfresco SDK 4
|
|
|
|
To build AMPs the SDK ships a default assembly XML file that will tell the assembly plugin how to produce an AMP file. You will find this file in
|
|
`src/main/assembly/amp.xml` (in the case of All-In-One project you'll find one descriptor for the platform JAR module and another for the share JAR module).
|
|
The plugin configuration is already present in your `pom.xml` file, as shown:
|
|
|
|
```
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-assembly-plugin</artifactId>
|
|
<version>2.6</version>
|
|
<executions>
|
|
<execution>
|
|
<id>build-amp-file</id>
|
|
<phase>package</phase>
|
|
<goals>
|
|
<goal>single</goal>
|
|
</goals>
|
|
<configuration>
|
|
<appendAssemblyId>false</appendAssemblyId>
|
|
<descriptor>src/main/assembly/amp.xml</descriptor>
|
|
</configuration>
|
|
</execution>
|
|
</executions>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.alfresco.maven.plugin</groupId>
|
|
<artifactId>alfresco-maven-plugin</artifactId>
|
|
<version>${alfresco.sdk.version}</version>
|
|
</dependency>
|
|
</dependencies>
|
|
</plugin>
|
|
```
|
|
|
|
This section is commented out by default.
|
|
|
|
1. To produce both a JAR file and an AMP, remove the comments and run the `mvn package` command.
|
|
|
|
Now you have full control over how your AMPs are built. If you want to change the content of the AMP, you can change the assembly `amp.xml` and tailor it
|
|
to your needs.
|
|
|
|
## Installing AMPs with the SDK
|
|
|
|
The projects created from the Alfresco SDK 4.0 archetypes are configured to deploy either JARs or AMPs to the ACS / Share docker container. The only thing to
|
|
do is modify the `pom.xml` file of the corresponding docker module / project in order to properly configure the dependencies and the Maven dependency plugin.
|
|
|
|
### All-In-One project
|
|
|
|
1. Modify the platform JAR dependency from the file `PROJECT_ARTIFACT_ID-platform-docker/pom.xml` to set the type of dependency to `amp`:
|
|
|
|
```
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.alfresco</groupId>
|
|
<artifactId>sample-module-platform-jar</artifactId>
|
|
<version>1.0-SNAPSHOT</version>
|
|
<type>amp</type>
|
|
</dependency>
|
|
</dependencies>
|
|
```
|
|
|
|
2. Modify the Maven Dependency Plugin in the file `PROJECT_ARTIFACT_ID-platform-docker/pom.xml` to set the platform JAR dependency type to `amp`:
|
|
|
|
```
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-dependency-plugin</artifactId>
|
|
<executions>
|
|
<!-- Copy the repository extension and the dependencies required for execute integration tests -->
|
|
<execution>
|
|
<id>copy-repo-extension</id>
|
|
<phase>pre-integration-test</phase>
|
|
<goals>
|
|
<goal>copy</goal>
|
|
</goals>
|
|
<configuration>
|
|
<artifactItems>
|
|
<artifactItem>
|
|
<groupId>org.alfresco</groupId>
|
|
<artifactId>sample-module-platform-jar</artifactId>
|
|
<version>1.0-SNAPSHOT</version>
|
|
<overWrite>false</overWrite>
|
|
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
|
<type>amp</type>
|
|
</artifactItem>
|
|
<!-- Test dependencies -->
|
|
...
|
|
</artifactItems>
|
|
</configuration>
|
|
</execution>
|
|
<!-- Copy other dependencies (JARs or AMPs) declared in the platform module -->
|
|
...
|
|
</executions>
|
|
</plugin>
|
|
```
|
|
|
|
3. Repeat these steps for the share module in the file `PROJECT_ARTIFACT_ID-share-docker/pom.xml`.
|
|
|
|
### Platform / Share project
|
|
|
|
1. Modify the Maven Dependency Plugin in the file `pom.xml` to set the platform / share JAR dependency type to `amp`:
|
|
|
|
```
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-dependency-plugin</artifactId>
|
|
<executions>
|
|
<!-- Copy the repository extension and the dependencies required for execute integration tests -->
|
|
<execution>
|
|
<id>copy-repo-extension</id>
|
|
<phase>pre-integration-test</phase>
|
|
<goals>
|
|
<goal>copy</goal>
|
|
</goals>
|
|
<configuration>
|
|
<artifactItems>
|
|
<artifactItem>
|
|
<groupId>org.alfresco</groupId>
|
|
<artifactId>sample-platform-jar</artifactId>
|
|
<version>1.0-SNAPSHOT</version>
|
|
<overWrite>false</overWrite>
|
|
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
|
<type>amp</type>
|
|
</artifactItem>
|
|
<!-- Test dependencies -->
|
|
...
|
|
</artifactItems>
|
|
</configuration>
|
|
</execution>
|
|
<!-- Copy other dependencies (JARs or AMPs) declared in the platform module -->
|
|
...
|
|
</executions>
|
|
</plugin>
|
|
```
|
|
|
|
Once this configuration is in place, you simply need to rebuild and restart the project. The new configuration will make the Docker images automatically
|
|
install the packaged AMPs in ACS / Share.
|
|
|
|
## Installing 3rd party AMPs
|
|
|
|
Installing 3rd party AMPs to the projects is pretty simple. The only requirement is adding the dependency to the project. The default configuration installs
|
|
any AMPs set as a maven dependency in the corresponding Docker image. It is important to remember that ACS and Share are separated containers, so you'll need
|
|
to add the dependency in the corresponding module in case of an All-In-One project.
|
|
|
|
Here is an example of how to install Florian Maul's Javascript Console.
|
|
|
|
```
|
|
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
|
<modelVersion>4.0.0</modelVersion>
|
|
<artifactId>sample-module-platform-jar</artifactId>
|
|
<name>Alfresco Platform/Repository JAR Module</name>
|
|
<description>Platform/Repo JAR Module (to be included in the alfresco.war) - part of AIO - SDK 4.0
|
|
</description>
|
|
<packaging>jar</packaging>
|
|
|
|
<parent>
|
|
<groupId>org.alfresco</groupId>
|
|
<artifactId>sample-module</artifactId>
|
|
<version>1.0-SNAPSHOT</version>
|
|
</parent>
|
|
|
|
<dependencies>
|
|
<!-- Add here any JAR or AMP dependency that needs to be deployed to ACS -->
|
|
<!-- Javascript Console AMP -->
|
|
<dependency>
|
|
<groupId>de.fmaul</groupId>
|
|
<artifactId>javascript-console-repo</artifactId>
|
|
<version>0.6</version>
|
|
<type>amp</type>
|
|
</dependency>
|
|
</dependencies>
|
|
|
|
...
|
|
</project>
|
|
```
|
|
|
|
## Controlling the order AMPs are applied
|
|
|
|
Under some specific circumstances it is necessary to apply different AMPs in a development project in a precise order. The default configuration of the
|
|
projects generated using the Alfresco SDK 4.0 archetypes doesn't specify any concrete order applying the AMPs to the ACS/Share installation.
|
|
|
|
Anyway, that order can be controlled modifying slightly the configuration of the custom Docker images in the project. For instance, let's say we have three
|
|
third party AMPs that we want to apply in the next order `third-party-amp-01.amp -> third-party-amp-02.amp -> third-party-amp-03.amp`. In this example, we're
|
|
going to consider we need to apply them to a platform JAR module (the process would be the same for a Share module, simply changing the path of the files).
|
|
|
|
1. Follow the steps described in the section [Installing 3rd party AMPs](#installing-3rd-party-amps) to include all the AMPs dependencies.
|
|
|
|
2. Locate the `Dockerfile` under the folder `src/main/docker`. In this file, there is a section that copies and applies the AMPs to the ACS installation.
|
|
|
|
```
|
|
# Copy Dockerfile to avoid an error if no AMPs exist
|
|
COPY Dockerfile extensions/*.amp $TOMCAT_DIR/amps/
|
|
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
|
$TOMCAT_DIR/amps $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
|
```
|
|
|
|
3. Replace the `RUN` command to execute one installation of AMP each time and copy it three times, ensuring the installation is executed in the required
|
|
order:
|
|
|
|
```
|
|
# Copy Dockerfile to avoid an error if no AMPs exist
|
|
COPY Dockerfile extensions/*.amp $TOMCAT_DIR/amps/
|
|
# Install third-party-amp-01
|
|
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
|
$TOMCAT_DIR/amps/third-party-amp-01.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
|
# Install third-party-amp-02
|
|
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
|
$TOMCAT_DIR/amps/third-party-amp-02.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
|
# Install third-party-amp-03
|
|
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
|
$TOMCAT_DIR/amps/third-party-amp-03.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
|
```
|
|
|
|
4. Rebuild and restart the project (use `run.bat` instead in Windows):
|
|
|
|
```
|
|
$ ./run.sh build_start
|
|
```
|
|
|
|
At this point, you have configured your project to apply the AMPs in a specific order.
|