Magnolia Cloud Maven plugin

The Magnolia Cloud Maven Plugin is used for the continuous integration and deployment (CI/CD) of custom bundles to Magnolia Cloud. The plugin validates and uploads your custom cloud bundle and deploys it to Magnolia’s pipelines. Currently, the plugin is tested against Java 8 and 13.

Make sure you use the latest version of the Magnolia Cloud Maven Plugin when deploying a new bundle to Magnolia Cloud: 1.0-RC7.
Currently, Magnolia Cloud only allows for incremental upgrades of the environment if the maven version is increased. The only alternative option at this time is to tear down the environment and set it up again.
What does the plugin do?
The plugin validates the custom bundle which
  • Checks for the required configuration in the web.xml and magnolia.properties files.

  • Inspects required and blacklisted modules and jars.

The plugin deploys the WAR file which
  • Uploads the built artifact to the S3 bucket that serves as the primary entry point to Magnolia Cloud’s deployment pipelines.

  • Collects meta-data about the artifact for debugging.

Setting up the CI/CD pipeline for custom cloud bundles

To set up a CI/CD pipeline for your custom cloud bundle development, you’ll need to successfully achieve the following maven goals:

Maven goal Description

magnolia-cloud:validate

Validates the project for compatibility with Magnolia Cloud deployment.

magnolia-cloud:upload-to-s3

Uploads the built artifact (the webapp WAR file) to the provided S3 bucket.

Both of these goals need to resolve the whole dependency tree for your webapp/reactor for inspection purposes. The execution needs to bind to a phase that resolves this. See more on the build lifecycle.

Prerequisites

  • You have a cloud subscription ID.

  • You must have access to your S3 bucket.

  • You must have your AWS access and secret to hand (these are provided in onboarding)

  • You must have at least basic maven knowledge.

Instructions

  1. First, get the Magnolic Cloud Maven plugin.

  2. Add the Magnolia Cloud Maven plugin to the pluginManagement section of your parent POM.

    <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <groupId>info.magnolia.cloud</groupId>
              <artifactId>magnolia-cloud-maven-plugin</artifactId>
              <version>${magnolia.cloud.version}</version>
              <configuration>
                <region>eu-central-1</region>
                <bucketName>magnolia-mgnl-prod-eu-central-1-custom-bundle</bucketName>
                <subscriptionCode>your-subscription-code</subscriptionCode> <!--your subscription code which is provided in onboarding -->
                <accessKey>ABCD</accessKey> <!-- Or passed as parameters, or from AWS environment -->
                <secretKey>DCBA</secretKey> <!-- Or passed as parameters, or from AWS environment -->
              </configuration>
            </plugin>
        </pluginManagement>
    </build>
  3. Validate and deploy your project:

    • Single module

    • Multi-module

    1. Validate your project:

      mvn -U compile magnolia-cloud:validate
    2. Deploy your project to S3:

      mvn -U package magnolia-cloud:upload-to-s3

    With a multi-module reactor, you have to restrict plugin execution to the webapp module meant for your Magnolia Cloud deployment.

    1. Add the following to your webapp’s pom.xml file:

      <build>
          <plugins>
            <plugin>
              <groupId>info.magnolia.cloud</groupId>
              <artifactId>magnolia-cloud-maven-plugin</artifactId>
            </plugin>
          </plugins>
      </build>
      This executes both plugin goals during their default phases meaning magnolia-cloud:validate is executed during the prepare-package phase and magnolia-cloud:upload-to-s3 during the deploy phase.
    2. Define profiles to reduce the number of deployments to Magnolia Cloud.

      <profiles>
         <!-- See Jenkinsfile for usage of profiles. Needs AWS access token and secret. -->
        <profile>
          <id>magnolia-cloud-verify</id> (1)
          <build>
            <plugins>
              <plugin>
                <groupId>info.magnolia.cloud</groupId>
                <artifactId>magnolia-cloud-maven-plugin</artifactId>
                <executions>
                  <execution>
                    <id>check-for-required-dependencies</id>
                    <goals>
                      <goal>validate</goal> (1)
                    </goals>
                  </execution>
                </executions>
              </plugin>
              <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                  <!-- Remove development related properties for Magnolia Cloud deployment -->
                  <packagingExcludes>
                    WEB-INF/config/dev
                  </packagingExcludes>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
        <profile>
          <id>magnolia-cloud-deploy</id> (2)
          <build>
            <plugins>
              <plugin>
                <groupId>info.magnolia.cloud</groupId>
                <artifactId>magnolia-cloud-maven-plugin</artifactId>
                <executions>
                  <execution>
                    <id>upload-artifact-to-s3</id>
                    <phase>verify</phase>
                    <goals>
                      <goal>upload-to-s3</goal> (2)
                    </goals>
                  </execution>
                </executions>
              </plugin>
              <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                  <packagingExcludes>WEB-INF/config/dev/</packagingExcludes>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
      1 Defines the profile for the validate goal.
      2 Defines the profile for the upload-to-s3 goal.
    3. Validate your custom bundle:

      mvn -U package -Pmagnolia-cloud-verify
    4. Deploy your project:

      mvn verify -Pmagnolia-cloud-deploy

Example CI/CD pipeline for cloud deployment

Ideally, you would set up a Jenkinsfile in your project. See the example below which uses the profiles created when setting up the pipeline.

Your profiles and CI/CD setup may vary.
Example Jenkinsfile
pipeline {

    agent {
        label 'java'
    }

    options {
        withAWS(region:'eu-central-1',credentials:'stored-in-jenkins-secrets')
    }

    stages {
        stage('Build the artifact') { (1)
            steps {
                sh 'mvn clean verify -U -Pmagnolia-cloud-verify'
            }
        }
        stage('Deploy to Magnolia Cloud') { (2)
            when {
                branch 'release'
            }
            steps {
                sh 'mvn deploy -Pmagnolia-cloud-deploy'
            }
        }
    }
}
1 Specify the validation/verification stage.
2 Specify the deployment stage.
Feedback