Build and Run Your Local Jive Customization

Version 5

    NOTE:  This document assumes you have Maven installed and configured, and that you have Maven: How To Create a New Maven Project, and that you have PostgreSQL installed.

     

    Create a Database

    The Jive instance will need to run against a database (Postgres by default), so you'll need to create one specific to your project.  When you created your project, a bootstrap jive_startup.xml was created in the project's /src/test/resources/jiveHome directory.  This file contains an entry pointing to a database, whose name defaults to that of the project that was created.  For example, if I named my project "someCustomer", the entry in the jive_startup.xml file will look like:

     

    jdbc:postgresql://localhost:5432/someCustomer

     

    We need to create the database before starting the server, or it will fail.  This can be done using a tool like PGAdmin 3, or in a terminal window using the following command:

     

    createdb -Upostgres someCustomer

     

    Your database is now created.  When we run through setup the first time the Jive instance is started, the database will be populated with tables and data.

     

    EAE Database (for instances 5.0 and up)

    It will also be necessary, for a Jive 5.0 instance, to run against an Enterprise Activity Engine (EAE) service.  Just run the following commands, substituting your project name for "someCustomer", like you did above, when creating the Jive database:

     

    createdb -Upostgres someCustomer-eae

     

    Build Your Project for the First Time

    Your custom project will consist of a custom WAR file, and possibly multiple Jive plugins (not required).  Your initial build will construct the WAR and JARs for each plugin in your project, though they won't be anything special because you likely haven't added any code to them.  What's special about your initial build, however, is that it performs some setup for your project.  Specifically, it will create your projects jiveHome directory, which the application uses as sort of a home base, to store temporary files, themes, etc.  The jiveHome directory is bootstrapped from/src/test/resources/jiveHome, and is placed in the project's root /target directory.  If the name of the directory sounds familiar, that's good, because that means you were paying attention in the previous section.  The jiveHome directory contains the jive_startup.xml file that contains the database connection information the app will need to connect to the Postgres database we just created.  It also contains a developer license file that is needed to run the Jive instance locally.

     

    NOTE: For Jive 7 projects, you will need to set up your system to use JDK 7.  It will not compile with Java 6.

     

    To run the initial build, from the project's root directory run:

     

    mvn clean install -Djive.setup=false

     

    Specifying the jive.setup property, tells Maven to apply "false" to any assets in the build containing a @jive.setup@ variable, which just happens to be the jive_startup.xml file.  The file is filtered when it is copied.

     

    Optionally, if you're creating a 5/6/7.0 instance, you can specify the which kind of license, internal or external, you want the app to use.  By default, an internal license is used.  Use of an internal vs. an external license will affect some default settings, as well as which default profile fields are available from the system.  You can only specify this once.  If you need to change which license the app uses, you'll need to wipe the database and set the app up again.  To specify which type of license to use, simply reference the appropriate profile (internal or external) in the above statement:

     

    mvn clean install -Djive.setup=false -P external

     

    If this is the first time you have run a Maven build, this will take a while, as Maven will be pulling all of the needed dependencies, both native and project-specific from Jive's Maven repository.  This will only happen once, as all the downloaded dependencies will be stored in your local Maven repository for future use.

     

    Subsequent builds should be done from the individual module that was changed (web, plugins, etc.) by running mvn clean package, which will repackage the only that particular module.  Running a build from the project root will result in a refreshing of the jive_startup.xml file and could cause changes to the file to be lost.

     

    Run the App

    To run the customized Jive instance, we use Cargo, which is a Mavenized Tomcat container.  Using a Maven command, we run a Cargo goal, which spawns a Tomcat instance, and deploys our custom WAR.  Since the command is a bit long, we have a couple of script files that take care of the command for you, and allow you spin up instances simply by executing the script by name.

     

    Local Search Instance (Optional for 6/7.0)

    To run the search server, you'll run the following command from the run-services project directory:

    ./search-start
    
    
    
    

    Also, you'll need to be sure to select the on-prem search service during setup, like this:

    Screen Shot 2012-11-06 at 8.11.52 AM.png

     

    Local EAE Instance (Optional for 5/6/7.0)

    You will first need to start up the EAE server locally, before starting the Jive instance, by executing the following command within the web (5.0) or run-services (6/7.0) project directory:

     

    ./eae-start

    Note that you may need to make the file executable before running it.

     

    Jive Instance

    In the web project directory, you will find the cargo-start file, whose contents are:

     

    mvn -Djive.devMode=true -Dcargo.wait=true -P int cargo:start

     

    This script will deploy the custom WAR to a Tomcat directory, start Cargo, and will run the Jive instance locally on port 8080.

     

    To execute the file, we'll first need to make it executable with:

     

    chmod 755 cargo*

     

    Then, execute it:

     

    ./cargo-start

     

    The server should start in about 20 seconds, displaying the following in the terminal window:

     

    [WARNING] [talledLocalContainer] INFO: Starting Coyote HTTP/1.1 on http-8080
    [INFO] [talledLocalContainer] Tomcat 6.x started on port [8080]
    [INFO] Press Ctrl-C to stop the container...
    
    
    
    

     

    Once you see the above text you'll be able to access your Jive instance with a web browser at http://localhost:8080. (For 4.x, http://localhost:8080/jive)

     

    The first time you access the instance, you will be required to run through the setup screens.  You should be able to accept the defaults or skip most pages.  Be sure to skip the last screen that allows for resetting the admin password.

     

    You will need to specify the EAE information on the setup screens, including the eaecore-someCustomer database for the activity database.

     

    Upon completion of the setup workflow, you'll need to stop your server and re-start.  To do that, just do a Ctrl+C in the same terminal window you used to start the server.  Sometimes, while after pressing Ctrl+C you get your command prompt back, the server is still not stopped, which will prevent the server from starting up again later, since a process will still be occupying port 8080.

     

    To get around this, download the attached kill-bootstrap.plx file, which will kill all running Java processes (don't worry...it won't kill the EAE or Eclipse), and place it in your /usr/local/bin folder.  You should also make sure that folder is in your path, so you can access it from anywhere.  To execute the script, just call it from the terminal window:

     

    $ kill-bootstrap.plx
    killed process 78209
    
    
    
    

     

    cargo-compile-exploded

    You might have noticed that there is another Cargo-related script in your project's /web directory, called cargo-compile-exploded.

     

    mvn compile war:exploded -P dev cargo:start

     

    This script starts the server, the same as cargo-start, but does it a bit differently, in that it does not deploy the custom WAR to Tomcat, but instead treats the directory used to create the custom WAR file as the deployed app.  No WARs are deployed or exploded by this script.

     

    So why use one over the other?  Well it depends on what kind of customization you're doing.  If your customization is restricted to a web overlay, cargo-compile-exploded is the way to go, as the feedback loop is considerably tighter since you don't have to deal with deployment of a WAR file.  If you are doing plugin development, cargo-start is preferred, since no WAR changes means no WAR deployments, and thus, no benefits.

     

    It should be noted that each file uses different Maven profile (-P int vs. -P dev).  This enables us to use different deployment options for each script.  That said, if configuration changes need to be made for an instance, it should be made for both profiles.

     

     

    Add Plugins

    Adding plugins to your Jive instance is easy.  In a UAT or production environment, you would do it using the admin console, and then restart the server.  You could do that locally, as well, but would take a wicked long time to get anything done.  When you install a plugin via the admin console, the uploaded plugin JAR file is stored in the database.  When the system is restarted, the plugin is retrieved, decoded, and exploded into memory for quick access.  That said, every time you do a plugin install, you have to restart your server.  That, plus multiple trips to the admin console to uninstall/install plugins, makes for a poor use of your time.

     

    Enter pluginDirs.

     

    Jive gives us the ability, when running in devMode, to load plugins into memory directly, at startup time, using the pluginDirs system property.  While this doesn't preclude you from having to restart the server in some cases, when making changes to the plugin, it's a lot more lightweight, definitely speeds up the development process.

     

    The preferred way to include the pluginDirs property is to modify your project's /web/pom.xml (henceforth known as the web pom) file.

     

    
    
    
    

     

    Simply uncomment the <pluginDirs> element and replace the value with the relative path to your plugin's exploded JAR directory.

     

    When you build a Jive plugin using the mvn clean package, a directory is created in the plugin's target directory that represents the exploded plugin JAR file, and will have a name like myPlugin-1.0-5.0.0.0 where 1.0 is the version of the plugin, and 5.0.0.0 is the Jive version the plugin was built against.  This is the directory you want to point to.  You'd change the entry to something like this:

     

    ${basedir}/../myplugin/target/myplugin-1.0-5.0.0.0

     

    If you want to specify multiple plugins, you can provide each of them in a comma-delimited string.

     

    Once that is set, run the project as you normally would.  You can verify that the plugins were properly loaded by checking the System-->Plugins tab in the admin console.  Note that, while you will see the plugins on this screen, you will not see them in the jivePlugin database table, since the use of pluginDirs just loads the plugins into memory.

     

     

    Making Changes

    How changes are incorporated into the running Jive instance depends on the kind of change:

     

    Web Overlay

    Java, Freemarker (not theme), Javascript, Spring and Struts changes require that the instance be stopped, the web module rebuilt (mvn clean package), and the server re-started, preferably usingcargo-compile-exploded.

     

    Themes

    Changes to themes, including Freemarker and CSS, will be reflected right away.  Just save the file and refresh the page in the browser.  This is made possible due to the <themes.directory>property passed to the Cargo configuration, which points at ${basedir}/src/main/themes.

     

    Plugins

    If your plugin is deployed via pluginDirs, Javascript, CSS and Freemarker changes can be deployed by rebuilding (mvn clean package) the plugin and refreshing the page in your browser.  No server restart is necessary.  Any Java, Struts, Spring, or plugin configuration changes will require a rebuild and a server restart.