Magnolia Code Server Documentation

Providing a Docker container for Magnolia Development from many aspects, using various Arguments to set it up in the way you desire.

With the vast array of system architectures, many scenarios can lead to issues getting a proper environment up-and-running. This is a solution to remove those potential road-blocks.

This Dockerfile is widely diverse, providing you with the ability to use it for purely frontend development, or for your more advanced use-cases, backend development in addition to all the frontend capabilities. This document will provide you with all the configurations available to produce the exact architecture you need.

Introduction

You can get the project code from the Magnolia Code Server Git repository.

Once you have the project, you can browse the available examples in the servers directory, or simply create your own within a new folder, and defining the arguments in the docker-compose.yml file. For example, if you want the most minimalistic environment (Code Server, Magnolia Community Demo Webapp Edition via Jumpstart), your docker-compose.yml file would look like this:

servers/my-docker-container/docker-compose.yml

version: '3.3'
services:
  minimal-code-server:
    build:
      context: ../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
    ports:
      - "8443:8443"
      - "8080:8080"

If you are using Apple Silicon (Apple M1+), you should check out Install with Multipass to set up Multipass to work natively instead of using Rosetta.

Once you run docker-compose up from servers/my-docker-container, you would be able to access the Code Server from http://localhost:8443/, where you could start up Magnolia using mgnl jumpstart from the magnolia directory. If you have deployed this container someplace other than your localhost, just modify that with the IP.

The following section will walk you through the various configurations you can use either in a docker-compose.yml file, or by docker build. When you are familiar with the configuration arguments, you can take a look at Example Servers to help guide you to build the server that’s right for you.

Arguments

Below is a list of the arguments that you can use to define your Docker container. You can also jump directly to Frontend Development Arguments or Backend Development Arguments.

General Settings

These settings apply to any type of Code Server. All Code Servers are deployed on the Ubuntu 20.04 platform, will come with Visual Studio Code Server’s web-based IDE, a JDK of your choosing, NodeJS, and Magnolia’s CLI. Additionally, the VSCode server will be populated with several extensions to make development even easier. These are the extensions that are provided for all Code Servers:

Freemarker/Magnolia/HTML Snippets
Freemarker
Tomcat for Java^[1]
YAML
GitLens — Git supercharged
Prettier - Code formatter
indent-rainbow
VS Code Java Pack

Argument Description Default Value Options/Type

CODE_USER

The user account name that will be used to access the server. This account does not have sudo rights, but will have access to a terminal via the Code Server browser.

magnolia

String

CODE_GROUP

The group that the user will be assigned.

magnolia

String

SYSPASSWORD

The user password for access to the server.

magnolia

String

CPU_ARCH

The CPU used by the system.

If the host machine is an M1+ Apple Silicon CPU, make sure to set this value to "arm64". You can also set this at build time with:

`docker-compose build --build-arg CPU_ARCH="arm64"

amd64

amd64
arm64

TZ

The Time Zone applied to the server. See TZ database name on Wikipage table

Etc/UTC

String

Table 2. Code Server Settings
Argument	Description	Default Value	Options/Type
`CODE_RELEASE`	The version of VSCode Server. See coder/code-server on GitHub for available releases.	4.6.1	Version String
`AUTH`	The type of authorization for accessing Code Server. Further configurations will come, at this time, only a simple password can be configured.	password	password none
`PASSWORD`	When `AUTH` is set to `password`, this is the password to use when logging into the web browser.	magnolia	String

Argument Description Default Value Options/Type

NODE_JS_VERSION

The version of NodeJS to install.

JDK_VERSION

The version of Java to install to the system.

If you choose a version other than JDK 11, you must also configure your Magnolia server with Backend-Live. Additionally, if you choose the DEV_PERSPECTIVE of "backend", you must also set COPY_MVN_SETTINGS_XML: "true", and add your settings.xml to the install-resources folder.

JDK_TYPE

The JDK Provider.

openjdk

openjdk
graalvm

GRAAL_VM_VERSION

The GraalVM version to use, if you choose JDK_TYPE: graalvm.

22.2.0

openjdk
graalvm

You should always, at a minimum, set the SYSPASSWORD and PASSWORD properties.

In the following sections, you will see that there are several arguments that are shared between both types of deployments.

Frontend Development Arguments

This section will provide you with an overview of configuration for the frontend code server. If you’d like information on how to use the server, you can jump directly to Frontend Code Server

Argument Description Default Value Options/Type

DEV_PERSPECTIVE

Set’s the type of development environment to target.

Since the default is "frontend", it is unnecessary to set this property.

"frontend"

"frontend"
"backend"

WEBAPP_EDITION

This is the type of Magnolia Server you would like to install.

If you choose a DX Core edition, you will need to provide the NEXUS_USER and NEXUS_PW

magnolia-community-demo-webapp

magnolia-empty-webapp
magnolia-community-webapp
magnolia-community-demo-webapp
magnolia-dx-core-webapp
magnolia-dx-core-demo-webapp
git-project^[2]

2. Not Applicable to Frontend Development Server

MAGNOLIA_VERSION

The version of Magnolia that you wish to jumpstart.

6.2.23

Version String

NEXUS_USER

This is your LDAP user that gives you access to the Magnolia Nexus repository. This will be required if you are using any DX Core version of Magnolia.

"anonymous"

String

NEXUS_PW

This is your LDAP password that gives you access to the Magnolia Nexus repository. This will be required if you are using any DX Core version of Magnolia.

It is best not to set this in a file, rather use docker-compose build --build-arg NEXUS_PW=$NEXUS_PW

"anonymous"

String

BACKEND_LIVE

If you wish to include the Backend Live extensions, you can set this to "true".

"false"

"true" or "false"^[3]

3. Booleans must be Quoted!

BACKEND_LIVE_SAMPLES

Along with using Backend Live extensions, you can also include some sample Backend Live Light Modules

"false"

"true" or "false"^[4]

4. Booleans must be Quoted!

BACKEND_LIVE_SAMPLES_GIT_REPO

It is unlikely that you would need to change this repository location, unless you have an alternative set of sample light modules.

If you do have an alternative set of Light Modules, the repository must have a folder called light-modules at it’s root where the actual modules are located.

"https://git.magnolia-cms.com/scm/light-modules/backend-live-samples.git" Browse the Repo

URL

HA

This will install the Headless Accelerator. Currently, you will have to follow the steps in the previous link in order to complete the installation process.

"false"

"true" or "false"^[5]

5. Booleans must be Quoted!

MGNL_HA_AUTH_TOKEN

If you wish to install HA, you will need to provide this property until HA-130 is resolved. If you would like to find out how to get your Authentication Token, see Get Nexus Authorization Token

Null

Your authentication token.

Backend Development Arguments

This section will provide you with an overview of configuration for the backend code server. If you’d like information on how to use the server, you can jump directly to Backend Code Server

Argument Description Default Value Options/Type

DEV_PERSPECTIVE

Set’s the type of development environment to target. For a Backend Code Server, it is required to set this to "true"

"frontend"

"frontend"
"backend"

WEBAPP_EDITION

This is the type of Magnolia Server you would like to install. The build scripts will use the Magnolia Maven Archetype to generate a parent project containing a webapp project. Node scripts are used to modify the POM files to match your selection. If you choose an edition that contains demo, the travel demo dependencies will be included in your POM files.

If you choose a DX Core edition, you will need to provide the NEXUS_USER and NEXUS_PW

magnolia-community-demo-webapp

magnolia-empty-webapp
magnolia-community-webapp
magnolia-community-demo-webapp
magnolia-dx-core-webapp
magnolia-dx-core-demo-webapp
git-project

MAGNOLIA_VERSION

The version of Magnolia that you wish to create.

6.2.23

Version String

NEXUS_USER

This is your LDAP user that gives you access to the Magnolia Nexus repository. This will be required if you are using any DX Core version of Magnolia.

"anonymous"

String

NEXUS_PW

This is your LDAP password that gives you access to the Magnolia Nexus repository. This will be required if you are using any DX Core version of Magnolia.

It is best not to set this in a file, rather use docker-compose build --build-arg NEXUS_PW=$NEXUS_PW

"anonymous"

String

GIT_PROJECT

The URL used to clone your desired Git repository.

If you set WEBAPP_EDITION to git-project, this argument is required!

URL

TOMCAT_VERSION

The Apache Tomcat version you prefer to use. Apache will remove old versions of Tomcat from time-to-time, so it is good to check Tomcat’s Download Page if you get an error on build.

9.0.65

Version String

COPY_MVN_SETTINGS_XML

If you provide your Nexus credentials, the Docker build will generate the appropriate settings.xml files to download dependencies. If you prefer to use an existing file, you can simply set this property to "true" and add your settings.xml file to the install-resources folder.

"false"

"true" or "false"^[6]

6. Booleans must be Quoted!

MODULE_GROUP_ID

This value will apply to your project’s <groupId> setting for your project.

info.magnolia.dev

String

MODULE_NAME

The name of the Magnolia project. This is the name of the parent project. The parent project will have a webapp module called `${MODULE_NAME}-webapp.

magnolia-dev-project

String

MODULE_CLASS_NAME

The class name of the Magnolia Module.

magnolia-dev-project

String

MAGNOLIA_PUBLIC

If this server is a public server, set value to true

false

String

MAGNOLIA_PUBLIC_BOOTSTRAP

If you have a public server, you need to modify the bootstrap file to point to the appropriate public server(s). If you have modified a bootstrap file, set this to true

false

String

BACKEND_LIVE

If you wish to include the Backend Live extensions, you can set this to "true".

"false"

"true" or "false"^[7]

7. Booleans must be Quoted!

BACKEND_LIVE_SAMPLES

Along with using Backend Live extensions, you can also include some sample Backend Live Light Modules

"false"

"true" or "false"^[8]

8. Booleans must be Quoted!

BACKEND_LIVE_SAMPLES_GIT_REPO

It is unlikely that you would need to change this repository location, unless you have an alternative set of sample light modules.

If you do have an alternative set of Light Modules, the repository must have a folder called light-modules at it’s root where the actual modules are located.

"https://git.magnolia-cms.com/scm/light-modules/backend-live-samples.git" Browse the Repo

URL

HA

This will install the Headless Accelerator. Currently, you will have to follow the steps in the previous link in order to complete the installation process.

"false"

"true" or "false"^[9]

9. Booleans must be Quoted!

MGNL_HA_AUTH_TOKEN

If you wish to install HA, you will need to provide this property until HA-130 is resolved. If you would like to find out how to get your Authentication Token, see Get Nexus Authorization Token

Null

Your authentication token.

Example Servers

The server configurations provided in the servers folder are examples to help guide you to build the system that best suits your needs and Use Case. You can try different configurations as you wish. The easiest way to build a system is using docker-compose, although you are free to build images with docker.

Building with DXCore

When using DXCore, you will need to provide your Nexus credentials in order to properly access the DXCore resources.There are two properties, NEXUS_USER and NEXUS_PW to set these.These properties should never be set in your YAML file, in case you accidentally check this in.Instead, you can set these values on the build command like this:

export NEXUS_PW=YOUR PASSWORD
docker-compose build --build-arg NEXUS_USER=srhodes --build-arg NEXUS_PW=$NEXUS_PW

For use of the Headless Accelerator, there is one additional argument that is currently necessary, MGNL_HA_AUTH_TOKEN.You can find your token by following the instructions at Get Nexus Authorization Token

For these builds, just add it to the build command:

export NEXUS_PW=YOUR PASSWORD
export MGNL_HA_AUTH_TOKEN=YOUR ACCESS TOKEN
docker-compose build --build-arg NEXUS_USER=srhodes --build-arg NEXUS_PW=$NEXUS_PW --build-arg MGNL_HA_AUTH_TOKEN=$MGNL_HA_AUTH_TOKEN

Frontend Code Server

A Frontend Server will make use of the Magnolia CLI to jumpstart a Magnolia server with an Author and a Public instance.Once your server is up, simply open a terminal in VSCode Server, navigate into the magnolia folder, and run mgnl start.

The following are meant to serve as an example for your development server, but can be configured more specifically to meet your Use Case.

The Vanillaist

This is about as simple as the frontend servers come. You can find the prepared server in this project at servers/frontend/frontend-default-jdk11/docker-compose.yml. It’s going to provide you with a basic magnolia-community-webapp server. As usual, we suggest you override the passwords, as the default value is always magnolia. In this example, we’re making it just slightly less generic, so you should get slightly more inventive for your actual implementation. If you use a docker-compose.yml file, this is how it would look:

servers/frontend/frontend-default-jdk11/docker-compose.yml

version: '3.3'
services:
  minimal-code-server:
    build:
      context: ../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
    ports:
      - "8443:8443"
      - "8080:8080"

Then, in the directory, simply run docker-compose up from the directory containing your YAML file.

Working with Backend Live

In the example servers, we have two examples. One is using the community edition, and the other is using DXCore. There is one other configuration available, where you could use the GraalVM JDK instead of the OpenJDK installation. We will discuss those configurations. Here is an example of a server using OpenJDK 11, Magnolia Community Edition, and some sample Backend-Live Light Modules:

servers/frontend/frontend-default-jdk11-backendlive/docker-compose.yml

version: '3.3'
services:
  frontend-default-jdk11-backendlive:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        BACKEND_LIVE: "true"
        BACKEND_LIVE_SAMPLES: "true"
    ports:
      - "8443:8443"
      - "8080:8080"

Then, in the directory, simply run docker-compose up from the directory containing your YAML file.

If you prefer to use DXCore, the YAML file only needs one more attribute, and would look like this:

servers/frontend/frontend-dxcore-jdk11-backendlive/docker-compose.yml

version: '3.3'
services:
  frontend-dxcore-jdk11-backendlive:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        BACKEND_LIVE: "true"
        BACKEND_LIVE_SAMPLES: "true"
        WEBAPP_EDITION: magnolia-dx-core-demo-webapp
    ports:
      - "8443:8443"
      - "8080:8080"

One last configuration that could be interesting is using an alternative JDK, specifically the GraalVM provided JDK. Here is an example of how to configure that.

servers/frontend/frontend-dxcore-graalvm-11-backendlive/docker-compose.yml

version: '3.3'
services:
  frontend-dxcore-graalvm-11-backendlive:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        JDK_VERSION: graalvm-ce-java11-22.2.0
        BACKEND_LIVE: "true"
        BACKEND_LIVE_SAMPLES: "true"
        WEBAPP_EDITION: magnolia-dx-core-demo-webapp
    ports:
      - "8443:8443"
      - "8080:8080"

Working with HA

This is still undergoing implementation. At this time, you are only installing the HA CLI, and building a separate Magnolia instance.

Since HA requires the use of DX Core, we will specify the DXCore WEBAPP_EDITION. You could also change this to magnolia-dx-core-demo-webapp if you wish to have the travel demo and some example content loaded. Remember, this is going to change as this server is not currently used by HA as of version 1.0.6.

servers/frontend/frontend-dxcore-jdk11-ha/docker-compose.yml

version: '3.3'
services:
  frontend-dxcore-jdk11-ha:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        WEBAPP_EDITION: magnolia-dx-core-webapp
        HA: "true"
    ports:
      - "8443:8443"
      - "8080:8080"
      - "3000:3000"

Then, in the directory, simply run docker-compose up from the directory containing your YAML file.

Backend Code Server

The primary difference between a Frontend Server and the Backend Server is that most of the Backend Servers use Maven to build the Magnolia Webapp. Additionally, by default, there will only be a single Author webapp and no Public servers. This gives you the ability to develop your backend functionality.

With Backend Servers, Maven is also installed to manage dependencies and build your webapp. When the server is built, the Magnolia Maven Archetype to build a parent project that maintains a webapp project. With the VSCode extensions, you will be able to run your server, debug the source code, and even perform Hot Code Replacement.

Deploying your Webapp

With Frontend Servers, you would start Magnolia using the Magnolia CLI. With Backend Servers, you will use the Apache Tomcat VSCode Extension.

To do so, you first would add Tomcat to the configuration by:

Click the + in the Tomcat Servers
Point to /home/magnolia/tomcat/apache-tomcat-${VERSION}

Now you will want to modify the JVM settings, which is fortunately quite simple. Just right-click on the new server, then click Customize JVM Options.

This will open a file, where you will add your customizations. The minimum customizations would look like this:

-Dmagnolia.repositories.home=/home/magnolia/repositories
-Dmagnolia.resources.dir=/home/magnolia/workspace/light-modules

This just changes the locations for the JCR Workspace, and the location for your Magnolia Resources where frontend development will take place.

If you are using JDK 17 and above, you would also need to add a flag to deal with some JDK issues like this:

--add-opens java.base/java.lang=ALL-UNNAMED
-Dmagnolia.repositories.home=/home/magnolia/repositories
-Dmagnolia.resources.dir=/home/magnolia/workspace/light-modules

Next, you will need to add your Webapp to the Server. The Webapp is located in your project within the *-webapp/target directory. You can either add the .war file or the folder with the same name. If you plan to do Hot Code Replacement, you need to use the "exploded" (non .war folder).

Just right-click on your webapp, and then click Debug on Tomcat Server. This will automatically start the deployment.

You can use the following examples to guide you in building the exact Backend Server to fit your needs.

Default Community Edition

The default Magnolia configuration, if left undefined, is the magnolia-community-webapp. You can find the prepared server in this project at servers/backend/backend-ce-jdk11/docker-compose.yml. As usual, we suggest you override the passwords, as the default value is always magnolia. If the version of the JDK is left unspecified, it will install Open JDK 11. Also, installed is Maven version 3.8.6 and Tomcat 9.0.65. If you run into issues on building a Backend Server, and the error occurs during the Tomcat installation, please check Tomcat’s Download Page as Apache doesn’t always maintain older versions.

It is also a good idea to override the MODULE_* properties as these will be the name of the generated project.

The WEBAPP_EDITION use the same naming convention as the Frontend Servers for convenience. There is some magic tricks added to take this edition to modify the POM’s of the parent and webapp projects. Basically, the POM’s are modified to point to the proper dependencies to use community, dxcore, and even add the travel demo modules if you indicate a *-demo-webapp edition.

In this example, we’re making it just slightly less generic, so you should get slightly more inventive for your actual implementation. If you use a docker-compose.yml file, this is how it would look:

servers/backend/backend-ce-jdk11/docker-compose.yml

version: '3.3'
services:
  backend-ce-jdk11:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        DEV_PERSPECTIVE: backend
        WEBAPP_EDITION: magnolia-community-webapp
        MODULE_GROUP_ID: info.magnolia.demo
        MODULE_CLASS_NAME: MyDemoModule
        MODULE_NAME: magnolia-dev-demo-project
    ports:
      - "8443:8443"
      - "8080:8080"

Then, in the directory, simply run docker-compose up from the directory containing your YAML file.

If you would like to include the travel demo with example content, simply change WEBAPP_EDITION: magnolia-community-webapp to WEBAPP_EDITION: magnolia-community-demo-webapp.

DXCore Edition

This example is nearly identical to the previous example, but uses DXCore. Here is the YAML configuration:

servers/backend/backend-dxcore-jdk11/docker-compose.yml

version: '3.3'
services:
  backend-dxcore-jdk11-ha:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        DEV_PERSPECTIVE: backend
        WEBAPP_EDITION: magnolia-dx-core-webapp
        MODULE_GROUP_ID: info.magnolia.demo
        MODULE_CLASS_NAME: MyDemoModule
        MODULE_NAME: magnolia-dev-demo-project
    ports:
      - "8443:8443"
      - "8080:8080"

The big difference is that you will need to provide your Nexus Credentials as shown in Building with DXCore.

Just like in the previous example, if you’d like to add the travel demo modules and sample content, just change WEBAPP_EDITION: magnolia-dx-core-webapp to WEBAPP_EDITION: magnolia-dx-core-demo-webapp.

Add Backend Live

If you’d like to use the experimental Backend Live functionality, you can do so by following this example:

servers/backend/backend-dxcore-jdk11-backendlive/docker-compose.yml

version: '3.3'
services:
  backend-dxcore-jdk11-backendlive:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        DEV_PERSPECTIVE: backend
        BACKEND_LIVE: "true"
        BACKEND_LIVE_SAMPLES: "true"
        WEBAPP_EDITION: magnolia-dx-core-demo-webapp
    ports:
      - "8443:8443"
      - "8080:8080"

This example also adds BACKEND_LIVE_SAMPLES which are a collection of Light Modules showing the various capabilities like custom Actions, Availability Rules, UI elements, and Commands.

Since Backend Live uses Javascript Models 2, you are now able to work with more modern JDK’s. You can configure your Backend Server to use JDK 17, for example by using the following YAML configuration:

servers/backend/backend-dxcore-jdk17-backendlive/docker-compose.yml

version: '3.3'
services:
  backend-dxcore-jdk17-backendlive:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        DEV_PERSPECTIVE: backend
        JDK_VERSION: java-17-openjdk-amd64
        BACKEND_LIVE: "true"
        BACKEND_LIVE_SAMPLES: "true"
        WEBAPP_EDITION: magnolia-dx-core-demo-webapp
    ports:
      - "8443:8443"
      - "8080:8080"

Using a Git Repo

If you prefer to use an existing Git Repository rather than building a new Maven project, you can do so with the following configuration:

servers/backend/fullstack-training-git/docker-compose.yml

version: '3.3'
services:
  fullstack-training-git:
    build:
      context: ../../../
      args:
        PASSWORD: magnolia123
        SYSPASSWORD: magnolia123
        DEV_PERSPECTIVE: backend
        WEBAPP_EDITION: git-project
        GIT_PROJECT:  https://USER_NAME:PASSWORD@git.magnolia-cms.com/scm/training/training-fullstack-project.git
        COPY_MVN_SETTINGS_XML: "true"
    ports:
      - "8443:8443"
      - "8080:8080"

There are some points of interest to discuss here. First, the Git Project depends on having a valid login. If you have anonymous access, you can simply remove this. Also, in this example, we are adding COPY_MVN_SETTINGS_XML. This is a special scenario that would use a previously built settings.xml for your Maven settings, moving it from the install-resources folder to your built docker image.

Backend with Headless Accelerator

While there is an example that will install the HA CLI, HA doesn’t currently support a Maven build. This will be updated once the functionality is available.

Working with Multiple Servers

Coming Soon: currently, in the process of configuring this server architecture.

More Information

Here you will find clarification of configurations above.

Why add my local settings.xml?

The Magnolia org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.8:download mvn function used to generate a Maven project is not compatible with JDK 17, so if you try to generate the settings.xml file, it will fail. Until this is resolved, you can simply copy your local copy of settings.xml to the install-resources directory, and the mvn call will be ignored.

1. Extension is deprecated, but more stable than RedHat Community Server