Installation

In this section we will go through the prerequisites needed for Magnolia Headless Accelerator (HA).

To use Headless Accelerator you must install Node.js version 14 or higher, Java, Git, and Yarn on your device. If you have all of those already, go directly to the installation of Magnolia CLI.

1. Install Node.js#

To see if you already have Node.js installed and check the installed version, run the following commands:

node -v

info

The recommended version of Node is 16, unless you're using the project template with Magnolia and SFCC integration, in which case you need to use version 14.

If you don't have Node.js installed or it is not version 16 (or 14 for the SFCC project template), please follow these instructions.

Ubuntu
Mac/Linux
Windows

sudo apt-get update -ysudo apt-get upgrade -ycurl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash –sudo apt-get install nodejs

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bashexport NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completionnvm install 14nvm alias default 14

Node Version Manager (NVM) allows you to install and switch between multiple versions of Node.js and npm on your system.

Download the latest Windows NVM (nvm-setup.zip) from https://github.com/coreybutler/nvm-windows/releases
Extract the zip file and run the installer.
Open a terminal and run:

nvm install 14nvm alias default 14

Node Version Manager (NVM) allows you to install and switch between multiple versions of Node.js and npm on your system.

2. Install Java#

You need to have Java installed on your system to run Magnolia. Make sure to use the version of Java supported by Magnolia. Check the the Magnolia Certified Stack for up-to-date information.

As of February 2022 supported versions of Java are Java 16 (supported by Magnolia 6.2.9+), Java 11 and Java 8.

Run this command to see the Java version installed:

java -version

If you do not have this setup already, please do the following:

Ubuntu
Mac/Linux/Windows
Apple ARM M1 CPU

sudo apt install openjdk-11-jre-headless -yecho "export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64" >> ~/.bashrcecho "export PATH=$PATH:$JAVA_HOME/bin" >> ~/.bashrc

Go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html, download according to your platform.

caution

Make sure you're using ARM compatible JDK when using Macbook M1 with the new Apple CPU.

info

Additionally, SDKMAN! can be used to install the specific version of Java required by Magnolia, providing easy Java version management.

3. Setup Git#

You can check if Git is installed on your device by running git --version. To configure your Git environment run:

git config --global user.name "My Name"git config --global user.email my.name@my-company.com

If you don't have Git installed, you can find the installation bundles here: https://git-scm.com/downloads.

4. Install Yarn#

If you haven't installed Yarn, run:

Linux
Mac/Windows

sudo npm i -g yarn

npm i -g yarn

5. Install the Headless Accelerator Wrapper#

Begin by installing the HA CLI wrapper. This package facilitates the connection to our private repository, ensuring a seamless installation and updating the CLI.

Linux
Mac/Windows

sudo npm install @magnolia/ha-cli -g

npm install @magnolia/ha-cli -g

6. Install the Headless Accelerator CLI#

Nexus credentials are needed in order to setup the .npmrc file and install the HA CLI from the private repository.

Setup the global .npmrc file#

Before you access the private repository, you need to configure your global .npmrc file.

Replace <NEXUS_USER_TOKEN> with your actual Nexus user token. To access your user token, you need to validate your credentials again. Use a token designed for the base64 representation of "user:password".

Run the following commands:

Mac/Linux
Windows

echo "@magnolia-dx:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> ~/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:always-auth=true" >> ~/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:_auth=<NEXUS_USER_TOKEN>" >> ~/.npmrcecho "@magnolia-ea:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> ~/.npmrc

echo "@magnolia-dx:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> %USERPROFILE%/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:always-auth=true" >> %USERPROFILE%/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:_auth=<NEXUS_USER_TOKEN>" >> %USERPROFILE%/.npmrcecho "@magnolia-ea:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> %USERPROFILE%/.npmrc

Install the CLI#

After setting up the global .npmrc file, you have access to the private @magnolia-dx and @magnolia-ea repository, and can install the HA CLI.

npm install -g @magnolia-dx/ha-cli

Now you can check the version of HA CLI by running ha --version. HA CLI should be the latest version.

Check the release notes to get more information about the current version.

Once this is done, you can use the full HA CLI functionality.

If you run HA in a CI Environment , you can copy your access token to MGNL_HA_AUTH_TOKEN environment variable. If the HA command finds this variable it will not prompt for username and password authentication.

info

Always make sure to have the latest version of the HA CLI. Update to the current version of the HA CLI if needed.

7. (Optional) Install Web components#

You can use UXF Web components to speed up your development process.

npm install @magnolia-ea/uxf-core

Congratulation!

You successfully installed all of the prerequisites.

Now you're ready to jumpstart your Headless project with Magnolia Headless Accelerator!

Troubleshooting#

Mac users with Apple silicon#

If you encounter compatibility issues with specific x86-based Java applications, you may consider enabling Rosetta. Refer to Apple's documentation for instructions on enabling Rosetta if required.