Installation of Jahia on various platforms
To install Jahia:
- Download the latest stable Jahia installer build from the downloads by choosing the right downloadable package for your operating system.
- Double-click on the downloaded installation package to start the installation wizard.
- On Unix servers with a graphical environment, you can start the installation wizard by running
java -jar <your-downloaded-jahia-jar>.
- On Unix servers where you have no graphical environment, you can start the installation in Console Mode:
java -jar <your-downloaded-jahia-jar> -console
- If you need to run the wizard in Console Mode on Windows, open your command prompt with administrator privileges.
- Follow the installation wizard. See the Settings during installation section for a detailed description of install settings.
- At the end, you can let the wizard launch Jahia (if the bundled Apache Tomcat server was selected as an option). Otherwise, you can launch Jahia using the generated shortcut or within the created installation folder using a console window launch the command
./start.sh(on Linux/MacOSX) or
This section describes the settings that you define for your Jahia installation when you run the install wizard.
There shouldn’t be any spaces in your folder path. For example,
C:\Jahia-188.8.131.52\ is OK while
C:\Jahia 184.108.40.206\ is not.
Installation type – Discovery install
This option allows you to discover Jahia without a specific configuration thanks to the installation of an Apache Tomcat 9 server & Sun Java DB/Apache Derby DBMS bundle. The discovery install also provides and deploys all relevant and available modules, applications, and templates.
Default application server
The default Jahia version is distributed with an Apache Tomcat 9.0.x application server. No manual configuration of the server is required, as it will be directly setup during the Jahia installation. By default, Tomcat will use standard ports (
8005). Ensure that you do not have any other servers/services running and using those ports. Optionally, you can change Tomcat ports during the Custom Install installation type. For more information, see Installation type – Custom install.
Jahia installs with the embedded Sun Java DB/Apache Derby database engine with the Discovery install option. If you wish to get started rapidly, you can use the provided database as is. With the Custom Install option you can choose to install Jahia to another more robust standalone database during the configuration wizard of Jahia.
If you want to install Jahia on a custom environment (application server, database, mail server configuration, different port numbers), choose a particular operating mode (development, production, distant publication server), configure clustering or LDAP providers, you need to choose the “Custom Install” option.
The Jahia Enterprise Distribution can be installed with an Apache Tomcat 9.0.x application server. If you want to install into your own server, you need to deselect the Apache Tomcat checkbox in the installation wizard. On the next page, you can choose whether the installation is targeted into the Apache Tomcat 9.0.x application server (in case you want to deploy Jahia yourself into an existing Tomcat server other than the one bundled by default).
The installed Jahia will then include some specific configurations, which are needed to make it run smoothly in the targeted application server. See Application server specific installations for further information.
The embedded Sun Java DB/Apache Derby database engine, which is used with Discovery install option is not suited for production. During installation, you can choose between:
- Microsoft SQL Server
During installation, you provide the connection URL and the user/password for accessing the database.
You also can set whether binary data should be stored in the database or directly on a file system (for clustered Jahia setup the file system need to be shared by all cluster nodes). By default, the binary files are stored on the file system, which in most cases results in a better performance as the file content can be directly streamed from the file system (utilizing low level OS mechanism) and a higher level of concurrency can be achieved.
There is also an option present to define if the Jahia DB structure (tables, indexes, sequences) has to be created first.
Apache Tomcat configuration
This section is available only if you have chosen to use the bundled Tomcat application server. Here you have the possibility to configure the different ports used by Tomcat.
Web application settings
Here you have the possibility to specify the context path for Jahia Web application. If you want to deploy it into the root context (“/”), just leave the field blank.
Here you have to choose in which mode you want to install Jahia.
Enables Development mode for Jahia including access to Studio.
Development + Modules/JahiApps/Demos
Enables Development mode and includes the set of all optional modules, template sets and pre-packaged demo sites.
Includes the core set of Jahia modules. Disables development mode for template deployment. Studio mode access is also disabled.
Distant publication server
Enables Production but content editing activities are limited to the Live content only.
Just take care that even if you can switch later between the modes (you can reconfigure it in jahia.properties), some demo modules will be packaged only when you perform the installation in “Development + Modules/JahiApps/Demos” Mode. Installing in Production Mode, and then switching to Development Mode will activate the development dedicated features (like the Studio), but will not deploy the additional modules. You will have to deploy them using Module Management Panel in the Administration. Refer to Modules for more information.
Differences between Development and Production modes
The following table lists the differences in available features and Jahia behavior between the Development and Productions modes. From the packaged modules point of view, there are no differences between plain Development (not the second option, which is “Development + Modules/JahiApps/Demos”) and Production mode.
|Development mode||Production mode|
|Cache||Display extra information directly in the rendered page by passing request parameter “cacheinfo=true” in the page URL||n/a|
|Rendering||Display extra view/area rendering information by passing request parameter “moduleinfo=true” in the page URL||n/a|
|Error handling||Exception stacktraces are rendered in the error page. Additional (more verbose) error reporting using ErrorFileDumper in the rendering of views.||n/a|
|Rules||Watch for changes in rule files under <jahia-web-app-dir>/WEB-INF/etc/repository/rules and automatically rebuild the rule base||n/a|
|If a background job is scheduled from a Spring definition file, the job is recreated (all the job data is deleted) and rescheduled on each Jahia restart.||Spring-based configured jobs are never deleted. If the change is detected in the trigger configuration the job is re-scheduled on Jahia startup.|
|URL rewriting rules||Scanned for changes each 5 seconds. The rule base is reloaded if changes are detected.||No implicit scanning for changes.|
|Groovy patcher||Scans for new patches each 5 seconds and executes them.||Scan interval is configurable at is set to 5 minutes by default. Scanning can be disabled completely.|
If you use LDAP directory as a provider for application users and groups, you can choose to configure LDAP provider settings during installation. If you select this option, you setup your configuration for user and group providers in and additional screen. If you do not configure them during the install, you will still be able to do it later using configuration files or from the Jahia administration pages. See LDAP for more information.
You can also configure Jahia to be run in cluster mode. If you select this option, you will then access an additional screen where you can setup your cluster configuration. Here, you will have to specify if the node you are installing is the processing server. Remember that only one node of this type is allowed in the same cluster. See Clustering for more information.
You will also have to specify a unique server identifier (or leave the <auto> value for it to be auto-generated) and declare the IP and listening port.
System administrator settings
You need to at least provide the password for the root user, who, like a super-user, always has all of the privileges in Jahia. So, you should choose a strong password and keep it secret.
Mail server: this field contains the SMTP host name, with advanced options.
Jahia uses the Apache Camel framework for messaging. The format of the mail endpoint should conform to the endpoint required by the Camel Mail Component (http://camel.apache.org/mail.html), for example:
All parts except the host are optional. See use cases below.
Mail administrator: the field contains a single e-mail address or multiple addresses (separated by a comma) of users who will receive system-level notifications (for example, about errors if this option is enabled).
Mail from: the default sender e-mail address for an e-mail message.
Here are several use cases for "Mail server" field values:
- SMTP server does not require authentication and uses the standard port 25:
- SMTP server requires authentication and uses non-standard port 11019:
- GMail example: SMTP server requires authentication and SSL enabled (or TLS):
- Enable the mail server debugging option to see the details of e-mail server communication:
Installing silently from the command line
You can perform a silent install of Jahia from the command line. This can save you time if you install Jahia frequently, for example, if you often reinstall in a developer environment. To perform a silent install, you install Jahia using the install wizard and create an XML file from the wizard that contains your install settings. Then you run a command that points the XML install file and installs Jahia silently. You can also modify the XML file before installing, for example to update the install path or change database settings.
To create the install file:
- Run the install wizard and specify install settings that you want saved in the XML file.
- On the Installation Finished page in the install wizard, select Generate an automatic installation script.
- Navigate to a location to save the file, provide a file name and click Save.
To install Jahia silently:
Open a command prompt and navigate to the location of the install file. Run a command using the following syntax.
Jahia-installer-version-number.exeis the name of the Jahia installer.
install-filename.xmlis the name of the install file that you created.
For example, install Jahia 8.0.1 on Windows use the following command:
Install Jahia 8.0.1 on Mac using the following command:
java -jar Jahia-EnterpriseDistribution-8.0.1-r60669.4716.jar install.xml
Folder structure after installing with bundled Tomcat
The runtime data and main configuration files are by default located outside of the Jahia Web application. This allows for more clear separation of artifacts, better customization, production deployment and maintainability throughout the project lifecycle, including hotfixes and upgrades. We will reference further in this document the runtime data folder as digital-factory-data and the configuration folder as digital-factory-config. Here is a brief overview of the folders structure in Jahia along with the important files that will be used throughout this guide. The files and folders in the Web application (here under tomcat/webapps/ROOT) should be the same as what is on the other application servers. Note, please that some folders under digital-factory-data are created on demand (upon Jahia first startup).
<INSTALL_PATH> |-- digital-factory-config | |-- jahia | | |-- applicationcontext-custom.xml | | |-- jahia.properties | | |-- jahia.node.properties | | `-- license.xml |-- digital-factory-data | |-- bundles-deployed | |-- compiledRules | |-- db | | `-- sql | | `-- schema | |-- dbdata | |-- generated-resources | |-- imports | |-- karaf | | |-- data | | |-- deploy | | |-- etc | | |-- instances | |-- modules | |-- patches | | |-- groovy | | |-- sql | |-- prepackaged Sites | |-- repository | | |-- datastore | | |-- workspaces | | |-- indexing_configuration.xml | | |-- indexing_configuration_version.xml | |-- scripts | | `-- groovy |-- docs |-- icons |-- licences |-- logs |-- tomcat | |-- bin | | |-- catalina.bat | | |-- catalina.sh | | |-- setenv.bat | | |-- setenv.sh | | |-- shutdown.bat | | |-- shutdown.sh | | |-- startup.bat | | `-- startup.sh | |-- conf | | |-- catalina.properties | | |-- server.xml | | `-- web.xml | |-- lib | |-- logs | | |-- jahia-errors | | |-- jahia-threads | | |-- jahia.log | | |-- jahia_access.log | | `-- jahia_profiler.log | |-- temp | | |-- jahia-caches | | `-- jahia-jsps | |-- webapps | | `-- ROOT | | |-- css | | |-- engines | | |-- errors | | |-- gwt | | |-- icons | | |-- iphone | | |-- META-INF | | | `-- context.xml | | |-- tools | | `-- WEB-INF | | |-- classes | | |-- etc | | | |-- config | | | | |-- log4j2.xml | | | | `-- urlrewrite.xml | | | |-- repository | | | | |-- export | | | | |-- jackrabbit | | | | | |-- repository.xml | | | | |-- nodetypes | | | | |-- rules | | | | |-- root.xml | | | | |-- root-mail-server.xml | | | | |-- root-permissions.xml | | | | |-- root-roles.xml | | | | |-- root-user.xml | | | | |-- site.xml | | | | |-- template-root-mail-server.xml | | | | |-- template-root-user.xml | | | | `-- user.xml | | | `-- spring | | |-- lib | | |-- notifications | | `-- web.xml | |-- work |-- tools |-- uninstaller |-- OpenAdministration.URL |-- OpenHome.URL |-- start.bat |-- start.sh |-- stop.bat `-- stop.sh
Here is a brief overview of the important folders:
Contains Jahia configuration and license file under jahia sub-folder
Contains runtime Jahia data, including database creation scripts, modules and prepackaged sites to be deployed, JCR repository folder, and more
Contains all the bundles, corresponding to the deployed modules. Note: When restarting the server after flushing the contents of this folder, the modules present in the digital-factory-data/modules will be redeployed, but the other modules (uploaded via UI, REST API, downloaded from store) will not be redeployed and you must manually deploy them again.
Folder with the pre-compiled business rules, which are generated on module deployment and “cached” here.
The database scripts to create the DB schema of Jahia and to connect to the corresponding database can be found here.
The configuration and runtime data of the OSGi container (Apache Karaf).
Configuration files for the Apache Karaf OSGi container.
Modules and template-sets located in that directory will be deployed to the server on startup or whenever a file changes during runtime. Template-sets will be available in the drop-down list when you create a new virtual site, and modules will be seen in the left panel of the Studio or in Page Composer.
Includes Groovy-based patch scripts. The folder is also “watched” for the new scripts during runtime on the processing server to allow execution of patches during runtime.
Contains SQL scripts which are executed against database schema on Jahia startup.
The Jackrabbit repository home, where the workspace configuration, and version storage is located as well as search indexes.
The Jackrabbit datastore folder where the binary resources will be stored.
The search indexes are stored in these directories.
Contains pre-configured Apache Tomcat server
Folder where Jahia error dumper service writes error reports into.
Folder where Jahia thread dumper service writes thread dump files into.
This directory will contain complied JSPs of the Jahia modules. It will include both compiled class and Java file for each JSP. This can prove helpful in case you have an error in a template showing in the Tomcat logs, for instance: sitemap_jsp.java:984: illegal start of expression. If you want to make sure that all JSP files of the templates are recompiled after a change, you may want to delete the jahia-jsps directory and also the Standalone directory in work. Next time you access a page, Tomcat will recompile all JSP files used by the page.
Database connection information. This configuration is applicable only for Apache Tomcat server.
Besides some configuration files, here you will find mainly resource bundle files used to translate the Jahia interface in other languages. There are normally at least 2 files for each language: JahiaInternalResources.properties and JahiaTypesResources.properties.
The etc directory contains most of the configuration files of Jahia. The config sub-directory contains several configuration files (log4j2.xml, seo-urlrewrite.xml, etc.). The repository directory contains the configuration files for Jackrabbit repository. The spring directory may contain custom Spring bean definition files, but is empty by default. The internal Spring files are located inside jahia-impl-*.jar file.
The Jahia start and stop scripts.
Discovering Jahia - first usage
This applies only if you want to discover Jahia using the prepackaged demonstration site. It assumes that you have installed Jahia using “Discovery install” or selecting “Development + Modules/JahiApps/Demos” Mode, so that the example templates and the modules they require have been automatically deployed.
- Open a browser and go to http://localhost:8080/start.Use the root user credentials set up during the installation process. You will discover the new Jahia landing page. Click on the “Create new Web-Projects” button and you're ready to create your first site.
- Import the new “Digitall Prepackaged Demo Website” package. After successful import, click the Go to Page Composer button to see the editing interface for the Digitall Web site.
- Switch to Live mode.
Installing a production server – additional steps
This applies when you install your production server, and assumes that you have installed Jahia in Production Mode.
Before being able to create your first website, you will have to deploy your custom set of templates and modules. But during the development process, you may have used some Jahia standard modules, automatically available on your installation. Notice that most of those modules were available because you installed your development server using the development mode. As your production server uses the production mode, only the core modules will be available. So, you also need to deploy yourself the standard modules you want to use.
- Prepare all the JAR files for your custom templates and modules, and the one for each standard module you want to use. For the standard modules, you can either download them from the Jahia Private App Store (http://store.jahia.com/), or retrieve them from your development server (they are available in digital-factory-data/modules/). In case you download the modules from the Jahia Private App Store, take care to download the same version of the module as the one you have tested during your validation process.
- In order to deploy additional modules, you could use a dedicated screen in the Jahia installer, where you are offered to provider a folder to additional modules, which have to be deployed to the Jahia instance, you are installing. Alternatively, after the installation you could use Module management screen in Jahia Administration or manually copy the required modules to digital-factory-data/modules folder.
- The modules will be automatically deployed.
- Now you can either import your site data from an export of your integration/development platform, or create a new empty site.
- Now let your users enter content on their site.
Different types of environment
During the life-cycle of a project you will need different types of environments:
- Development environment
Each of your developers will have their own environment. Those developer environments are normally much lighter than the one needed for production. Your developers can either use the integrated DBMS (Apache Derby) or use another DBMS (MySQL, MariaDB, Microsoft SQL Server, PostgreSQL or Oracle).
- Integration environment
This environment will help you integrate the work of all your developers on the same platform and prepare the site(s) you are going to deploy in production.
- Production environment
This one is the last step in the development life-cycle of your project.
To deploy Jahia into an existing Apache Tomcat installation a number of required steps has to be completed. The following sections describe all those steps, which are all mandatory.
The installation procedure for an existing Apache Tomcat is as follows:
- Launch the Installer.
- Choose the
Custom Install (advanced)installation type.
- Select only
Jahia Core Platform + jContentpack, unselecting the
Add Apache Tomcatone
- On the next screen choose the
Apache Tomcat 9.0.xas the target application server
- Follow the next steps of the Installer.
Once the Installer is finished in your installation directory you should find among others the tomcat folder and, if the locations of runtime data and configuration folders were not changed during the installation, the digital-factory-config and digital-factory-data folders.
Further, it is assumed that your target Apache Tomcat server is installed in the
<tomcat> folder and <install-dir> will reference the folder, where you’ve installed Jahia into using the installer.
- Copy the content of the
<install-dir>/tomcat/libfolder into your
ROOTwas configured as the Web application context name, remove or rename the default Tomcat’s
ROOTWeb application at
<tomcat>/webapps/ROOTif it exists. For example, rename it to tomcat-root.
- Copy the content of the
<install-dir>/tomcat/webappsfolder into your
- The configuration folder path (
digital-factory-config) has to be added into the class path to make it available to Jahia. The easiest way is to modify the common.loader variable value in the
<tomcat>/conf/catalina.properties file to point to the
digital-factory-configfolder path. For example, if the Jahia configuration folder has a path
/opt/Jahia-8/digital-factory-configthan the value of common.loader should look like:
digital-factory-configfolder is inside the installation folder, you could use the path, relative to catalina.home, i.e.:
- Note, if you decide to move the
digital-factory-datafolder to other location, the
jahiaVarDiskPathvalue in the
digital-factory-config/jahia/jahia.propertiesfile should be adjusted to reflect its new path.
- Adjust the JVM and connector options appropriately (see the next JVM tuning options section).
The default JVM options of the Apache Tomcat must be adjusted to reflect the Jahia requirements. We recommend creating a setenv.bat (Windows) or setenv.sh (non-Windows OS) script in the <tomcat>/bin folder to put those options. An example of the
<tomcat>/bin/setenv.bat for Windows OS could be:
rem ------------------------------------------------------------------ rem Jahia settings rem ------------------------------------------------------------------ set CATALINA_OPTS=%CATALINA_OPTS% -server -Dsun.io.useCanonCaches=false -verbose:gc -XX:+HeapDumpOnOutOfMemoryError -XX:+PrintConcurrentLocks -Djava.net.preferIPv4Stack=true -Xms2048m -Xmx2048m set CATALINA_OPTS=%CATALINA_OPTS% -Dderby.system.home="%CATALINA_HOME%\..\digital-factory-data\dbdata"
In a similar way, the
<tomcat>/bin/setenv.sh script for a non-Windows OS can look like:
#!/bin/sh # -------------------------------------------------------------------- # Jahia settings # -------------------------------------------------------------------- CATALINA_OPTS="$CATALINA_OPTS -server -Djava.awt.headless=true -verbose:gc -XX:+HeapDumpOnOutOfMemoryError -XX:+PrintConcurrentLocks -Djava.net.preferIPv4Stack=true -Xms2048m -Xmx2048m" CATALINA_OPTS="$CATALINA_OPTS -Dderby.system.home=$CATALINA_HOME/../digital-factory-data/dbdata" export CATALINA_OPTS export CATALINA_PID=$CATALINA_HOME/temp/tomcat.pid
The JVM heap sizes (
-Xmx) should be adjusted according to your needs. Note that the minimal value of the
-Xmx value, required by Jahia is
2048m. If you have chosen Apache Derby as the target DBMS server during the installation, the value of the -Dderby.system.home in the setenv.bat/setenv.sh script should point to your
HTTP/AJP connector tuning options
The following configuration for the HTTP and AJP connectors (configured in the <tomcat>/conf/server.xml file) is recommended, which includes maximum threads and accept count configuration, compression of the response content etc.:
The Module section has been moved to a dedicated page: Module deployement