Hot Deploy Troubleshooting
This article needs updating. For more information, see Wiki - Need Updating.
Sometimes for various reasons plugins fail to install. There are different reasons for this based on several factors, including
- Liferay configuration
- The container upon which Liferay is running
- Changing the configuration options in multiple places
- How Liferay is being launched
You will often be able to tell if you have a plugin deployment problem by looking at the Liferay server console. If you see the plugin get recognized by the hot deploy listener, you will see a plugin copied successfully message. If this message is not followed up by a plugin registered successfully message, you have an issue with your plugin deployment configuration, and it is likely one of the factors above.
Liferay Configuration Issues#
Liferay by default comes as a bundle or as a .war file. Though every effort has been made to make the .war file as generic as possible, sometimes the default settings are inappropriate for the container upon which Liferay is running.
There is a property called auto.deploy.dest.dir that defines the folder where plugins are deployed after the hot deploy utilities have finished preparing them. This folder maps to a folder that the container defines as an auto-deploy or a hot deploy folder. By default, this property is set to ../webapps. This default value works for Tomcat containers, but will not work for other containers that define their hot deploy folders in a different place.
For example, Glassfish defines the hot deploy folder as a folder called autodeploy inside of the domain folder in which your server is running. By default, this is in <Glassfish Home>/domains/domain1/autodeploy. JBoss defines the hot deploy folder as a root folder inside of the particular server configuration you are using. By default, this is in <JBoss Home>/server/default/deploy. WebLogic defines this folder inside of the domain directory. By default, this is in <Bea Home>/user_projects/domains/<domain name>/autodeploy.
You will first need to determine where the hot deploy folder is for the container you are running. Consult your product documentation for this. Once you have this value, there are two places in which you can set it: the portal-ext.properties file and in the Plugin Installer portlet.
To change this setting in the portal-ext.properties file, browse to where Liferay was deployed in your application server. Inside of this folder should be a WEB-INF/classes folder. Here you will find the portal-ext.properties file. Open this file in a text editor and look for the property auto.deploy.dest.dir. If it does not appear in the file, you can add it. The safest way to set this property--as we will see later--is to define the property using an absolute path from the root of your file system to your application server's hot deploy folder. For example, if you are using Glassfish, and you have the server installed in /java/glassfish, your auto.deploy.dest.dir property would look like the following:
Remember, if you are on a Windows system, use forward slashes instead of back slashes, like so:
Save the file and then restart your container. Now plugins should install correctly.
If you would rather change this setting via the Plugin Installer portlet (because you do not wish to restart your container), you can do that by clicking on the Configuration tab. On this page are a number of settings you can change, including the default folders for hot deploy, where Liferay should look for plugin repositories, and so on.
The setting to change is the field marked Destination Directory. Change this to the full path to your container's auto deploy folder from the root of your file system. When you are finished, click the Save button at the bottom of the form. The setting will now take effect without your having to restart your container.
Note that the setting in the portlet overrides the setting in the properties file.
The Container Upon Which Liferay Is Running#
There are some containers, such as Oracle Application Server and WebSphere®, which do not define a hot deploy folder. Unfortunately, these containers do not work with Liferay's hot deploy system. But this does not mean that you cannot install plugins on these containers. Some users have had success deploying plugins manually using the application server's deployment tools. On some containers, Liferay is able to pick up the portlet plugins once they get deployed to the container manually, especially if you add it to the same Enterprise Application project that was created for Liferay.
Changing the Configuration Options in Multiple Places#
Sometimes, especially during development when several people have administrative access to the server at the same time, the auto deploy folder location can get customized in both the portal-ext.properties file and in the Plugin Installer portlet. If this happens, the value in the Plugin Installer takes precedence over the value in the properties file. If you go into the Plugin Installer and change the value to the correct setting, plugin deployment will start working again.
How Liferay Is Being Launched#
The default value of the hot deploy destination directory is a relative path (e.g., ../webapps or ../server/default/deploy). This path is relative to the folder from which the application server is normally launched.
The start up and shut down scripts are in the bin folder. So to start Tomcat, you would normally go into the bin folder to run the startup script which starts Liferay running in Tomcat.
Tomcat's hot deploy folder is the webapps folder. This folder is on the same level the bin folder is on. If you are at the command prompt inside of the bin folder (where you started Tomcat), to get to a file in the hot deploy folder you would reference it by using two dots to go back up one folder, and then the path separator (/), and then the name of the folder (webapps). So in the default configuration, the hot deploy destination directory is relative to the folder from which the application server was launched.
If you are launching your application server from another script--perhaps as part of a cron job--and your script does not enter the folder the application server's startup scripts are in (in this case, <Tomcat Home>/bin), the relative path that is set by default will not work. Instead, the path will be relative to the path from which you launched the startup script. This will cause Liferay to create--in the Tomcat example--a webapps folder one folder up from where the startup script was launched. Since this is not the correct hot deploy folder for your application server, you will see the copied successfully message in the server console, but you will never see the registered successfully message.
To fix this, you can do one of two things: 1) Change the relative path to an absolute path as recommended above; or 2) Change the way you launch Liferay by making sure you go into the folder where the application server's startup scripts are before you launch them. Either one of these methods should fix your hot deploy problem and will result in the successful deployment of portlet and theme plugins.