Using War Overlays with Crafter Engine
Crafter Engine, the delivery component of CrafterCMS is completely programmable with scripted Groovy. From time to time:
you may find that you want to build classes in Java directly
or you may need to include dependencies in a deployment where Ivy and Grapes are not an option
or you may need to modify the
web.xmlof the engine WAR file for some reason.
These scenarios are an exception but they do come up. For these scenarios, you want to create a Maven WAR Overlay. Overlays allow you to add and override contents of CrafterCMS component WARs like Crafter Studio, Engine, Profile, and Social.
An overlay is a very simple maven project that downloads a specific version of Crafter Engine (specified in the POM file), downloads the additional dependencies you require, builds your source code that’s specific to your project, packages it to a jar and then combines all of these into a new WAR file.
Let’s create an example where we simply want to overlay a dependency into the jar, for example, the Amazon AWS SDK.
Step 1: Create a project structure
Create a directory structure as follows:
+--my-project (project root directory)
|
+--src
|
+--main
|
+--java (your class structure starts here)
|
+--webapp (any files you want to override or include in the webapp like web.xml)
Step 2: Create your Maven POM file
In a file at my-project/pom.xml put the following contents:
1<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/xsd/maven-4.0.0.xsd">
2 <modelVersion>4.0.0</modelVersion>
3 <groupId>com.mysite</groupId>
4 <artifactId>craftercms-engine-overlay</artifactId>
5 <version>1.0.0-SNAPSHOT</version>
6 <packaging>war</packaging>
7 <name>craftercms-engine-overlay</name>
8 <description>craftercms-engine-overlay</description>
9
10 <properties>
11 </properties>
12
13 <dependencies>
14 <dependency>
15 <groupId>org.craftercms</groupId>
16 <artifactId>crafter-engine</artifactId>
17 <version>3.0.8</version>
18 <type>war</type>
19 </dependency>
20
21 <!-- ADD YOUR DEPS HERE -->
22 <dependency>
23 <groupId>com.amazonaws</groupId>
24 <artifactId>aws-java-sdk</artifactId>
25 <version>1.11.289</version>
26 </dependency>
27 </dependencies>
28
29 <build>
30 <finalName>ROOT</finalName>
31
32 <plugins>
33 <plugin>
34 <!--<groupId>org.apache.maven.plugins</groupId>-->
35 <artifactId>maven-compiler-plugin</artifactId>
36 <version>3.3</version>
37 <configuration>
38 <source>1.8</source>
39 <target>1.8</target>
40 </configuration>
41 </plugin>
42
43 <plugin>
44 <artifactId>maven-war-plugin</artifactId>
45 <version>2.1.1</version>
46 <configuration>
47 <workDirectory>target/overlay-war-folder</workDirectory>
48 <overlays>
49 <overlay>
50 <groupId>org.craftercms</groupId>
51 <artifactId>crafter-engine</artifactId>
52 </overlay>
53 </overlays>
54 </configuration>
55 </plugin>
56 </plugins>
57 </build>
58</project>
Note
Note that the above POM file is very simple. It simply states that you want to download Crafter Engine 3.0.8, Download Amazon’s 1.11.x SDK and then recombine these into a new Engine WAR file called ROOT.war in the output directory target folder.
Step 3: Run the Build
Type the following command in your project directory: mvn clean package
Similar output to the following is expected:
1mvn clean package
2[INFO] Scanning for projects...
3[INFO]
4[INFO] ------------------------------------------------------------------------
5[INFO] Building craftercms-engine-overlay 2.2.8-SNAPSHOT
6[INFO] ------------------------------------------------------------------------
7[INFO]
8[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ craftercms-engine-overlay ---
9[INFO] Deleting /Users/myuser/code/test-war-overlay/target
10[INFO]
11[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ craftercms-engine-overlay ---
12[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
13[INFO] skip non existing resourceDirectory /Users/myuser/code/test-war-overlay/src/main/resources
14[INFO]
15[INFO] --- maven-compiler-plugin:3.3:compile (default-compile) @ craftercms-engine-overlay ---
16[INFO] No sources to compile
17[INFO]
18[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ craftercms-engine-overlay ---
19[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
20[INFO] skip non existing resourceDirectory /Users/myuser/code/test-war-overlay/src/test/resources
21[INFO]
22[INFO] --- maven-compiler-plugin:3.3:testCompile (default-testCompile) @ craftercms-engine-overlay ---
23[INFO] No sources to compile
24[INFO]
25[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ craftercms-engine-overlay ---
26[INFO] No tests to run.
27[INFO]
28[INFO] --- maven-war-plugin:2.1.1:war (default-war) @ craftercms-engine-overlay ---
29[INFO] Packaging webapp
30[INFO] Assembling webapp [craftercms-engine-overlay] in [/Users/myuser/code/test-war-overlay/target/ROOT]
31[INFO] Processing war project
32[INFO] Processing overlay [ id org.craftercms:crafter-engine]
33[INFO] Webapp assembled in [780 msecs]
34[INFO] Building war: /Users/myuser/code/test-war-overlay/target/ROOT.war
35[INFO] WEB-INF/web.xml already added, skipping
36[INFO] ------------------------------------------------------------------------
37[INFO] BUILD SUCCESS
38[INFO] ------------------------------------------------------------------------
39[INFO] Total time: 3.658 s
40[INFO] Finished at: 2018-03-07T21:11:09-05:00
41[INFO] Final Memory: 14M/309M
42[INFO] ------------------------------------------------------------------------
Step 4: Deploy Your New WAR
In the project folder, you will now see a target folder with a ROOT.war in it. This is your new WAR file. You can now place this in the webapps folder of your CrafterCMS authoring or delivery server.