Skip to end of metadata
Go to start of metadata

This is a document in progress. For a rough outline of the steps involved in packaging and deploying, see KULRICE-3675

Definitions and overview

A "distributed Rice package," or simply, a "distribution," is a compressed archive of one of three types (source, binary or server), which we make available to the general public via the Rice website at rice.kuali.org. A full "Rice distribution" consists of nine files: a source, binary and server package compressed in each of three different ways (zip, bzip2 and tarball). We upload these files to the server manually, via scp.

When you "deploy" Rice, you are dealing with Maven and a Maven repository, located at test.kuali.org/maven. We deploy each of Rice's component modules, as well as its parent POM, to a separate, version-specific directory within this repository using the mvn javadoc:jar source:jar -Dmaven.test.skip deploy command.

The binary and server distributions contain a database utility called ImpEx and the datasets necessary to begin running Rice.

Documentation Checklist

#

Task

Completed?

Comments

1

Create release notes

 

 

2

Update installation guide (it has version numbers in it)

 

 

3

Update acknowledgments page if there are new libraries added (or removed)

 

 

4

Generate an updated schema.html

 

 

5

Update the ERD if there are database changes

  • TODO: need to document how we create our ERDs and what tools to use, MySQL Workbench)

 

 

Pre-Packaging Checklist

Before you focus on packaging the various distributions, go over this checklist:

#

Task

Completed?

Comments

0

Ensure that the database upgrade scripts are up to date with final versions for both MySQL and Oracle.

 

 

1

Apply ECL licensing headers to project files (see Automated application of header for details).

 

 

2

Ensure that the bootstrap and demo dataset cleanup scripts are up to date based on the database changes made since the last version of Rice

  • these scripts are located under scripts/dataset

 

 

3

Make sure that the latest exports of all of the databases succeeded

  • we need to make sure that rice-cfg-dbs and friends are up to date with the latest copy of what's in the master databases
    • easy way to very this is to look at the SVN history for the appropriate rice-cfg-dbs branch
    • remenber however that the project will only be updated when changes have been made to the database

 

 

4

Update README.txt, NOTICE.txt and LICENSE.txt each release (if needed)

    • README.txt will always need to be updated for every release because it contains version numbers in it
    • NOTICE.txt will sometimes need to be updated if new libraries with new licenses have been added or if new partner schools have joined the project.
      • There is also a date at the top of NOTICE.txt that may need to be updated
      • This file is essentially a text version of the acknowledgements
    • LICENSE.txt will not need to be updated unless we have switched licenses (i.e. a newer version of the ECL)

 

 

5

Ensure that all unit tests are at 100% on both MySQL and Oracle

 

 

6

Update the <version> tag in the POM (change X.Y.Z-SNAPSHOT to simply X.Y.Z)

  • Use the prepare-new-version Ant script
  • This should update all the pom files and createproject.groovy, please verify that this is the case

 

 

7

Check to make sure that the servers (rice.kuali.org and test.kuali.org) have enough free space for the distros, docs, and maven deployments

  • rice.kuali.org is where distributions and documentation go
    • in /opt/www/drupal/contents/rice/downloads
    • approximate amount of space required is ?
      • run "df -h" command
  • test.kuali.org is where maven deployments go
    • in /usr/local/apache/htdocs/maven
    • approximate of space required is ?
      • run "df -h" command

 

 

8

Ensure that you are set up to be able to ssh to the target deployment machines

 

 

Packaging and Deployment Process

  1. Get clean, working copies of kul-cfg-dbs and the Rice version you want to distribute
  2. Edit the following values in $HOME/kuali-build.properties:
    • dist.database.password (should have value of RICEPACKAGING schema password)
    • dist.database.admin.user (administrative username for esdbk02)
    • dist.database.admin.password (administrative password for esdbk02)
    • dist.database.svn.base (the directory within the rice-cfg-dbs repository applicable to the release)
  3. Edit client-dataset-impex-build.properties and server-dataset-impex-build.properties such that the drivers.directory and drivers.file.pattern will include the MySQL and Oracle drivers in the classpath of the build process
  4. OutOfMemory errors are not fun! Make sure ant has enough memory allocated to finish:
    1. set ANT_OPTS=-Xms512m -Xmx1g (Windows)
    2. export ANT_OPTS="-Xms512m -Xmx1g" (ksh/bash)
    3. setenv ANT_OPTS "-Xms512m -Xmx1g" (tcsh/csh)
  5. Go to the root directory of the Rice project and run ant dist-all; this will create the binary, source and server packages.
    • This can take upwards of 1 hour to finish executing
  6. Copy the server and binary packages to a temporary directory, decompress the archives and any archived objects that they contain (eg the standalone war) in order to verify that the packages you created do not contain proprietary libraries
  7. Upload the binary, source and server distributions
    • upload to rice.kuali.org:/opt/www/drupal/contents/rice/downloads
    • there is a sub directory for each version under there
  8. Deploy the new version to the maven repository using mvn javadoc:jar source:jar -Dmaven.test.skip deploy.
  9. Run mvn -Dmaven.test.skip site-deploy to publish the javadocs to the website.

Post-Packaging Checklist

  1. Create a page in Confluence that will serve as a documentation "portal." (c.f. 1.0.1 documentation portal)
  2. Generate the doc-to-help documentation using the steps described here||\.
  3. Ensure that the generated distributions do not have the ojdbc14.jar file inside of them!

Additional TODOS for this distribution guide

  1. We should also include a description of what the process does (and how it uses the packaging database to stage everything)
    6) We should come up with a standard checklist of "QA" items that need to be dealt with every release so that we don't forget, some examples:

7) Bring over and update the documentation on the various rice distributions and what they include, need to figure out if this is already in readme files (which I think it is) because we don't want to duplicate it

  1. The maven site-deploy does not appear to be properly deploying javadocs, plus it's really really slow and has lots of errors, we should look into this

Setting up SCP

Set up scp using these steps:

  1. Generate a keypair using either PuTTYgen or keygen.
  2. Send the public key to the Kuali Configuration Manager so that it can be added to the authorized_keys file on the server you are connecting to.
  3. If one does not already exist, create a settings.xml file in your $HOME/.m2 directory (or %HOME%\.m2 in Windows).
  4. Add a servers section to it like so:
    For more information on this step, see https://test.kuali.org/confluence/x/EaM| | |