To install Jahia:
java -jar <your-downloaded-jahia-jar>
.java -jar <your-downloaded-jahia-jar> -console
./start.sh
(on Linux/MacOSX) or start.bat
(on Windows).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-8.0.1.2\
is OK while C:\Jahia 8.0.1.2\
is not.
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.
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 (8080
, 8009
and 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:
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.
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.
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.
Development
Development + Modules/JahiApps/Demos
Production
Distant publication server
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.
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 | |
---|---|---|
Studio | Yes | Not accessible |
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 |
Job scheduling
(from Spring) |
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.
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:
[smtp|smtps]://[username@]host[:port][?options]
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.acme.com
smtp.acme.com:11019?username=myuser&password=secretpassword
smtps://smtp.gmail.com?username=acme@gmail.com&password=mypassword
or
smtp.gmail.com:587?username=acme@gmail.com&password=mypassword&mail.smtp.starttls.enable=true
smtp.acme.com?mail.debug=true
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:
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.exe install-filename.xml
Where
Jahia-installer-version-number.exe
is the name of the Jahia installer.install-filename.xml
is the name of the install file that you created.For example, install Jahia 8.0.1 on Windows use the following command:
Jahia-EnterpriseDistribution-8.0.1.0-r60669.4716.exe install.xml
Install Jahia 8.0.1 on Mac using the following command:
java -jar Jahia-EnterpriseDistribution-8.0.1-r60669.4716.jar install.xml
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:
digital-factory-config/
digital-factory-data/
digital-factory-data/bundles-deployed
digital-factory-data/compiledRules
digital-factory-data/db
digital-factory-data/generated-resources
digital-factory-data/karaf
digital-factory-data/karaf/etc
digital-factory-data/modules
digital-factory-data/patches/groovy
digital-factory-data/patches/sql
digital-factory-data/repository
digital-factory-data/repository/datastore
digital-factory-data/repository/index
and digital-factory-data/repository/workspaces/*/index
tomcat/
tomcat/logs/jahia-errors
tomcat/logs/jahia-threads
tomcat/temp/jahia-jsps
tomcat/webapps/ROOT/engines
tomcat/webapps/ROOT/META-INF/context.xml
tomcat/webapps/ROOT/WEB-INF/classes
tomcat/webapps/ROOT/WEB-INF/etc
start.*/stop.*
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.
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.
During the life-cycle of a project you will need different types of environments:
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:
Custom Install (advanced)
installation type.Jahia Core Platform + jContent
pack, unselecting the Add Apache Tomcat
oneApache Tomcat 9.0.x
as the target application serverOnce 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.
<install-dir>/tomcat/lib
folder into your <tomcat>/lib
directory.ROOT
was configured as the Web application context name, remove or rename the default Tomcat’s ROOT
Web application at <tomcat>/webapps/ROOT
if it exists. For example, rename it to tomcat-root.<install-dir>/tomcat/webapps
folder into your <tomcat>/webapps
directory.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.propertie
s file to point to the digital-factory-config
folder path. For example, if the Jahia configuration folder has a path /opt/Jahia-8/digital-factory-config
than the value of common.loader should look like:
common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar","/opt/
Jahia-877/digital-factory-config"
If your digital-factory-config
folder is inside the installation folder, you could use the path, relative to catalina.home, i.e.:
common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar","${catalina.home}/../digital-factory-config"
digital-factory-data
folder to other location, the jahiaVarDiskPath
value in the digital-factory-config/jahia/jahia.properties
file should be adjusted to reflect its new path.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 (-Xms
and -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 digital-factory-data/dbdata
folder.
The following configuration for the HTTP and AJP connectors (configured in the <tomcat>/conf/server.xml file) is recommended[1], which includes maximum threads and accept count configuration, compression of the response content etc.:
<Connector port="8080"
protocol="HTTP/1.1"
redirectPort="8443"
maxThreads="300" acceptCount="100"
compression="on"
compressibleMimeType="text/plain,text/html,text/xml,text/css,text/javascript,application/x-javascript,application/javascript,application/json,application/xml" />
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443"
connectionTimeout="20000" keepAliveTimeout="300000" maxThreads="300" />
Modules are extensions to Jahia, which are packaged as JAR files and can be deployed on a server. A module can contain different kinds of resources: JSPs, definitions in CND files, CSS and images, resource bundles, XML or ZIP import files, rules definitions, libraries, Spring files etc. Modules are deployed by using the built-in module management screen in the server administration, using REST API (with supplied command line scripts) or by dropping them into the digital-factory-data/modules folder. When deploying several new versions of modules, it is advised to use the REST API (see Installing multiple modules) as it comes with an optimization regarding dependency resolutions: a single bundle refresh is performed internally at the end.
The module management UI contains an explicit checkbox for starting or not a module, uploaded via that UI, as well as a similar checkbox for the modules, downloaded from private app store.
For more information about the module management UI, see Managing modules.
Jahia provides a REST API for module management, as well as corresponding command line scripts in the Jahia installation folder (in a default installation they are located in the <jahia-install-dir>/tools folder). Examples of usage of such scripts are listed below.
./installBundle.sh article-2.0.2.jar true
Installs the specified file as a module and starts it after the installation. if last parameter (true) is omitted, the module is just installed, but not started automatically.
./installBundles.sh article-2.0.2.jar faq-2.0.2.jar --start
Installs the specified files as modules and starts them after the installation. if last parameter (--start) is omitted, the modules are just installed, but not started automatically.
./startBundle.sh org.jahia.modules/article/2.0.2
Starts the article module version 2.0.2. The org.jahia.modules/article/2.0.2 is a full module key in this case, which is composed like <groupId>/<artifactId>/<version>
string. The start/stop/ uninstall commands can operate on a full module key as well as on a short one, like article/2.0.2 or event article, if the corresponding bundle can be resolved by that key unambiguously, for example if there is only one bundle with symbolic name article installed on your Jahia instance. The shorter form will be:
./startBundle.sh article
./stopBundle.sh org.jahia.modules/article/2.0.2
Or in a shorter form:
./stopBundle.sh article
This command stops the target article module.
./uninstallBundle.sh org.jahia.modules/article/2.0.2
And the shorter form:
./uninstallBundle.sh article
Uninstalls the target article module from your Jahia instance.
./getLocalBundleInfo.sh article/2.0.2
Get current local info about a single bundle.
./getLocalBundleInfo.sh article/2.0.2 jline/2.14.2
Get current local info about multiples bundles.
./getLocalBundleInfo.sh article/*
Gut current info about all versions of a bundle
./getLocalBundleInfo.sh org.jahia.modules/*/*
Get current info about all modules and their versions, having group ID org.jahia.modules
./getLocalBundleInfo.sh *
Get current info about all bundles
./getBundleInfo.sh article/2.0.2
Get current info about a single bundle.
./getBundleInfo.sh article/2.0.2 jline/2.14.2
Get current info about multiples bundles.
./getBundleInfo.sh article/*
Get current info about all versions of a bundle
./getBundleInfo.sh org.jahia.modules/*/*
Get current info about all modules and their versions, having group ID org.jahia.modules
./getBundleInfo.sh *
Get current info about all bundles
The following is available
./refreshBundle.sh org.jahia.modules/article/2.0.2
And the shorter form:
./refreshBundle.sh article/2.0.2
Refreshes the target article module from your Jahia instance.
The following is available
./updateBundle.sh org.jahia.modules/article/2.0.2
And the shorter form:
./updateBundle.sh article/2.0.2
Updates the target article module from your Jahia instance.
The deployment of modules can also be done by dropping them into the digital-factory-data/modules folder. This folder is “watched” for changes (new modules are dropped, existing modified or deleted) and actions are performed by Jahia to react on those changes. The folder supports module operations in “hot” (online, while Jahia is running) as well as in “cold” (offline, when Jahia is shut down) mode. If a new module is dropped into that folder, it is by default automatically started if Jahia is running in development operating mode (“operatingMode” flag value in jahia.properties file) or just installed without auto-starting it in case of other operating modes (say, “production”). If needed, the behavior can be explicitly controlled by adding the following flag into jahia.properties (or your own jahia.custom.properties) file:
jahia.modules.fileinstall.bundles.new.start=true
Supported values are true or false.
We rely on OSGI capability mechanism to define the dependencies between modules.
An OSGI bundle, so a Jahia module, can be started if all its dependencies (OSGI bundles that provides the required capabilities) are resolved.
The import and definition registering is done at resolve state.
At startup, a Jahia module if necessary:
We provide several mechanisms to make the module start whatever the order the modules are deployed.
jahia-depends
defines the required modules to be resolved. It also defines, in case of multiple modules deployed at once, the order to start them. Copying several modules at once in the /modules directory work as each module deployed one by one, so we cannot compute the order of deployment, this can lead to inconsistencies while the modules are starting, but should be solved automatically at the end.Jahia includes a built-in clustered module management support. All module operations, performed via Module management UI (in Server Settings) or via REST API/command-line scripts on any node and also including module deployments/undeployments via the /modules folder, are automatically replayed on other nodes in the cluster, so the state of bundles should be consistent across all nodes in the cluster. When a cluster node is joining the cluster it “pulls” the bundle state from the cluster and “applies” it locally. So, the module operations, listed in Module deployment, are cluster-wide (for example, a module deployed on any node of the cluster will be automatically deployed on the other nodes).
Be aware that direct bundle operations performed via Java code (on BundleContext or Bundle instances) any custom scripts, OSGi Web Console ,or SSH Console (except clustered commands under cluster:* group), are only effective locally, until the next cluster-wide operation is performed which synchronizes the cluster state in any case. Note that when a module is deployed in cluster it becomes “available” only after its deployment has been successfully completed by a Jahia processing node. For information and troubleshooting you could refer to a SSH console and “cluster:*” group of commands.
The following command:
cluster:bundle-list default
shows the clustered state of bundles in the default group – the global cluster group, which includes all nodes. This command has a shortcut alias:
clb
which does the same. Here is the sample snapshot of the output of this command:
In case of bundle state desynchronization in cluster, for example due to a cluster split (network partition) or other issues, it could be required to force synchronization of cluster state for bundles:
cluster:sync –bundle
or for all resources (bundles, config, features):
cluster:sync
Starting a new version of a module can take some time (from several seconds to few minutes), depending on its complexity, which will make the module unavailable during this operation, as well as the modules depending on it. This can be even more problematic when it involves a template set module: the consequence will be the unavailability of the sites using this template set during the start operation. The steps explaining how to perform a module deployment in a cluster with limited downtime are described in the "Module version update with limited downtime" procedure.
You can undeploy your modules using REST API (or corresponding uninstallBundle.sh command-line script). Alternatively, you can undeploy the modules from the Administration>Server>System Components>Modules. The advantage of doing so using the UI approach is that Jahia will inform you of any modules that might depend on the one you're trying to undeploy and will first ask you to disable the module from all the sites that might be using it. Module undeployment in both cases is a cluster-wide operation as described in Cluster deployment.
Once the JAR file has been deployed, modules become available. They can then be deployed to Web projects via module management screen in Server Settings or via Studio. If a new version of the module is uploaded on the server, it will be automatically deployed on all sites that are currently using it. All updates will be immediately available in the site.
digital-factory-data/dbdata
folder