CQ MAVEN METHODSCQCON 2013

HELLO WORLDI'm Andrew.

asavory@adobe.com

@savs

Joined Adobe in November 2012

CQ Newbie

JCR/CMS/TLA old hat

Background in Open Source, Content Management, Mobile

Talking today about what I learned so far...

FORK ME!If you found this talk useful, or spotted mistakes:

github.com/savs/CQCon_2013_CQ_Maven_Methods

IN YOUR BROWSERhttp://goo.gl/qqS1F

SEE ALSOhttp://www.planetcq.org/

LET'S BUILD A CQ SITE

... uh, where to begin?

METHOD 1Enthusiastically rush in, use CRXDE Lite

METHOD 2I'm a guru, I use Eclipse and CRXDE

METHOD 3I'm a ninja, I use emacs and vlt

METHOD 4I'm a guru ninja, I use vi and curl

METHOD 5

See also: http://xkcd.com/378/ – Real Programmers

BUT WHAT ABOUT ...reverting mistakes?

reproducible builds?

collaborating with others?

deploying to production?

WHY ISN'T IT EASIER TO BUILD A CQ SITE?Laborious project inception

No two projects alike

Don't know project layout

Don't know project dependencies

Hard for others to reproduce

Hard to test

Lengthy RTFM or worse (no FM)

Documentation over convention

CQ SUCKS

$PRODUCT SUCKS

YOUR METHODOLOGY SUCKS(sorry)

SO HOW DO WE FIX THIS?Maven

Git(or Subversion, or CVS ... ymmv)

Best Practices

MAVEN“Maven is a software project management

and comprehension tool. Based on the

concept of a project object model (POM),

Maven can manage a project's build,

reporting and documentation from a central

piece of information.”

GIT“Git is a free and open source distributed

version control system designed to handleeverything from small to very large projects

with speed and efficiency. ”Version control is a system that records changes to a file or set of files over

time so that you can recall specific versions later.

BEST PRACTICES“A best practice is a method or technique that

has consistently shown results superior tothose achieved with other means.”

In addition, a "best" practice can evolve to become better as improvementsare discovered.

WHAT DO WE WANT?Minimal customisation

Standardised way to create a project

Standardised way to build a project

Standardised way to deploy a project

Standardised way to test a project

Standardised way to share a project

OUR TARGET

Success criteria:

IT'S EASY TO BUILD A CQ SITE!

GETTING STARTEDInstall Maven: http://maven.apache.org/guides/getting-

started/

Install Git: http://git-scm.com/book/en/Getting-Started-Installing-Git

CONFIGURING MAVENMaven has a settings file that defines things likerepositories where plugins can be downloaded (typically~/.m2/settings.xml).We need to add a profile to point to the Adobe repository.We then specify this repository when we use thearchetype plugin.

See also: Obtaining the Content Package Maven Plugin

CONFIGURING MAVEN<profile> <id>adobe-public</id> <activation> <activeByDefault>false</activeByDefault> </activation> <properties> <releaseRepository-Id>adobe-public-releases</releaseRepository-Id> <releaseRepository-Name>Adobe Public Releases</releaseRepository-Name> <releaseRepository-URL>http://repo.adobe.com/nexus/content/groups/public</releaseRepository-URL> </properties> <repositories> <repository> <id>adobe-public-releases</id> <name>Adobe Basel Public Repository</name> <url>http://repo.adobe.com/nexus/content/groups/public</url> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>adobe-public-releases</id> <name>Adobe Basel Public Repository</name> <url>http://repo.adobe.com/nexus/content/groups/public</url> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories></profile>

CONFIGURING MAVENEnable the repository:

Or use the -P option to activate profile(s):

<activeProfiles> <activeProfile>adobe-public</activeProfile></activeProfiles>

mvn -P adobe-public [...]

USING MAVEN

STARTING A NEW PROJECT ...

... can sometimes feel like reinventing the wheel.

YOU ARE HERE

ARCHETYPESarchetype |ˈɑːkɪtʌɪp|

noun

a very typical example of a certain person or thing: he wasthe archetype of the old-style football club chairman.an original which has been imitated; a prototype: aninstrument which was the archetype of the early flute.

MAVEN ARCHETYPESA prototype upon which others are

copied, patterned, or emulated.

WHAT CQ ARCHETYPES ARE THERE?simple-content-package

Generates a simple

multimodule-content-packageIncludes the folder structure for developing a CQ

application (content package and bundle).

cqblueprints multi-moduleThird-party archetype encapsulating best practices for

working with e.g. OSGi bundles, taglibs, and CQ content

See also:

content package

How to work with packages

ON PACKAGESPackages enable the importing and exporting of repositorycontent. They are used to install new functionality, transfercontent between instances, or back up the repositoryA package is a zip file in file system (vault) serializationformatPackages include meta information - filter definitions,import configuration, package propertiesPackages are often managed through the CQ Package Manager

ON BUNDLESBundles are modular containers of functionality for OSGi –

essentially a java module that contains application logic

Bundles consist of java classes and other resources needed

to deliver functionality or to provide services to other

bundles.

Bundles can be managed through the CQ

See also:

Web Console

Creating OSGi bundles using CRXDE

HOW TO USE AN ARCHETYPE

archetypeGroupId: identifies the archetype projectuniquely across all projectsarchetypeArtifactId: the name of the archetype jarwithout a version numberarchetypeRepository: where to get the archetype from(based on pluginRepository in settings.xml)

See also: and

mvn archetype:generate -DarchetypeGroupId=foo -DarchetypeArtifactId=bar -DarchetypeVersion=1.0.0 -DarchetypeRepository=baz

Maven: Introduction to Archetypes Maven: Naming conventions

SIMPLE CONTENT PACKAGE ARCHETYPEFrom the fine manual:

“Creates a maven project that is suitable for

installing resources for a simple CQ

application. The folder structure is that used

below the /apps folder of the CQ repository.

The POM defines commands for packaging

the resources that you place in the folders and

installing the packages on the CQ server.”

SIMPLE CONTENT PACKAGE USAGE

archetypeGroupId: com.day.jcr.vaultidentifies the archetype project uniquely across all projectsarchetypeArtifactId: simple-content-package-archetypethe name of the archetype jar without a version numberarchetypeRepository: adobe-public-releaseswhere to get the archetype from (based onpluginRepository in settings.xml)

mvn archetype:generate -DarchetypeGroupId=com.day.jcr.vault -DarchetypeArtifactId=simple-content-package-archetype -DarchetypeVersion=1.0.1 -DarchetypeRepository=adobe-public-releases

SIMPLE CONTENT PACKAGE IN ACTION

SIMPLE CONTENT PACKAGE PARAMETERSgroupId: Like a package name, e.g.com.yourcompany.myprojectartifactId: name of the jar without the version, e.g.myprojectversion: accept the defaultpackage: not used in simple-content-packageappsFolderName: name of /apps/myproject, e.g. myprojectartifactName: Description in Package ManagerpackageGroup: Group in Package Manager

See also: Maven: Naming conventions

SIMPLE CONTENT PACKAGE OUTPUTTemplate directoriespom.xml file

Instructions for compiling, creating bundles, deployingto CQ in packages

FileVault configuration files

MULTIMODULE CONTENT PACKAGE USAGEmvn archetype:generate -DarchetypeGroupId=com.day.jcr.vault -DarchetypeArtifactId=multimodule-content-package-archetype -DarchetypeVersion=1.0.1 -DarchetypeRepository=adobe-public-releases

MULTIMODULE CONTENT PACKAGE OUTPUT${artifactId} |- pom.xml |- bundle |- pom.xml |- src |- main |- java |- ${groupId} |- SimpleDSComponent.java |- test |- java |- ${groupId} |- SimpleUnitTest.java |- content |- pom.xml |- src |- main |- content |- jcr_root |- apps |- ${appsFolderName} |- config |- install |- META-INF |- vault |- config.xml

|- filter.xml |- nodetypes.cnd |- properties.xml |- definition |- .content.xml

CQBLUEPRINTS MULTI-MODULE USAGEFirst add the CQ Blueprints Maven Repository to Maven'ssettings.xml, then:

archetypeGroupID: com.cqblueprints.archetypesarchetypeArtifactId: multi-modulearchetypeVersion: 1.0.5archetypeRepository: cqblueprints.plugins.releases

See also: and

mvn -P cqblueprints archetype:generate -DarchetypeGroupId=com.cqblueprints.archetypes -DarchetypeArtifactId=multi-module -DarchetypeVersion=1.0.5 -DarchetypeRepository=cqblueprints.plugins.releases

Connecting to the CQ Blueprints Repository The CQ Project Maven Archetype

CQBLUEPRINTS MULTI-MODULE OUTPUT${artifactId} |- README |- pom.xml |- ${artifactId}-all |- pom.xml |- ${artifactId}-config |- ${artifactId}-content |- ${artifactId}-services |- ${artifactId}-taglib |- ${artifactId}-view

WHY USE CQBLUEPRINTS MULTI-MODULE?

The cqblueprint multi-module archetype is developed by

“The things we wanted to consider with ourarchetype is to address concerns of larger

teams”

headwire.com

CQBLUEPRINTS MULTIMODULE DESIGNfoo-view subproject: where css/html/js developers (frontend)do their workfoo-taglib foo-services: where java developers (backend) dotheir workfoo-config: where the configuration (runmode configs stored)foo-content: how we get initial content and site structure ontothe developer's box quicklyfoo-all: how we hand off builds to the next environment

USING GIT

WHY GIT?Local safety net"The internet is my backup"It's good to shareEnlightened self-interest

YOU ARE HERE

GIT PROJECT SETUPcd projectnamegit init

GIT IGNOREEdit .gitignore, for example:

.classpath

.project

.vlt/

.settings/target/

GET IT IN GITgit add *git commit -m 'Initial project version'

GET IT IN GITHUB (OPTIONAL)

hub-new-repo is a shortcut for creating a repository ongithub and pushing your local repo into it

See also:

See also:

cd projectgit hub-new-repo

CLI remote github repo creation

github

DEMO

... TIME PASSES ...

COMMIT PROJECTgit add filenamesgit commit -m "meaningful message"git push origin master

(BEST) PRACTICE(S)

YOU ARE HERE

“the three great virtues of a programmer:laziness, impatience, and hubris”

BUILDING

HOW CAN WE BUILD SMARTER?Create local zips and jars that you can upload:

mvn packageproduces:

Content package output: target/yourapp-content-1.0-SNAPSHOT.zipBundle output: target/testapp-bundle-1.0-SNAPSHOT.jar

DEPLOYING

HOW CAN WE BUILD AND DEPLOY SMARTER?Content package: mvn -PautoInstallPackageinstallBundle: mvn -PautoInstallBundle install

cqblueprints: mvn -Pauto-deploy install

DEMO

DEVELOPING

YOU ARE HERE

How do we develop in a world of maven builds and deploys

and git saves?

THE FILEVAULT TOOLYou can use the FileVault tool (vlt) to check in, check out,

update and sync local content with the repository.

Install: extract crx-quickstart/opt/filevault/filevault.[tgz|zip] and add to your pathUsage: vlt --credentials admin:admin co --force http://localhost:4502/crx

See also: How to use the VLT Tool

SAMPLE DEVELOPMENT WORKFLOWUse maven to build and deployInitialise vltCreate components, templates with CRXDE LiteUse vlt to copy back into local filesystemChange locallyUse vlt to copy back into the repositoryAdd to git

DEMO

TESTING

CONTINUOUS INTEGRATION? with ,

as a with and

Jenkins Git plugin GitHub plugin

Selenium server

Cucumber for java Jenkins plugin tests in java

INTEGRATION TESTING FRAMEWORK... see Lydia's talk

PRODUCTION

How do we move to production in a world of maven builds and

deploys and git saves?

YOU ARE HERE

MAVEN PROFILE FOR PRODUCTIONAdd this to pom.xml:

Deploy using this profile:

Or one-time override: mvn -Dcrx.host=another.host,crx.port=4504 -PautoInstallPackage install

See also:

<profile> <id>auto-deploy-prod</id> <properties> <crx.host>production.server.hostname</crx.host> <crx.port>4502</crx.port> </properties></profile>

mvn -PautoInstallPackage,auto-deploy-prod install

Introduction to build profiles

DEPLOYMENT TESTING... see Bertrand's talk

PUTTING IT ALL TOGETHER

0-60 IN 5 PSEUDO LINESmvn archetype:generate

git init; git add *; git commit -m "Initial project"

mvn -PautoInstallPackage install

vlt checkout ; vlt update ; vlt commit

git add; git commit; git push

THANK YOU. QUESTIONS?

CREDITS designed by from The Noun Project

designed by from The Noun Project designed by from The Noun Project

designed by from The Noun Project designed by from The Noun Project designed by from The Noun Project

designed by from The Noun Project designed by from The Noun Project

designed by from The Noun Project designed by from The Noun Project

designed by from The Noun Project

Light Bulb Shane David KennaQuestion Anas RamadanHard Disk Drive Eddie AlshehriTime wayne25ukSync P.J. OnoriSync Rohith M SCloud Upload Adam WhitcroftPuzzle John O'SheaQuestion Henry RyderFactory Adrijan KaravdicCrash Test Dummy Luis Prado