Installing Magnolia

This page instructs you on installing Magnolia on your machine. This could be your own laptop for local development-purposes, a beta-testing environment, or even as part of a pipeline for production. As an alternative to the instructions here, you can use the Magnolia CLI to install and start Magnolia.

Production installs

If you are installing Magnolia for production purposes, there is typically additional installation, configuration steps, and testing phases that are not mentioned in this guide. You should consult with your operations and security team to prepare for a full production environment.

For more details, see Modifying the magnolia.home property as a starting point.

Get Java

Magnolia needs at least a Java Runtime Environment (JRE) to run. Check if there’s a version of Java already installed on your computer by opening the terminal or command prompt and typing java -version. If the system reports a version number, Java is installed on your computer.

See Certified stack to confirm that the version installed is supported.

For local development, use 17.0.12-zulu. Example installation using SDKMAN:

sdk install java 17.0.12-zulu

Windows
Mac
Linux

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.

JRE is for users who run Java programs on their computers.
JDK is for developers who write Java-based applications.

Download and install JDK. By default, JDK is installed at C:\Program Files\Java\jdk-<version>\.

Instructions

Check for JAVA_HOME

Open the command prompt.
Type set and press ENTER.
Find JAVA_HOME in the command output and verify that the path points to your JDK installation directory, for example, C:\Program Files\Java\jdk-<version>>.xx.
If JAVA_HOME is missing or it points to the wrong directory, see Set JAVA_HOME.

Set JAVA_HOME

Open the Command Prompt as an administrator.
Set the path for JAVA_HOME.
```
setx /m JAVA_HOME "path\to\Java\jdk" (1)
```
1 Where path\to\Java\jdk is where your Java Development Kit is saved.

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

For Mac, you need to download or update to Java 17 or higher. After reviewing and agreeing to the terms of the license agreement, download the file, then double-click it to launch the installation wizard and follow the installation instructions.

The installation directory varies from one Linux system to another. On Debian-based distributions, JREs or JDKs are usually installed in /usr/lib/jvm/.

Download Magnolia

Download Magnolia.
Magnolia Community Edition

Magnolia Community Edition software is distributed free-of-charge and without any warranty under the terms of the GNU General Public License (version 3), a license that permits you to redistribute and modify the software under certain terms and conditions. It is important that you read the license to understand your rights and obligations.
- Other downloads
Extract the zip file to your preferred directory on your machine.

Zip structure and storage
magnolia-x.y/ ├── add-ons/ └── apache-tomcat-x.y/ ├── bin/ ├── conf/ ├── lib/ ├── logs/ ├── temp/ ├── webapps/ | ├── magnoliaAuthor/ | ├── magnoliaPublic/ | └── ROOT/ └── work/
Example storage location

C:\Users\<username>\magnolia.

If you are installing Magnolia for personal use, extract the zip to /home/<your account> or equivalent directory.

If you are installing onto a production server, extract the zip to /usr/local or /opt. A standard user account may not have permissions to extract files into a target directory such as /opt. If this is the case:
1. Extract the zip in the folder where you downloaded it.
2. Open a terminal and move the extracted folder using your ROOT admin command such as sudo mv magnolia-x.y.
  
  The sudo command executes the mv (move) command as superuser, prompting you for a password.

Start Magnolia

Go to the magnolia-x.y/apache-tomcat-x.y/bin directory and run:

./magnolia_control.sh start --ignore-open-files-limit (1)

1	If you get an error due to a low `max open files` limit, try executing the command with the `--ignore-open-files-limit` option:

OS-specific instructions

Windows
Mac OS
Linux
Solaris

Open your Command Prompt.
Go to your Magnolia installation directory.
```
cd path\magnolia-x.y\apache-tomcat\bin
```

Run magnolia_control.bat start.

./magnolia_control.sh start && tail -f ../logs/catalina.out (1)

Magnolia reports startup information in a new Tomcat window. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms.

To stop Magnolia, type CTRL + C, then ./magnolia_control.bat stop and press ENTER.

Open your terminal.

Go to your Magnolia installation directory

cd /Applications/magnolia-x.y/apache-tomcat/bin

Start Magnolia.

./magnolia_control.sh start && tail -f ../logs/catalina.out (1)

1	The first part of the startup command `./magnolia_control.sh start` launches Magnolia. The second part `&& tail -f ../logs/catalina.out` displays log messages written to `/apache-tomcat/logs/catalina.out` log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms.

To stop Magnolia, type CTRL + C, then ./magnolia_control.sh stop and press RETURN.

Open your terminal.
Go to your Magnolia installation directory.
```
cd /path/to/magnolia-x.y/apache-tomcat/bin
```

Start Magnolia:

./magnolia_control.sh start && tail -f ../logs/catalina.out (1)

1	The first part of the startup command `./magnolia_control.sh start` launches Magnolia. The appended part `tail -f ../logs/catalina.out` displays log messages written to `/apache-tomcat/logs/catalina.out` log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms.

To stop Magnolia, type CTRL + C, then ./magnolia_control.sh stop and press ENTER.

Open your terminal.

Go to your Magnolia installation directory.

cd /home/userAccount/magnolia-x.y/apache-tomcat/bin

Start Magnolia.

./magnolia_control.sh start && tail -f ../logs/catalina.out (1)

1	The first part of the startup command `./magnolia_control.sh start` launches Magnolia. The second part `&& tail -f ../logs/catalina.out` displays log messages written to `/apache-tomcat/logs/catalina.out` log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms.

To stop Magnolia, type CTRL + C, then ./magnolia_control.sh stop and press ENTER.

Run web update

After installing and starting Magnolia, you need to run a web update.

Open a browser and go to http://localhost:8080.
Click Run the Web update on the author instance, then Start installation.
Click Run the Web update on the public instance, then Start installation.
Magnolia installs its modules.
When the installation is complete, click Start up Magnolia on both.