Many of us have experienced it, you go to deploy a new application into your portal instance and see the dreaded deployment error messages. What do you do? Is the error message helpful? How can I find the solution?

If you're experiencing deployment problems with deploying a JSF portlet on Liferay, there's a simple process you can follow to solve your deployment issues. Instead of trying to figure out what's wrong with your code, it's sometimes easier to compare your portlet to a working example. The strategy/tutorial below creates a working example to compare your project to. This strategy is recommended by our Liferay Faces experts.

For the following steps, we assume someone is using a JBoss server. However, these fundamental steps can be followed for any app server. Here they are:

1. Download a Liferay+JBoss bundle
2. Determine the correct version of Liferay Faces: Liferay Faces Version Scheme
3. Follow the instructions to upgrade Mojarra: For JBoss or for other app servers
4. Follow the instructions to upgrade Weld: For JBoss or for other app servers
5. Follow the instructions for Building Liferay Faces From Source
6. Build the jsf2-portlet (from liferay-faces on Github) using theJBoss profile and deploy it to the Liferay+JBoss bundle:

            cd liferay-faces/demos/bridge/jsf2-portlet
            mvn -P jboss clean package
            cp target/jsf2-portlet*.war $LIFERAY_HOME/deploy

    7. Build the primefaces4-portlet (from liferay-faces on Github) using the JBoss profile and deploy it to the Liferay+JBoss bundle:

            cd liferay-faces/demos/bridge/primefaces4-portlet
            mvn -P jboss clean package
            cp target/primefaces4-portlet*.war $LIFERAY_HOME/deploy

    8. Examine the working example WARs and find out how they are different from the WARs that you are having trouble deploying. Typically it is a problem with dependencies. For example, you might be including portal-service.jar inside of WEB-INF/lib which could cause a ClassCastException.

This specific Liferay Faces troubleshooting tutorial is currently being migrated into Liferay's documentation. I'll post the link to the official tutorial to this post, once it's complete. Hope this helps!