Page tree
Skip to end of metadata
Go to start of metadata

If you have decided to use the custom cloud bundle variant, your site is hosted in Magnolia Cloud and you, or your cloud partner, must create and deploy the custom bundle.

To successfully deploy custom bundles to Magnolia Cloud, certain best practices must be followed when creating your project and when deploying it the first time or continuously thereafter. 

Creating your custom bundle

Magnolia provides a cloud-specific option in the Magnolia Maven Archetype to bootstrap a new project.

You receive your subscription-code and access keys during the Magnolia Cloud onboarding process.

The magnolia-cloud-project-archetype is supported with version 1.3+ of the Magnolia Maven Archetype.

Usage

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/ 

...
6: https://nexus.magnolia-cms.com/content/repositories/magnolia.public.snapshots -> info.magnolia.maven.archetypes:magnolia-cloud-project-archetype (Automates the creation of a Magnolia Cloud project: parent pom and webapp)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 6

Define value for property 'groupId': : com.mycompany.project
Define value for property 'artifactId': : web-project-xyz
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  com.mycompany.project: :
Define value for property 'cloud-subscription-code': : mycompany-project
Define value for property 'magnolia-bundle-version': : 6.2.1
Define value for property 'project-name':  web-project-xyz: :
Confirm properties configuration:
groupId: com.mycompany.project
artifactId: web-project-xyz
version: 1.0-SNAPSHOT
package: com.mycompany.project
cloud-subscription-code: mycompany-project
magnolia-bundle-version: 6.2.1
project-name: web-project-xyz
 Y: : Y

...

[INFO] project created from Archetype in dir: /Users/user/dev/web-project-xyz
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  02:18 min
[INFO] Finished at: 2020-04-23T13:12:46+02:00
[INFO] ------------------------------------------------------------------------

Further instructions and best practice information are provided in your project's README.md.

The Magnolia Maven Archetype generates a best-practice project skeleton. For example:

my-mgnl-cloud-webapp/
├── pom.xml
└── src
    └── main
        └── webapp
            └── WEB-INF
                └── config
                    └── dev
                    │   └── README.md
                    │   └── magnolia.properties
                    └── shared
                        └── README.md
                        └── magnolia.properties

Note that upon creation:

  • Two default profiles are generated: dev and shared. These profiles have their own magnolia.properties files. 
  • During packaging, the dev profile is excluded. The shared profile is included and deployed to Magnolia Cloud.
  • You can add local developer credentials to the dev profile to be used instead of the typical Magnolia superuser/superuser, which is disabled in the cloud.
  • In the shared profile, you can create specific .properties files for each cloud environment. This can be used, for example, to test the integration of a third-party tool in the UAT environment without affecting your Live environment. 

If you created a custom bundle before Magnolia 6.2.1 with .properties file changes, please check your customizations carefully and adhere to the structure shown above.

Continuous integration and deployment of custom bundles

You must use the Magnolia Cloud Maven Plugin 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.

Make sure you use the latest version of the Magnolia Cloud Maven Plugin when deploying a new bundle to Magnolia Cloud: v1.0-RC6.

More information can be found in the readme here: https://git.magnolia-cms.com/projects/OD/repos/magnolia-cloud-maven-plugin/browse/README.md

Validation of the custom bundle

The plugin performs validation checks against the built artifact (webapp) to ensure compatibility with the Magnolia Cloud infrastructure:

  • Basic checks for required configuration in the web.xml and magnolia.properties files.
  • Inspection of required and blacklisted modules/jars.

Deployment of the WAR file

The plugin uploads the built artifact to the entry point for Magnolia Cloud's deployment pipelines. It also collects meta-information about the artifact for debugging purposes.

Magnolia Cloud Simulator

We recommend you test your custom bundle in a simulated cloud environment before deploying it.

To do so, we offer a docker-compose based setup: Magnolia Cloud Simulator.


4 Comments

  1. Hello Julie Legendre , let's consider putting below information here since 6.2 (source Magnolia Cloud updates 2020) – PS: I'm temporarily put it inside so that customer can reference due to HELPDESK-850

    Magnolia Cloud magnolia.properties file conventions

    Applies to custom cloud bundle implementations only.

    From Magnolia 6.2.1, Magnolia provides a cloud-specific option in the Magnolia Maven Archetype to facilitate the creation of your cloud bundles.

    The Magnolia Maven Archetype generates a best-practice project skeleton. The Magnolia Cloud Maven Plugin validates and uploads your custom cloud bundle.

    my-mgnl-cloud-webapp/
    ├── pom.xml
    └── src
        └── main
            └── webapp
                └── WEB-INF
                    └── config
                        └── dev
                        │   └── README.md
                        │   └── magnolia.properties
                        └── shared
                            └── README.md
                            └── magnolia.properties

    Note:

    • Two default profiles are generated: dev and shared. These profiles have their own magnolia.properties files. 
    • During packaging, the dev profile is excluded. The shared profile is included and deployed to Magnolia Cloud.
    • You can add local developer credentials to the dev profile to be used instead of the typical Magnolia superuser/superuser, which is disabled in the cloud.
    • In the shared profile, you can create specific .properties files for each cloud environment. This can be used, for example, to test the integration of a third-party tool in the UAT environment without affecting your Live environment. 

    Make sure you use the latest version of the Magnolia Cloud Maven Plugin when deploying a new bundle to Magnolia Cloud: v1.0-RC6.

    If you previously created a custom bundle with .properties file changes, please check your customizations carefully and adhere to the structure shown above.

    More information can be found in the readme here: https://git.magnolia-cms.com/projects/OD/repos/magnolia-cloud-maven-plugin/browse/README.md

    Also see Creating and deploying custom cloud bundles.

    1. Hi Viet Nguyen, all of that information was already on the page. Check the Usage section (for example the warning about customized properties files). I'll revert your changes. 

      1. Thanks  Julie Legendre, can we put a link from this page to that "usage section" so that Cloud customer can easily find out and use the product follow "developing for Magnolia "on the cloud" (smile)

        1. You're welcome Viet Nguyen. Thanks for the suggestion. There is also already a link to this page from the Developing for Magnolia in the cloud page. Imho I think the whole page is relevant; not just the usage section.