WIXLIB

Magnolia in a CanContainerizing Your Magnolia Web AppNow that you have made all the decisions about the ingredients for yourimage, it’s time to containerize your Magnolia web app.BEST PRACTICEMake your Magnolia web application self-starting.By default, your Magnolia web app requires your input when starting up.You will be prompted to: Approve the installation of Magnolia Enter your Magnolia licenseTo start Magnolia without your intervention you can enable auto updatesand configure your license.Enable Auto UpdateWhen Magnolia starts up for the first time or a Magnolia module hasbeen updated, Magnolia will prompt you before proceeding with theinstallation or update.You can avoid this prompt by setting a Magnolia property:magnolia.update.auto trueWhen set to true, Magnolia will proceed with installing or updating itselfwithout prompting.Magnolia properties are a powerful way to control and run Magnolia andcome in handy when containerizing your Magnolia web application. Wewill discuss other Magnolia properties later on.11

Magnolia in a CanConfigure the Magnolia LicenseMagnolia expects to find its license in the JCR repository. You can seeyour Magnolia license by opening the Configuration app and navigatingto /modules/enterprise/license.If Magnolia does not find its license there, Magnolia will prompt you toenter the license during start-up.There are several options for adding your Magnolia license: Bundling the license in the Magnolia web app: create a Mavenmodule that sets the license when it is loaded. Setting the license from the container environment: use theConfiguration Injection module to add your license at runtime. Building a custom Magnolia Java module: a custom module canretrieve and set the license when Magnolia starts.Each of the above options has pluses and minuses:Bundling the license in the Magnolia web appBundling your license into your Magnolia web app puts an expirationdate on your web app. When the Magnolia license expires, the Magnoliaweb app will start but some features will be disabled. Including theMagnolia web app in your Docker image means your Docker image hasan expiration date as well.This is typically not an issue, because chances are that you will updatethe Magnolia web app before the license expires, so including anupdated license won’t be a lot of extra work.However, bundling the license in a module and including it in yourMagnolia web app could be considered a security risk. Your licensecould be recovered from the Magnolia WAR file, your source code, orDocker image.To protect your Magnolia license, make sure that your artifact andsource code repositories as well as your Docker artifacts are secure.12

Magnolia in a CanSetting the license from the container environmentYou can’t set the Magnolia license through Magnolia properties outof-the-box, but you can use the Configuration Injection module fromMagnolia’s Incubator. This module allows you to set the Magnolia licensefrom a Magnolia property when Magnolia starts up. This approachallows you to set the license using a Docker ENV variable when startingyour container decoupling the license from the Magnolia web app.Setting the Magnolia license from the container environment could beconsidered a security risk as well, but it minimizes the number of placesthe Magnolia license can be recovered from. To eliminate this risk, youcould use your container platforms's security features, for example bypassing your license as a Secret.Building a custom Magnolia Java moduleDon’t like either bundling the license in the Magnolia web app or settingthe license from the container environment? Or do you have additionalrequirements, for example, retrieving your Magnolia license from asecure vault? Then building a custom Magnolia Java module may be thebest option for you.Magnolia Java modules have lots of useful tools like startup tasksand dependency management. This option gives you total freedom toimplement a solution that meets your needs.Building a custom Magnolia Java module requires some knowledge ofJava, Java tools like Maven, and possibly the Content Repository API forJava (a.k.a. JCR), as well as an understanding of how Magnolia is puttogether.13

Magnolia in a CanOf the options above, this is what we recommend:BEST PRACTICESet the license from the container environment using theConfiguration Injection module.The Configuration Injection module introduces the system propertymagnolia.inject.config. It can be used to create a startup task thatsets the Magnolia license at /modules/enterprise/license:magnolia.inject.config :/modules/enterprise/license,owner, email for license ;setProperty:/modules/enterprise/license,key, your Magnolia license key For more information on the Configuration Injection module Configuration Injection.If you prefer to bundle the license in the Magnolia web app you cancreate a Magnolia Java module that automatically loads the license onstartup.Magnolia Java modules are one of the basic ways to customizeand extend Magnolia. They require some Java coding to produce aJava jar file, but in our case the amount of coding is limited. You canalso find a template for a license bundle module here: os/autolicense/browse.For more information on developing Magnolia Java modules, check thefollowing ay/DOCS62/How to create and use a custom Magnolia Maven module for custom Java isplay/DOCS62/Bootstrapping in Maven modules14

Magnolia in a CanMagnolia properties and containerizationMagnolia properties control key aspects of Magnolia when it is running.Above we mentioned the Magnolia property magnolia.update.auto,but there are many other Magnolia properties you may want to use inyour Docker image.Magnolia properties can control: Whether Magnolia runs as an author instance or a public instanceThe configuration of the JCR repositoriesDatabase connectionFile system locations for: ResourcesLight modulesMagnolia publication keysTemporary filesMagnolia properties can be set in property files included in yourMagnolia web application but you can override any Magnolia property bysetting a Java property with the same name to a new value.For more on Magnolia property files, see S62/WAR file with multiple agnolia.propertiesfile.Here’s a quick tour of some of the more interesting Magnolia properties:magnolia.home: the granddaddy of all Magnolia properties,magnolia.home is used to set several other Magnolia propertiesspecifying locations like magnolia.resources.dir (location ofMagnolia resources and light content), magnolia.cache.startdir(location of persisted Magnolia cache files), magnolia.upload.tmpdir (destination of files uploaded to Magnolia), magnolia.repositories.home (location of Magnolia’s JCR repository),magnolia.logs.dir (location of Magnolia log files) and magnolia.author.key.location (location of the Magnolia publication key).magnolia.home is used to specify other file system destinations usedby Magnolia under a parent directory.Don’t forget: you can still override individual Magnolia properties defininglocations.15

Magnolia in a Canmagnolia.update.auto: if true, Magnolia doesn't wait for user inputto install or update Magnolia.magnolia.resources.dir: the location of Magnolia light modules.Your Magnolia web application will probably be a combination ofMagnolia Java modules and Magnolia light modules consisting of filesread from the file system.If you want to use light modules in your Magnolia container, you maywant to set magnolia.resources.dir to a Docker volume where youadd files to and share among your Magnolia containers.magnolia.repositories.home: the directory where Magnolia storesJCR repository files and Lucene indices. You may want to persist,add or modify these files for your Magnolia container. magnolia.repositories.home lets you set its location.magnolia.repositories.jackrabbit.config: the location ofthe Jackrabbit JCR configuration file. This file contains databaseconfiguration and file locations.magnolia.logs.dir: the directory where Magnolia log files will bestored.magnolia.bootstrap.dir: the directories where bootstrap contentwill be loaded from.magnolia.bootstrap.authorInstance: one of the mostfundamental Magnolia properties. It controls whether Magnolia will runas an author instance (true) or as a public instance (false).magnolia.develop: improves Javascript generation performancewhen developing, should be set to false for production deployments.You may want to change this based on how the container is used(development versus production containers).magnolia.author.key.location: the location of the private andpublic key used for publication of content from author to public instances.You can also define your own properties and use them in Magnoliaconfiguration files. This includes the Jackrabbit JCR configuration file.16

Magnolia in a CanHere’s an example: DataSources DataSource name "magnolia" param name "driver" value "com.mysql.jdbc.Driver" / param name "url" value "jdbc:mysql://localhost:3306/magnolia" / param name "user" value "root" / param name "password" value "password" / param name "databaseType" value "mysql"/ param name "validationQuery" value "select 1"/ /DataSource /DataSources The properties magnolia.database.url, magnolia.database.user and magnolia.database.password now specify the databaseconnection used by the JCR repository and can be set when you buildyour Docker image or run the container.BEST PRACTICESet key Magnolia properties as Java properties, e.g.-Dmagnolia.update.auto true when running the JVMcontaining Magnolia.There are a couple of ways to do this: In your ENTRYPOINT script If you are using Tomcat, in the CATALINA OPTS environment variableor a setenv.sh scriptHere’s a simple example of a setenv.sh script that initializesCATALINA OPTS:#!/usr/bin/env bash# Container settings - Adjust these default settings according to your needs## JVM settings#17

Magnolia in a Canexport CATALINA OPTS " CATALINA OPTS \-server \-Djava.security.egd file:/dev/./urandom \-Djava.awt.headless true"## JVM memory settings#export CATALINA OPTS " CATALINA OPTS \-Xms JVM XMS \-Xmx JVM XMX"This script defines the Java properties java.security.egd and java.awt.headless as well as the starting and maximum heap size for theJVM. It also enables the Java HotSpot Server VM.The starting and maximum heap sizes are set from environmentvariables when the JVM is started and could be set from ENV variablesyou define for your Docker image.BEST PRACTICEUse ENV and ARG parameters to set important Magnoliaproperties.With so many Magnolia properties, what properties should you setthrough ENV and ARG parameters?It’s hard to give absolute recommendations without qualifications forevery situation, but we recommend thinking about what you want to endup with: one image that can be run in any situation (possible, but you’llprobably end up with a lot of ENV parameters and possibly encounterproblems setting several related Magnolia properties) or several imageswith some key Magnolia properties set as ARGs and other Magnoliaproperties set as ENV properties.18

Magnolia in a CanHere’s a breakdown of how commonly used Magnolia properties mightbe considered as ENV or ARG parameters:ENV parametersMagnolia display properties like magnolia.ui.sticker.environment, magnolia.ui.sticker.color, magnolia.ui.sticker.color.background and magnolia.webapp.These properties can be used to customize the appearance of MagnoliaAdmincentral to help users identify what Magnolia instance they areusing, such as a production, test or dev instance; and the Magnoliainstance, such as author or public instance.ARG parametersMagnolia path properties like magnolia.resources.dir, magnolia.repositories.home, magnolia.bootstrap.dir, magnolia.logs.dir and magnolia.author.key.location.These locations could be set with ENV parameters, but you will probablywant a standard layout for your Magnolia related files and directoriesfor all your Magnolia containers. You can implement a standard filestructure for Magnolia by setting these as ARG parameters.ENV or ARG parametersMagnolia runtime properties like magnolia.bootstrap.authorInstance and magnolia.develop.Magnolia Jackrabbit properties like magnolia.repositories.jackrabbit.config or custom Java properties used in Jackrabbitconfiguration or the magnolia.properties file.These are Magnolia properties that could be set as ARG parametersif you want Docker images with fixed key Magnolia properties or ENVparameters if you want to defer the setting of Magnolia properties todeployment time.19

Magnolia in a CanJVM settingsWhile you are setting your Magnolia properties, don’t forget to setimportant JVM parameters, such as: Starting heap size Maximum heap size Garbage collection settingsBEST PRACTICESet a starting heap size of at least 1 GB, e.g. -Xms1g.Magnolia does a lot of work on starting up; a larger starting heap sizewill minimize start up duration by reducing time for collecting garbage.BEST PRACTICEMonitor memory usage in your Magnolia web app underrealistic conditions to determine the optimal maximumheap size.We can’t give a blanket recommendation for what your maximumheap size should be. It really depends on your Magnolia web app, butmaximum heap sizes from 2 to 4 GB are common. Keep in mind thatbigger is not necessarily better: a very large heap might reduce thenumber of garbage collections but make them longer, interruptingrequest handling.20

Magnolia in a CanBEST PRACTICEUse the -XX: AlwaysActAsServerClassMachine flag ifyour JVM supports it.This sets better garbage collection defaults for a Docker container andhelps you avoid less efficient serial garbage collection.We have touched on the complicated subject of JVM garbage collectionconfiguration.Given different JVMs, different servlet containers, differentMagnolia web apps, it’s hard to go beyond the generalrecommendations we have made (starting and max heap settings, theAlwaysActAsServerClassMachine flag).There can be performance gains by tuning the garbage collectionof your JVM, but there are a couple of caveats: you should test yourchanges in realistic conditions (as we mentioned earlier) and avoidtunnel vision.'Realistic conditions' means reproducing the requests and traffic volumeyou expect or want to serve with a Magnolia instance. 'Tunnel vision'means not ignoring other ways to gain performance. In general, othermeans like implementing a good caching strategy, tuning the Tomcatconnection or looking for performance bottlenecks in your Freemarkertemplates will yield bigger performance wins than tuning your JVMgarbage collection. And don’t forget, if you containerized your Magnoliapublic instance, you could always spin up a new container to handlemore traffic.21

Magnolia in a CanDocker container runtime settingsOne important container setting often overlooked when runningMagnolia is the open files limit.GOTCHA!Magnolia needs a generous open files limit to run.An open files limit of 1024 in a container may not besufficient, especially if you use an embedded database.You have hit the open files limit if you see errors like this:SEVERE: Endpoint ServerSocket[addr 0.0.0.0/0.0.0.0,port 0,localport 80] ignoredexception: java.net.SocketException: Too many open filesjava.net.SocketException: Too many open er SearchManager.java(onEvent:431)17.01.2008 12:52:00Error indexing node.java.io.FileNotFoundException: lia/workspaces/config/index/redo.log (Too many open files)Magnolia usually needs more than 1024 open files to run, so set theopen file limit to something generous when running the Magnoliacontainer:docker run -it --ulimit nofile soft limit : hardlimit your image See: ne/run/#setulimits-in-container---ulimit22

Magnolia in a CanContainerizing Your ContentOnce you have created a container including the Magnolia webapplication and all its ingredients, you may want to think about what isgoing to happen when you launch a container based on your image.Suppose your Magnolia container is going to be used as a Magnoliapublic instance. In that case your instance will have defined web pages,images, resources and other web content.Some of that content - page, area and component templates,customizations of Magnolia apps and configuration and more - may bedefined as 'light' content.Some of the content may be bootstrapped from Magnolia modules inyour Magnolia web application but you may want to load other contentwhen starting Magnolia in a new container.Suppose you have this scenario: a Magnolia author instance and twoMagnolia public instances running in Docker containers built from yourMagnolia image. You want to start a third Magnolia public instance tohandle increased traffic.That new Magnolia public instance must have the same content (webpages, images, resources, etc.) as the other public instances.There are a few ways of initializing content on a new Magnolia publicinstance: Restore the JCR repository on the new instance from a backupSynchronize the content from the Magnolia author instanceImport an export the JCR repositoryAdd bootstrapped content to a Magnolia module included in theMagnolia web appYou can even use a mixture of the above techniques to initialize thecontent on a new Magnolia instance.23

Magnolia in a CanThe above techniques may affect how you build your image. Forexample, you could: Add logic to your CMD or ENTRYPOINT script to retrieve a Magnoliabackup and restore it before starting the web container and Magnolia. Chain together separate scripts in your CMD or ENTRYPOINT, oneto retrieve a backup and restore it, another one to launch the webcontainer and Magnolia. Add logic to your CMD or ENTRYPOINT script to launch contentsynchronization between your new Magnolia public instance and theMagnolia author instance.Capturing content: backup and restoreIf you have a running Magnolia instance with up-to-date content, you canmake a copy of the content and restore it on a new Magnolia instance.Let’s take a closer look at your options for backing up and restoringMagnolia content.Magnolia Backup moduleMagnolia has its own backup and restore tool: https://documentation.ma

Pro: Better performance, especially on large repositories Pro: Better tools for monitoring and management Pro: Can use a single database service for multiple Magnolia instances Con: Another service to containerize and manage Decision #2.1: Determine whether to run Magnolia and its database in the same container or in separate containers