-- fixed site:deploy

*************

Prerequisites

*************

- The only prerequisite to follow reading this document is to have Apache Maven 3.0.3+ (or higher) installed

on your machine; there is no preferred IDE nor web container and database requirements needed.

- It is strongly advised to use the Apache Maven official binary distributions downloaded from maven.apache.org; avoid

OS-specific distributions as much as possible.

- add MAVEN_OPTS="-Xms256m -Xmx1G -XX:PermSize=300m" to your environment if your plan to launch tests / run embedded in Jetty

*****

Usage 

*****

This multi-module project manages an All-in-One Alfresco project and it's composed by the following modules:

- amp --> An Repository Tier AMP project, demonstrating sample project structure and demo component loading. Can be configured to work for Share 

- alfresco --> An alfresco.war Repository Extension, overlaying the Alfresco WAR with custom resources / classes and depending on the 'amp' project

- share --> A share.war extension, overlaying the Share WAR with custom resoruces / classes

- solr --> A solr.zip overlay / customization to configure solr cores properties

The project provides support for typical development lifecycle use cases like:

- packaging

- testing

- run embedded

- integration testing

- release and distribution

of your Alfresco (and platform components) related artifacts. The AMPs produced with this project are fully compatible with Alfresco MMT, 

in fact the Alfresco Maven plugin - used to manage AMPs in this SDK - embeds the official Alfresco MMT to install depended AMPs. 

Project layout:

--------------

parent-project

            |-> amp

            |-> alfresco

            |-> share

            |-> solr

            |-> wcmqs (Alfresco Web Quick Start)

            |-> runner (a Jetty embedded runner / integration test runner)

Useful commands

---------------

Running from parent project: 

- mvn package --> Runs unit tests (if present) and packages all modules in their respective target/ 

- mvn install --> Runs unit tests  (if present) , packages and installs AMP in local Maven repository

- mvn install -Dmaven.test.skip=true --> Packages and installs AMP in local Maven repository, skipping tests

- mvn integration-test -Prun --> Runs unit tests and packages all modules and the runner project runs Alfresco, Share and Solr in Jetty + H2

- mvn clean -Ppurge --> Removes DB, alf_data and log files

Running from runner:

- 'mvn jetty:run -Prun' or 'mvn integration-test -Prun' to quickly run already packaged webapps

Properties management 

---------------------

Properties are configurable at 2 levels:

- POM properties (in the parent POM or at single module level)

- direclty in each modules *.properties files, particularly

   - src/main/properties/<env>/alfresco-global.properties (environment dependent properties for Alfresco WARs)

Useful properties that can be fully controlled directly in the POM are:

alfresco.data.location (default = alf_data_dev) 

alfresco.db.name (default = alf_dev)

app.log.dir (default = target/)

app.log.root.level (default = INFO)

***************************

Maven Alfresco SDK Overview

***************************

The Maven Alfresco SDK is an effort that have been developing in the last 5 years - mostly driven by community efforts on

Google Code (http://code.google.com/p/maven-alfresco-archetypes) - which delivers archetypes for building Alfresco

integration project with Maven; builds are based on Alfresco Community and Enterprise artifacts released on the

Alfresco Artifacts Repository at https://artifacts.alfresco.com

The Maven Alfresco SDK is full rewriting of the Maven Alfresco Lifecyle (latest version 3.9.1) and it's composed of 3 efforts:

a) POM files: 

    - alfresco-sdk-parent: provides lifecycle features and behaviors for typical Alfresco development projects

    - alfresco-platform-distribution: describes and provides dependencyManagement for artifacts of each Alfresco release

b) alfresco-maven-plugin:

    - defines the AMP packaging type and lifecycle in Maven

    - emdeds Alfresco MMT to provide safe installation of single / multiple AMP -> WAR 

    - will potentially grow including more use cases around Alfresco / Maven

c) The definition of (initially 2) archetypes that show some simple project's configuration using

the parent POMs

    - AMP archetype (this archetype)

    - All-in-One multi-module archetype including

        - Alfresco Repository AMP

        - Alfresco Repository extension project (WAR, also depending on the AMP)

        - Share customization project (WAR)

        - Solr customization project (WAR)

        - Jetty embedded runner for the full platform (mvn clean install -Prun)

****************************************

Why using this SDK might be a good idea?

****************************************

The main reported advantages of using the Maven Alfresco SDK are:

- IDE-independent SDK, all build-related features are provided by Apache Maven, which is the only

prerequisite to use this SDK 

- No IDE manual configuration, all modern IDEs offer advanced Maven integrations, so 

feel free to use Eclipse, IntelliJ, or any other IDE to write your code and leverage Maven

- Process ready: scales from quick start rapid application development, to be seamlessly 

integrated in enterprise devleopment processes like Continuous Integration and Release

- Language independent, you don't like Maven? You can still use Ant, Ivy, Buildr, Gradle, Leiningen or any other build

system that is compatible with Maven artifact resolution mechanism; just configure artifacts.alfresco.com as (one of) your

Maven repositories and you're ready to go

- Javadoc and Sources support, provided by artifacts.alfresco.com related Maven artifacts; you don't need to manually

configure your IDE to attach (manually downloaded) sources to your (manually downloaded) binaries.

- Clean and readable, the build logic related with OOTB Alfresco features is wrapped in 50 lines of pom.xml

- Advanced build functionality, inherited by your parent POMs you can use embedded databases and j2ee

containers with (almost) no configuration at all, among other features exposed below.

- One mvn command to generate, one mvn command to run embedded, this is all you need to do to have a local Alfresco running

on an empty laptop

- Supports community and enterprise flawlessly, allowing to switch one to another very easily

 No newline at end of file

  ------

  Alfresco Maven AMP Archetype Advanced Usage

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------

All-in-One Archetype properties

    In each of the modules of the archetype (as in the whole Maven Alfresco SDK\x99) properties are configurable at many levels:

    * as POM properties

    * direclty in *.properties, particularly

        * For Alfresco WAR projects

            * <<<src/main/properties/<env>/alfresco-global.properties>>> (environment dependent <<<alfresco-global.properties>>> packaged in the WAR )

        * For Alfresco AMP projects

            * <<<src/test/properties/<env>/alfresco-global.properties>>> (environment dependent <<<alfresco-global.properties>>> for test WAR run)

    Build Environment (e.g. local, test, staging, prod) can be easily switched by setting the <<<<env>>>> property in yoru POM or 

    adding <<<-Denv=yourEnv>>> on the command line.

* Common properties

    Archetype behavior can mostly be controlled directly in the POM, via common properties provided by the parent POM.

    See {{{../../poms/alfresco-sdk-parent/sdk-properties.html} SDK properties reference}} for details.

Parent POM and behavior customization 

    To customize the behavior of your project, check out full set of the properties and plugin configurations defined in the 

    {{{./poms/alfresco-sdk-parent/index.html}single entry point parent POM}}. 

    One quick way to do that is to use the <<<maven-help-plugin:effective-pom>>> to analyze your POM at runtime. 

 No newline at end of file

  ------

  Building AMPs (Alfresco Module Packages) with Maven

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------

Alfresco All-in-One Archetype - Part of the Maven Alfresco SDK\x99

  The Alfresco All-in-One Archetype is a multi-module project,

  leveraging Maven Alfresco SDK\x99 powerful capabilities to customize and run the full Alfresco platform embedded and all it's components.

  The archetype does not require additional download and provides a perfect starting point for full-blown Alfresco projects.

* Features

  Amongst other features, this archetype provides support for:

  * <<<amp>>> packaging support for your projects

  * AMP Dependency management and overlay in an Alfresco Repository or Share WAR

  * Embedded run in Jetty and embedded H2 database of the full Alfresco suite, including Repository, Share, Solr and Web Quick Start

  * Support for unit and integration testings

How to create a project:

  You can create the latest release archetype with the following command:

+---+

mvn archetype:generate -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml

+---+

  You should then:

  [[1]] Select the <<<alfresco-allinone-archetype>>> option

  [[2]] Specify the <<<groupId>>> and <<<artifactId>>> for the project you want to create

  [[3]] (<Optionally>) Select Alfresco Version / Edition (current default is: Alfresco Community 4.2.b)

 You can find new Alfresco All-in-One project ready to go in the <<<artifactId>>> folder.

Usage

  Instructions on how to use the Alfresco AMP archetype can be found on the {{{./usage.html}usage page}}, while 

  for more advanced use cases refer to the {{{./advanced-usage.html}usage page}}

  ------

  Alfresco Maven AMP Archetype Usage

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------

Prerequisites

   See {{{/prerequisites.html} SDK Pre-Requisites}} to successfully run this archetype.

Project layout

    The archetype generated multi-module project should look like:

+---+

    pom.xml

    |-> amp

    |-> alfresco

    |-> share

    |-> solr

    |-> wcmqs (Alfresco Web Quick Start)

    |-> runner (a Jetty embedded runner / integration test runner)

+---+

* Modules 

    The All-in-One Alfresco project is composed by the following modules:

    * <<<amp>>>: An Repository Tier AMP project, demonstrating sample project structure and demo component loading. It can be configured to work for Share

    * <<<alfresco>>>: An <<<alfresco.war>>> Repository Extension, overlaying the Alfresco WAR with custom resources / classes 

    and depending on the <<<amp>>> project

    * <<<share>>>: A <<<share.war>>> extension, overlaying the Share WAR with custom resoruces / classes

    * <<<solr>>>: An Alfresco <<<alfresco-*-*-solr.zip>>> overlay / customization to configure {{{http://solr.apache.org}Apache Solr}} cores properties

    * <<<wcmqs>>>: An Alfresco Web Quick Start overlay / customization. WQS Repository and Share AMPs are also installed on Alfresco and Share.

    * <<<runner>>>: A Jetty + H2 runner, capable of running all the aforementioned projects in embedded mode for demo / integration-testing purposes

Usage 

    The project provides support for typical development lifecycle use cases like

        * AMP/WAR packaging

        * AMP Unit testing

        * run embedded in Jetty + H2 database. 

          (<<NOTE>>: this is not a {{{http://www.alfresco.com/services/subscription/supported-platforms/} supported stack}} so use <<only for development purposes>>)

        * Integration testing

        * AMP to WAR installation and overlay (embedding {{{http://wiki.alfresco.com/wiki/Module_Management_Tool}Alfresco Module Managment Tool}})

        * release and distribution

    for all the components of the Alfresco landscape. 

    <<NOTE>>: AMPs produced with this project are fully compatible with Alfresco MMT,in fact the Alfresco Maven plugin - used to manage AMPs in this SDK - embeds the official Alfresco MMT to install depended AMPs. 

Commands

* Commands from the root aggregator project

    Common Alfresco project lifecycle commands you want to run from the aggregator :

    * <<<mvn package>>>: Runs unit tests and packages all customized modules in their respective \${project.build.directory}/\${project.build.finalName}.amp

    * <<<mvn install>>>: Like <<<mvn package>>> but also installs all modules in local Maven repository to be depended upon

    * <<<mvn install -Dmaven.test.skip=true>>>: Like <<<mvn install>>> but skips unit tests

    * <<<mvn install -Prun>>>: Like <<<mvn install>>> but also trigger the <<<runner>>> project to run Alfresco, Share, Solr and Web Quick Start in Jetty  (with H2 embedded database)

    * <<<mvn clean -Ppurge>>>: Removes DB, alf_data and log files

* Commands from from the <<<runner>>> project

    * <<<mvn jetty:run -Prun'>>> or <<<'mvn integration-test -Prun'>>> to quickly run already packaged webapps

Advanced usage

    See the {{{./advanced-usage.html}advanced usage page}}

<project>

  <body>

        <menu ref="parent" inherit="bottom"/>

        <menu name="Alfresco AMP Archetype">

            <item name="Introduction" href="index.html"/>

            <item name="Usage" href="usage.html"/>

            <item name="Advanced Usage" href="advanced-usage.html"/>

        </menu>

        <menu name="Maven Alfresco SDK">

            <item name="Home" href="/index.html" />

            <item name="Maven Alfresco SDK Prerequisites" href="/prerequisites.html" />

            <item name="Why using SDK?" href="/why.html" />

            <item name="Alfresco SDK Parent POM" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest/poms/alfresco-sdk-parent/index.html" />

            <item name="Alfresco Platform Distribution POM" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-platform-distribution/latest/index.html" />

            <item name="Maven AMP Plugin" href="http://maven.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-lifecycle/latest/plugins/maven-amp-plugin/index.html" />

        </menu>

        <menu name="Maven Alfresco Community">

            <item name="Alfresco Maven Wiki Docs" href="http://wiki.alfresco.com/wiki/Maven_Alfresco_SDK" />

            <item name="Alfresco with Maven for Dummies" href="https://wiki.alfresco.com/wiki/Maven_For_Dummies" />

            <item name="Developer Access (Google Code)" href="http://code.google.com/p/maven-alfresco-archetypes/" />

            <item name="Gabriele Columbro's blog" href="http://www.mindthegab.com/" />

            <item name="Maurizio Pillitu's blog" href="http://www.session.it/" />

            <item name="Carlo Sciolla's blog" href="http://skuro.tk/" />

            <item name="Enterprise adoption" href="http://www.slideshare.net/guest67a9ba/maven-application-lifecycle-management-for-alfresco" />

        </menu>

        <!--<menu ref="reports"/>-->

  </body>

</project>

 No newline at end of file