Overview

New Adopters are often confused about when they need to do an initportal, an initdb, a deploy-ear, or a deploy-war when they are incorporating changes from Apereo or upgrading versions.  This is especially true during early development when portlets are being added, layouts are changing, etc.  This page attempts to give some guidance to this question.  However this is a complicated question as it depends substantially on what the nature of the changes are.

Very general guidance

uPortal is a collection of web applications and the database information to support it.  What you build is dependent upon what is changed.  When in doubt on a dev or test system, you could always do an ant clean initportal to rebuild all webapps and init the db.  In fact, this is recommended.  It is a best practice to be able to get a system similar to production up and running using the command 'ant clean initportal'.

To choose to do one of the other things that build a more limited amount of the system, it depends upon the changes. The following are relevant to local, dev and test systems.  When you are on production (or a test system to prove out the production upgrade process), you typically wouldn't do initdb or initportal as these would impact the database and you'd lose your user's customizations.

Database changes

If there are database changes (in uportal-war/src/main/data), you would minimally do 

a) ant -Dmaven.test.skip=true initdb

the -Dmaven.test.skip=true skips running unit tests and is a little faster.  It doesn't hurt to run the unit tests and is good practice to insure everything is working.  However when doing repetitive development, it is often more efficient to skip running the unit tests to reduce development cycle time.

b) or you can use an ant command (see Import Export Data Migration Tools) or use the admin UI to import the specific xml files that changed. 

This allows you to avoid initializing the DB.  This is what you'd do on a running production system. 

To use an ant command, see Import Export Data Migration Tools. 

Using the admin UI you would go to the import/export section and import the specific xml file(s).  The admin UI is not great at indicating errors in the import processing the UI (errors are logged in portal/portal.log) so if you have hand-edited XML files or you don't get the results you expect, look in the portal.log file for error messages during the import process or fall back to use the ant commands where it displays the error in the command window until you get more familiar with the system or have proven the input files.  If you are importing files you had created from an export this is less of an issue, though you can run into issues importing files in the wrong order and having dependencies upon entities that are not present any longer.  Where you typically run into issues is with hand-edited xml files.

Code changes

1. If there are changes to uPortal (uportal-war folder), you would do an ant clean deploy-war

2. If there are changes to other portlets (directories other than uportal-war), or to filter files, rebuild all web applications/portlets by doing ant clean deploy-ear

If you are new to uPortal and you aren't as familiar with the system, it is helpful to always adding the 'clean' parameter to the ant build commands to delete all files in the target folders before doing the build.  There are situations where ant may not fully understand a dependency, such as changes to the property values in the filters folder affecting certain files, and think a file is up to date when it should be built.  To avoid confusion and frustration when you are new to uPortal, just add the clean to the ant command and you will always get consistent results.  When you are more familiar with the system and have an understanding of the changes that are made you can do more specific builds or steps that are short cuts and take less time.

Changes to both Database and Code

Depending upon the changes, you can do one of the two processes above individually.  On a local or dev system, it is generally easier to do an 'ant clean initportal' to get a stable system without having to spend time doing analysis of the changes.

Local or Dev systems

In summary on local or dev systems, especially when you are new, the easiest thing to do is:

1. typically do ant clean initportal

You can try looking at what has changed and determining if you want to try one of the shortcuts.  It is certainly a good learning process.  However especially if you are a new adopter if it doesn't work, fall back to the ant clean initportal rather than spending time trying to understand the details (unless you are working on processes you'll use later in a production upgrade).

2. add 'clean' to the ant initportal, deploy-ear, and deploy-war commands

Test and Prod systems

1. Do not use initportal or initdb.  Assuming you have exported your prod configuration and saved it in your source code repository (in the uportal-war/src/main/data folder), you'll want to look at the changes you are incorporating in this release and update your data folder with the appropriate changes.  Then you would update the database by importing the specific XML file changes in the appropriate order that matches the order an initdb would use.

2. The code can safely be replaced with an ant clean deploy-ear.  It's more efficient to stop Tomcat prior to running the command.  Otherwise Tomcat will spend much time unloading and reloading webapps when the portlets and uPortal are being deployed to Tomcat.

3. Restart Tomcat to pick up the changes.  This will insure that data in uPortal's caches will be purged and reloaded from the database.