Hello Cloud

Welcome to the Hello Cloud Tutorial. This tutorial guides you on setting up and using Light Development with Magnolia Cloud.

Magnolia Cloud is a Platform as a Service (PaaS) offering that provides:

  • Magnolia CMS optimized for running in the cloud.

  • A complete application development environment running on AWS.

  • Managed services for enterprise-grade security.

Although we have both a custom and standard bundle variant, this tutorial focuses on the standard bundle where your projects are leveraged using Light Development. Your site is hosted in Magnolia Cloud and Magnolia manages the environment as a service.

For more on custom bundles, check out Creating and deploying custom cloud bundles.

Tutorial structure

image

Prerequisites

You need to be able to install Magnolia and in order to do that, you need Java, Node.js, npm, Git, and access to the Magnolia Cockpit which is provided to you when you signed up for Magnolia Cloud.

If you have any issues with logging into the Cockpit, please contact the Magnolia Cloud Helpdesk.

Java

Magnolia needs at least a Java Runtime Environment (JRE) to run. See the Certified stack page to confirm the latest supported Java version. Check your java version by going to your terminal and running java --version. If you do not see a Java version in the output of the command, you need to install Java for your operating system.

For your OS

Java is not pre-installed on Mac OS X 10.7 and later. Download Java from Oracle.

On Windows you need a Java SE Development Kit (JDK). The Java Runtime Environment (JRE) is not enough because the Tomcat application server does not recognize it.

What is the difference?

  • JRE is for users who run Java programs on their computer.

  • JDK is for developers who write Java-based applications.

Download and install JDK. By default JDK is installed in C:\Program Files\Java\. You can choose another location.

Check JAVA_HOME environment variable

  1. Open the command prompt.

  2. Type set and press ENTER.

  3. Find JAVA_HOME in the command output and verify that the path points to your JDK installation directory.

  4. If JAVA_HOME is missing or it points to the wrong directory, see Set JAVA_HOME environment variable below.

Set JAVA_HOME environment variable

  1. Right-click My Computer and select Properties.

  2. Go to the Advanced tab.
    (In Windows 7+, right-click Computer and select Advanced System Settings, then Environment variables.)

  3. If the JAVA_HOME environment variable does not exist in User variables or System variables, create it:

    • User variables apply to the currently signed-in user only. Create JAVA_HOME here if you want it to apply only to the currently logged in user. These variables take precedence over system variables.

    • System variables apply to all users. Create JAVA_HOME here if you want it to apply to all users. You must be an administrator to modify a system environment variable.
      image

  4. Set the value of JAVA_HOME to the path of your JDK installation directory, for example C:\Program Files\Java\jdk1.8.0_131.

  5. Optional step: Add the Magnolia bin directory to the PATH variable, for example C:\Program Files\magnolia\apache-tomcat-x.y\bin. Setting the PATH allows you to issue the Magnolia start and stop commands from anywhere without navigating to the installation directory first. Separate the path from existing paths with a semicolon ( ; ). If you do this, you also need to add CATALINA_HOME to environment variables. Set the value of CATALINA_HOME to the Tomcat installation directory, for example C:\Program Files\magnolia\apache-tomcat-x.y

  6. Click OK.

  7. Go back to Check JAVA_HOME environment variable above and test that the variable is found and has the correct value. You need to open a new command prompt since environment variables are session specific.

Alternatively you can set JAVA_HOME with a batch file, by adding a line like the one below to /apache-tomcat/bin/magnolia_control.bat:

set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_131

The set command creates the JAVA_HOME environment variable and sets its value to the JDK directory. The command is executed when Magnolia starts.

Download Java from Oracle. The installation directory varies from one Linux system to another. For example, on Ubuntu 18.04 the OpenJDK is installed in /usr/lib/jvm/java-11-openjdk-amd64/bin/java by default.

Download Java from Oracle. You can install it in any directory such as /usr/java.

Node and npm

You also need Node.js and npm. Check this by running node --version and npm --version respectively in your terminal. If you do not see a version (as below), you must install Node.js and npm.

$ node --version
v12.18.1

$ npm --version
6.14.5

Install

If you do not have Node installed, go to Node.js to download and install the latest LTS version. For installation instructions of npm, see https://docs.npmjs.com/downloading-and-installing-node-js-and-npm.

Git

Finally, you need Git for version control and pushing local changes to your Magnolia remote repository. Check this by running git --version. If you do not have git, download the latest stable version from Git’s website here.

$ git --version
git version 2.27.0

Get Magnolia

The CLI commands referred to here and further on are Magnolia CLI version 4 commands.

Run npm install @magnolia /cli -g in your terminal where the -g flag makes Magnolia available to you globally on your machine. To check if Magnolia was installed successfully, run mgnl --version and you will see the Magnolia CLI version number (as below).

$ mgnl --version
Magnolia CLI: 4.0.0 (node.js: v12.18.1)

You may have to run the terminal as an administrator if you receive an error such as npm ERR!.

MAC or Linux:

sudo npm install @magnolia /cli -g

Windows:

Right click CMD, and choose Run as Administrator.

Jumpstart Magnolia

Now that Magnolia is installed, let’s jumpstart it.

  1. Navigate to the directory where you want to download Magnolia. For example purposes, we’ll call this directory magnolia.

  2. In your magnolia directory, run mgnl jumpstart -m <version>. If prompted, choose option 3 magnolia-community-demo-webapp. If successful, you see:

    ....
info Magnolia has been successfully setup for light development!
....

  3. To make sure it’s working, run mgnl start from the magnolia directory and after a few seconds, go to the localhost:8080/magnoliaAuthor in your browser and log in as superuser with the password superuser.

    For now, shut down the local server by entering CTRL-C in your terminal where the server is running.

The jumpstart command:

  • Downloads the Magnolia bundle specified into the magnolia directory.

  • Creates a light-modules folder in the directory.

  • Changes the default value of the magnolia.resources.dir configuration property from ${magnolia.home}/modules to /magnolia/light-modules for both the Author and the Public instances of Magnolia.

Prepare Environments in the Cockpit

In this section, we log in to the Cockpit and set up new Integration, UAT, and Live environments. If these environments were already set up during onboarding, you can skip this step.

If you have any issues with logging into the Cockpit, please contact the Magnolia Cloud Helpdesk.

  1. Log in to the Cockpit.

  2. Set up a new Environment for Integration, UAT, and Live. You will need to repeat these steps for each of the three environment types.

    1. On the landing page by your Subscriptions, click Show Package Overview on the right side of the page.

    2. Choose Set up environment for the chosen Environment (Integration, UAT, or Live).

    3. Choose the Magnolia version. You can see runtime information regarding the available bundles.

    4. Click Set up <environment name>. The creation of the environment may take some time.

    5. Click OK.

      Actions in the Magnolia Cockpit are asynchronous. You receive a notification when the Environment is up and running.

  3. Copy or note your Magnolia Cloud .git repository from the Cockpit. This is found under Additional Information on the Package Overview page.

    image

Create a Light Module

OK, so let’s create something - specifically a light module. We are now back on your local machine in the magnolia folder where we installed Magnolia.

If you are curious to know more about light modules, check them out here. But, let’s continue on for now.

  1. In the root magnolia folder, initialize a git repository and add your Magnolia Cloud repo as the remote origin.

    1. run git init

    2. run git remote add origin <yourMagnoliaRemoteRepo>. This is what you just copied from the Cockpit.

    3. run git remote -v and you should see your Magnolia repo as the origin for both fetch and push.

    4. run git pull origin master and now you’re ready to make some local changes. This may take a minute.

  2. Navigate down one level to your light-modules directory.

  3. Run mgnl create-light-module forest. Magnolia CLI has now created the following for you:

    /magnolia/light-modules/forest
    forest/
├── decorations
├── dialogs
│ ├── components
│ └── pages
├── i18n
│ └── forest-messages_en.properties
├── includes
├── templates
│ ├── components
│ └── pages
└── webresources

  4. The forest light module is now ready. Navigate to light-modules/forest. Create a page template in forest using mgnl create-page big-tree.

    A Page template definition

    light-modules/forest/templates/pages/big-tree.yaml

    A Page template script

    light-modules/forest/templates/pages/big-tree.ftl

    A Page dialog definition

    light-modules/forest/dialogs/pages/big-tree.yaml

  5. In light-modules/forest, run mgnl create-component nest to create a component.

    A Component template definition

    light-modules/forest/templates/components/nest.yaml

    A Component template script

    light-modules/forest/templates/components/nest.ftl

    Component dialog definition

    light-modules/forest/dialogs/components/nest.yaml

  6. We need to make the nest component available to the big-tree page template. Still in light-modules/forest, run mgnl add-availability components/nest pages/big-tree@main.

    Added [@cms.area name="main"/] to:

    light-modules/forest/templates/components/big-tree.yaml

    Added the component nest with an id:forest:components/nest to:

    light-modules/forest/templates/components/big-tree.ftl

    In light-modules/forest/templates/pages/big-tree.ftl, make sure the main area is inside the <div class="container"> as so:

       <div class="container">
        <h1>big-tree works!</h1>
        [@cms.area name="main"/]
   </div>

  7. Make the MTK module (Magnolia Templating Kit module) HTML available to the big-tree page.

    1. Go to light-modules/forest.

    2. run mgnl add-availability mtk:components/html pages/big-tree@main. Your templates/pages/big-tree.yaml file should now look like:

      big-tree.yaml
      title: big-tree
templateScript: /forest/templates/pages/big-tree.ftl
renderType: freemarker
dialog: forest:pages/big-tree
visible: true

areas:
  main:
    availableComponents:
      nest:
        id: forest:components/nest
      html:
        id: mtk:components/html

  8. Let’s add some simple functionality. Navigate to and open /magnolia/light-modules/forest/templates/pages/big-tree.ftl.

    1. Uncomment the resfn.css and refsn.js snippets.

    2. Save the File.

      big-tree.ftl
      ${resfn.css(["/forest/.*css"])!}
</head>
${resfn.js(["/forest/.*js"])!}
</body>

  9. Navigate to and open /magnolia/light-modules/forest/templates/components/nest.ftl.

    1. Add a simple button and div below the content.title section at the top of the file.

    2. Save the File.

      nest.ftl
      // <div class="nest">
//   [#if content.title?has_content]
//     <h2>${content.title!}</h2>
//   [/#if]

// <!-- add the button and div below -->
//   <button onclick="tweet()">Click me</button>

//   <div id="birdie"><h2>I'm a wee birdie</h2></div>

  10. Create a new folder called css at forest/webresources.

    1. Navigate to the new forest/webresources/css folder.

    2. Create a file called styles.css.

    3. Copy and paste the code below into styles.css.

    4. Save the File.

      styles.css
      div.nest {
    background-color: #8c720b;
    padding: 100px;
    border-radius: 15px 50px;
    color: white;
}

button {
    padding: 5px;
    background-color: rgb(129, 126, 125);
    color: whitesmoke;
    border-radius: 8px;
    box-shadow: -1px 0px 11px -3px rgba(0, 0, 0, 0.671);
    cursor: pointer;
}

#birdie {
    display: none;
}

  11. Finally, create a new folder called js at forest/webresources.

    1. Navigate to the new forest/webresources/js folder.

    2. Create a file called tweet.js.

    3. Copy and paste the code below into the tweet.js file.

    4. Save the File.

      tweet.js
      function tweet() {
    var x = document.getElementById("birdie");
    if (x.style.display === "none") {
      x.style.display = "block";
    } else {
      x.style.display = "none";
    }
  }

Local test

  1. In the root magnolia folder, run mgnl start and then use your favorite web browser to open the URL http://localhost:8080/magnoliaAuthor/.

  2. Create a new page with using your big-tree page template and choose the nest component.

    1. Navigate to the Pages App via the (mgnl-app-launcher: []) icon on the top bar.

    2. Click Add Page.

    3. Name the page home and click on big-tree template.

      image

    4. Double-click the newly-created home page.

    5. Add the nest component to the page.

      image

  3. Make sure your forest module is in your Resource Files app.

    Use the search bar at the top and type Resource Files.

Push your changes

If you are happy that all is well locally, let’s push those changes to your Magnolia Cloud repository.

  1. In the the magnolia folder (the parent directory of your light-modules) stop the local server with CTRL-C.

  2. Run git add . && git commit -m "flyAway" && git push origin master.

Install git changes in the Cockpit

Go back to your Cockpit and log in using your provided credentials.

  1. Navigate to My Subscription Packages > Subscription > Manage updates.

  2. Choose Deploy a development snapshot. Choose Branch > Master in the on-screen wizard.

    image

  3. On the Manage updates page, Choose Create a new release from a development snapshot. Follow the on-screen wizard. image

  4. On the Manage updates Page, Choose Promote a release. Follow the on-screen wizard for the UAT and repeat for the Live Environment as well. +image

Create a Page

  1. Navigate to your Live Environment under Environments.

  2. Go into the Author space by clicking on the author URL under the Artifact ID.

  3. Edit the Home page by right clicking it and choosing Change Template and change the template to use your big-tree page template.

    image

  4. Publish the page.

    1. Click Preview Page.

    2. Once in Preview, click Publish. This assigns a publishing task to your publishing group.

    3. Navigate to Tasks, found in the top navigation bar.

    4. Select the task and click Assign to Me.

    5. Navigate to the Assigned Tab in Tasks.

    6. Click on the task assigned to you.

    7. Click Preview Task.

    8. Once in Preview, click Approve and Publish.

You can now go to your public Live environment URL (or associated domain name) and see the updated page.

Take a bow, my friend. You’re done. You have successfully:

  • Logged in to your Cockpit.

  • Set up Integration, UAT, and Live environments.

  • Made changes locally via Magnolia CLI, pushed them to Magnolia Cloud, and implemented those changes.

Have a look at the rest of the Magnolia Cloud or dig further into light module development by learning about front-end development in Magnolia.
Feedback

Legacy Cloud

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia Cloud docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules