Prerequisites
- Tools
- General Azure and Maven setup
Prepare the Magnolia demo
- Configure the Magnolia webapp
- Integrate Azure into your build configuration
Test your deployment
Deploy the new build
Troubleshooting
Clean up Azure resources
Simplifying Magnolia deployments with Azure App Service
Additional Resources

Deploying Magnolia using Azure App Service

Azure App Service provides a web hosting service that enables quick deployments of Magnolia projects. It integrates well with Maven and can be used directly from your IDE. Once configured, it just takes a few commands to deploy your Magnolia application to a hosted service, where the application can be accessed from the public internet. This makes it easy for users outside your organization to test new features in your Magnolia project.

This blog explains how to enable quick deployments of a single Magnolia instance to a hosted Azure environment using standard development tools. Full documentation for production-ready configurations and deployments is outside the scope of this blog.

Prerequisites

Tools

Besides the standards required for Magnolia development like Maven and Java, you will need to install the following tools for Azure:

You can either work on the command line or install a toolkit for your development environment:

In this example, we will use the command line and Maven tools, but feel free to use one of the above alternatives.

General Azure and Maven setup

We assume that you already have an Azure account and were able to create an initial configuration on your development machine to use the Azure command-line tools. You should also be aware of how Maven is used to create Java-based web applications, such as a Magnolia instance. We provide additional resources at the end of this article for more information.

Please be aware that you have to use unique parameters for your Magnolia instance, for example for its name, because Azure does not allow you to use the same parameters for multiple Azure clients at the same time, like “MagnoliaAzureDemo”.

Create a service principal

Service principals are dedicated Azure accounts for automated tools providing an account without administrator privileges. Using a service principal is more secure than using a regular user account.

To enable Maven to deploy the Magnolia project on Azure, create a service principal with password-based authentication:


# az ad sp create-for-rbac --name MagnoliaAzureDemo

It’s important to keep the output of the result you retrieve from this command, especially the password which cannot be retrieved later.


{
  "appId": "ed4b6deb-e623-4d75-949b-1674dbfa7e82",
  "displayName": "MagnoliaAzureDemo",
  "name": "http://MagnoliaAzureDemo",
  "password": "pBpBiZYy.P7PB0GmpN2T1vq-Z4huA~Tuct",
  "tenant": "f7b40566-d9fd-49e6-a4ad-2c4fbc01129d"
}

In production, you should make use of Azure’s key vault or use Maven to encrypt the key value.

We recommended storing any configuration in Maven settings. Therefore, adjust your existing settings.xml file by adding a server configuration:

settings.xml


...
<server>
   <id>azure-auth</id>
   <configuration>
       <client>ed4b6deb-e623-4d75-949b-1674dbfa7e82</client>
       <tenant>f7b40566-d9fd-49e6-a4ad-2c4fbc01129d</tenant>
       <key>pBpBiZYy.P7PB0GmpN2T1vq-Z4huA~Tuct</key>
       <environment>AZURE</environment>
   </configuration>
</server>
...

You can specify the Azure region using one of the following values for the environment parameter: AZURE, AZURE_CHINA, AZURE_GERMANY, or AZURE_US_GOVERNMENT.

Prepare the Magnolia demo

In this article, we will use a simple Magnolia public instance based on the “magnolia-community-demo-webapp”. Alternatively, you can skip this section and leverage one of your existing projects.

If you are new to Magnolia, we recommend you read how to create a custom webapp with Maven first. You can also have a look at an example project.

Configure the Magnolia webapp

The Magnolia instance context should be available as a subdomain matching the name of your deployment on the azurewebsites.net domain, like:

https://<name>.azurewebsites.net/

For the root configuration, create a folder named “ROOT” under <project>-webapp/src/main/webapp/WEB-INF/config and add a magnolia.properties file.


magnolia-blog-azure-demo-webapp/
├── overlays/
└── src/
    └── main/
        └── webapp/
            ├── docroot/
            └── WEB-INF
                ├── bootstrap/
                └── config
                    ├── default/
                    └── ROOT
                        └── magnolia.properties

Add the following content to magnolia.properties to bootstrap a public Magnolia instance at the ROOT level.


magnolia.bootstrap.authorInstance=false
# the directories in which the bootstrap files are searched
magnolia.bootstrap.dir=WEB-INF/bootstrap/public WEB-INF/bootstrap/common

Integrate Azure into your build configuration

Add a profile to the pom.xml in the <project-name>-webapp:

pom.xml


<profiles>
    ...
    <profile>
      <id>ROOT</id>
      <build>
        <finalName>ROOT</finalName>
      </build>
    </profile>
  </profiles>

In the same file, add the Azure Maven build plug-in:


<build>
  <plugins>
      ...
      <plugin>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>azure-webapp-maven-plugin</artifactId>
        <version>1.12.0</version>
        <configuration>
          <schemaVersion>V2</schemaVersion>
          <subscriptionId>94dbb43c-40b5-4de6-ba4f-7b00075XXX456</subscriptionId>
          <resourceGroup>MagnoliaAzureDemoResourceGroup</resourceGroup>
          <appName>mgnlazuredemo</appName>
          <pricingTier>B3</pricingTier>
          <region>westeurope</region>
          <runtime>
            <os>Linux</os>
            <webContainer>Tomcat 9.0</webContainer>
            <javaVersion>Java 11</javaVersion>
          </runtime>
          <deployment>
            <resources>
              <resource>
                <directory>${project.basedir}/target</directory>
                <includes>
                  <include>*.war</include>
                </includes>
              </resource>
            </resources>
          </deployment>
        </configuration>
      </plugin>
    </plugins>
  </build>

In a production deployment, you would use properties and variable names in your Maven configuration. Feel free to adjust the pricing tier, region, and other values according to your needs. See Maven Plugin for Azure App Service for additional information.

Deploying your CMS to Azure Cloud

Our free blueprints guide you through deploying your CMS to Azure Cloud, using Magnolia CMS as an example

Download now

Test your deployment

Open a terminal and navigate to <project-name>-webapp of your Magnolia project.

Create a Resource Group

If you have not already done so, create a Resource Group for the demo using your preferred name and location parameters:


# az group create --name MagnoliaAzureDemoResourceGroup --location westeurope

This should produce a response in JSON similar to the below:


{
  "id": "/subscriptions/94dbb43c-41b6-5de5-ba9d-7b11175de438/resourceGroups/MagnoliaAzureDemoResourceGroup",
  "location": "westeurope",
  "managedBy": null,
  "name": "MagnoliaAzureDemoResourceGroup",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Build and deploy Magnolia

Build Magnolia with the ROOT profile. The final artifact will be called ROOT.war and the magnolia.properties file in the ROOT folder will be used at startup.


# mvn clean package -P ROOT

Deploy the build to Azure:


# mvn azure-webapp:deploy

The last command can take some time while Azure App Service takes care of your Magnolia instance:


[INFO] Trying to deploy artifact to mgnlazuredemo...
[INFO] Deploying the war file ROOT.war...
[INFO] Successfully deployed the artifact to https://mgnlazuredemo.azurewebsites.net
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Once you see the “BUILD SUCCESS” message you can access your Magnolia instance via its public URL https://<name>.azurewebsites.net/ and start the installation:

When the installation is complete, start Magnolia:

You have successfully deployed a Magnolia instance and should now see your public website:

Now try to restart the instance from the terminal and see what happens:


# az webapp restart -n mgnlazuredemo -g MagnoliaAzureDemoResourceGroup

Once the service is ready, you’ll notice that you see “Start installation” again, because the Azure container has not stored the default location of its file-based H2 database.

Stop and delete the Magnolia demo instance:


# az webapp stop --name mgnlazuredemo --resource-group MagnoliaAzureDemoResourceGroup
# az webapp delete --name mgnlazuredemo --resource-group MagnoliaAzureDemoResourceGroup

Adjust Magnolia instance properties

Open the magnolia.properties file you created above and add the following lines:


magnolia.content.bootstrap.dir=/var/lib/mgnl-public/content-importer
magnolia.upload.tmpdir=/var/tmp/mgnl-public-uploaded
magnolia.exchange.history=/var/tmp/mgnl-public-history
magnolia.home=/home/site/magnolia
magnolia.resources.dir=/home/site/magnolia/resources
magnolia.cache.startdir=/home/site/magnolia/cache
magnolia.repositories.home=/home/site/magnolia/repositories
magnolia.logs.dir=/home/site/magnolia/log
magnolia.author.key.location=/home/site/magnolia/magnolia-activation-keypair.properties

For a public instance, set magnolia.update.auto=true, to trigger module installations automatically rather than giving your visitors the option to update Magnolia.


# Set it to true if bootstrapping/update should be performed automatically
magnolia.update.auto=true

Deploy the new build

Repeat the previous steps:


# mvn clean package -P ROOT
# mvn azure-webapp:deploy

Once the instance has been deployed successfully, navigate to your application URL and clear your browser cache if necessary.

Troubleshooting

If Magnolia fails to start, check its log file by connecting to the container via SSH:


# az webapp ssh -n mgnlazuredemo -g MagnoliaAzureDemoResourceGroup
# tail -f /home/site/magnolia/log/magnolia-debug.log

Clean up Azure resources

Attention: Remove any unused resources and orphaned artifacts to prevent being charged for them by Microsoft.

Use the Azure portal or clean up on the command line:


# az webapp stop --name mgnlazuredemo --resource-group MagnoliaAzureDemoResourceGroup
# az webapp delete --name mgnlazuredemo --resource-group MagnoliaAzureDemoResourceGroup
# az group delete --name MagnoliaAzureDemoResourceGroup

Simplifying Magnolia deployments with Azure App Service

Azure App Service is a convenient way to deploy Maven-based Magnolia projects to the cloud. It builds on an existing tool stack and requires only some initial configuration. Furthermore, it provides integrations for the most popular Java IDEs out-of-the-box.

Azure App Service’s stability and reliability have improved significantly in recent years. However, its “self-patching” approach might pose challenges in production environments. A productive installation might also require higher standards of performance, data storage, and scalability.

In any case, it is a solution that relieves developers from providing and configuring their own infrastructure whether you use it for testing or more.

Additional Resources

About the Author

Lars Fischer Professional Services at Magnolia

Lars Fischer works for Magnolia’s Professional Services team and is involved in pre-sales and post-sales consultancy. He supports customers with a wide range of topics including implementations of Magnolia, integrations, and security.