Upgrading - Documentation - Jive Software by yaoyufang

VIEWS: 0 PAGES: 9

									Upgrading
                                                                                                                                                                                 | TOC | 2




Contents
  Upgrading......................................................................................................................................... 3
           Before You Upgrade............................................................................................................................................. 3
                  Back Up Your jiveHome Directory...........................................................................................................3
                  Back Up Your Database............................................................................................................................ 3
                  Remove Plugins Before Upgrading...........................................................................................................4
                  Allow Time for Search Index Rebuilding................................................................................................. 4
           Database Upgrades................................................................................................................................................ 4
           Creating a Test Environment Before Upgrading...................................................................................................4
           Upgrading a Linux Package.................................................................................................................................. 4
                  Upgrading the Package..............................................................................................................................5
           Upgrading Custom Themes and Templates.......................................................................................................... 6
           Upgrading on a Cluster..........................................................................................................................................7
           Post-Upgrade Tasks...............................................................................................................................................7
           Troubleshooting Upgrades.................................................................................................................................... 8
                  Troubleshooting Upgrades from 3.0 and Higher.......................................................................................8
                                                                                                                             | Upgrading | 3




Upgrading
    This guide includes information on upgrading the application.

    Upgrading from Version 3.0 and Higher
    Some Jive modules you've purchased have their own system and installation requirements. See the separate
    documentation for each module.
    With Jive versions 3 and up, the distribution you receive includes key required pieces such as an application server
    and a Java VM. Your operating system should have a package manager (such as the RPM manager on Linux) already
    installed. When installing, you'll invoke that manager to install the package that contains the application.

    Upgrading from a Version Before 3.0
    You can upgrade from an earlier installation, version 2.5 and higher (if you're on a version prior to 2.5, you'll need to
    upgrade to 2.5 before upgrading to this version). If you're experienced with previous upgrades, you'll notice that the
    new platform presented with Jive means that the process has changed considerably. While the steps you'll take here
    to upgrade to Jive include special steps to get from a previous version to this one, you'll only do these steps for this
    upgrade; future upgrades are made much simpler because they're managed through the package manager.
    •   Jive Software supports upgrades to Jive from version 2.5.x and later.
    •   These instructions assume you've already installed the application on the target host. If you haven't, you can use
        the installation instructions to do so.
    •   You'll export information from your jiveHome directory, the home for application environment-related data.
    •   If you're upgrading from an application instance that uses a DBMS not supported on version 3, you should
        already have migrated your database to a supported DBMS. Take a look at the database prerequisites for more
        information.
    •   Upgrading from a version old than 3.0 includes steps you'll take only for upgrades from a version older than 3.0.
        Future upgrades are made much simpler by the package manager used by versions 3.0 and higher.
            Note: Upgrading an existing standalone or source build to version 3 is not supported. Make sure to back up
            your jiveHome directory and back up your database before doing an upgrade.



Before You Upgrade
    Before you upgrade your instance, take the steps described here (such as backing up important data) to help ensure
    that your upgrade is successful.

Back Up Your jiveHome Directory
    The jiveHome directory is the place where versions before 3.0 store information about your environment. The
    database connection information is stored there, as well as logs, cached attachments, your license file, and the local
    system database files (if used). You should back up this directory before upgrading.

Back Up Your Database
    You should back up your database before you upgrade. For now, the best way to manage database backups is to
    follow the recommendations of your DBA or the recommendations of your database software. There are a number of
    tools built in to various databases. Here are a couple of examples:
    •   MySQL — Use the mysqldump tool
    •   Postgres — Use the pg_dump tool
                                                                                                                        | Upgrading | 4



Remove Plugins Before Upgrading
    Before starting your upgrade, be sure to remove any plugins you've installed. For those plugins that aren't compatible
    with the version you're upgrading to, you'll need to separately upgrade your plugin code (or get upgraded versions of
    the plugins from their developer), then install the upgraded versions after you've completed your Jive upgrade. The
    latest versions of Jive-supported plugins are available from the Jive Community.
    For more on managing plugins, see Adding and Removing Plugins.

Allow Time for Search Index Rebuilding
    Jive Software recommends that you first test the upgrade on a UAT instance to determine how long the search index
    rebuild will take. In some cases, it may take days to rebuild the index, depending on the size and activity of the
    community. Communities with large amounts of content and activity should allow adequate time for the search index
    rebuild before deploying an upgrade to production.


Database Upgrades
    You'll need to upgrade your database when you upgrade the rest of the installation.
    For information about database upgrades, see Upgrading a Database. You may want to review the rest of the best
    practices in Database Configuration and Best Practices, especially if you are moving to a new database platform.


Creating a Test Environment Before Upgrading
    If you are upgrading an existing instance of Jive, we strongly recommend you create a test environment for the new
    version before migrating your current database. The following instructions assume that your application name is "sbs"
    and you are using a Postgres database.
    1. Dump the production database and copy it to your target server.

         pg_dump sbs -Fc -O -U postgres > sbs_prod.dmp
    2. Re-create the target database.

         createdb sbs -E UTF-8 -O sbs -U postgres
    3. Restore the database from production into the target.

         pg_restore -d sbs -O -x -i -U sbs < /home/your_name/sbs_prod.dmp
    4. Log into the database and override all of the email addresses to prevent spamming. We strongly recommend
       disabling email so that your Jive test instance does not spam users with email.

         update jiveuser set email = username || 'discard@localhost';
    5. Start the target app server.
    6. Rebuild the user and main search indexes (Admin Console: System > Settings > Search > Index Tasks).
    7. Update the jiveURL system property (Admin Console: System > Management > System Properties).
    8. Change/disable the Email Monitor (Admin Console: System > Settings > Email Server > Incoming Email).
    9. Change the Analytics database settings, if applicable.
    10. Change your SSO settings, if applicable.
    11. Change your video keys, if applicable.


Upgrading a Linux Package
    With a new package distribution in hand, you can easily upgrade your existing package.
                                                                                                                         | Upgrading | 5



           Note: Before you upgrade, uninstall all your plugins. You'll need to re-install them via the Admin Console
           after you have successfully upgraded.


   What You'll Need to Upgrade
   •   An existing installation of the Jive package.
   •   A copy of the application package you're upgrading with. You'll also need SSH access to the host computer so you
       can copy the package there for installation.
   •   Root access (not just sudo) to the host where the installation is performed, commonly via SSH.

Upgrading the Package
   For more detail about the commands, refer to Installing the Linux Package.
           Note: Executing the rpm command to upgrade the package will automatically stop Jive applications. The
           application will be started again at the end of the upgrade.

   1. Be sure to read the system requirements for important information about software, hardware, and network
       requirements and recommendations.
   2. Remove all plug-ins from your existing instance. (You'll need to re-install them via the Admin Console after
       you've successfully upgraded). For a list of supported Jive plugins, see this list in the Jive Community.
   3. If you are upgrading from a version earlier than 3.0, back up the jiveHome directory. For more information, see
       Transferring jiveHome.
   4. If you are upgrading from a version later than 5.0, if possible, pull the web application server(s) from the load
       balancing pool to prevent new activity coming in. Make sure your Activity Engine queues are drained to zero.
       You can see the queues in Admin Console: System > Settings > Activity Engine. (Versions before 5.0 do not
       use an Activity Engine.)
   5. Stop the existing web application server(s).
   6. Back up your existing database. If you are also upgrading the database, see Upgrading a Databse.
   7. From the command line, access the target host as root.
   8. If you haven't yet done so, copy the new application package to the target host.
   9. Set your desired installation options as described in Installing the Linux Package.
   10. Upgrade the application package using an rpm command such as the following. Here, the U, h, and v options
       are provided to indicate install with hash indicators, and to be verbose during the installation. You must run this
       command on each cache server in your configuration.

        rpm -Uhv jive_sbs_employee-6.0.0.RHEL-5.x86_64.rpm

       Note that all elements of the application will be upgraded, including cache services and, if you have it, document
       conversion services. The following shows console output for a successful upgrade using the preceding command.

        [root@targethost ~]# rpm -Uvh jive_sbs_employee-5.0.0.RHEL-5.x86_64.rpm
        Preparing...                 ###########################################
         [100%]
        Writing upgrade version.
        Wrote upgrade version.
        Stopping Jive Applications
        Stopping Jive System Database.
        Stopping Jive HTTP Service.
        Stopping Jive JDCD Service.
        Stopping Jive JOOSD Service.
        Jive pre-upgrade configuration complete.
        Pre-install tasks complete.
           1:jive_sbs                ###########################################
         [100%]
        Executing Jive post-install configuration.
        Performing jive platform upgrade.
                                                                                                                            | Upgrading | 6



        Platform upgrade successful.
        Jive post-install upgrate configuration complete.
        Executing Jive post-install configuration.
        Jive Document Conversion Daemon activated.
        Jive Open Office Server activated.
        Starting Jive System Daemon.
        Performing Jive system configurations.

        Starting Jive System Database.
        server starting
        Disabling existing Apache HTTPD server.
        Starting jive-httpd:

        Starting Jive applications.
        Starting jive-jdcd:
        OK
        Starting jive-joosd:
        OK
        Handling applications ['sbs']
        Starting sbs...
        Executing /usr/local/jive/applications/sbs/bin/manage start
        sbs started successfully.
        All applications started successfully (1 total).
        Jive post-install configuration complete.
   11. With a supported web browser, navigate to http://<hostname>/, where hostname is the DNS resolvable name of
       the server where the RPM was installed. There, you can proceed with the upgrade using the Admin Console.
   12. After you've finished the upgrade, you'll need to restart the application. To do this, log into the target host as the
       jive user and execute the following commands:

        appstop --verbose

        appstart --verbose
   13. You're finished upgrading. You can now reapply any plugins you installed. Note that you may also need to
       reconfigure SSL support for Apache and Tomcat; some configuration files are overwritten during the upgrade.
   14. If you had any custom themes and templates, see Upgrading Custom Themes and Templates.
   15. See Post-Upgrading Tasks for your next steps.


Upgrading Custom Themes and Templates
   For each customized theme and/or template, you will run a 3-way diff against core (current core version on the left,
   new version on the right, customized version in the middle).
   1. Upgrade your existing Jive instance using the instructions in Upgrading a Linux Package.
   2. Copy your production themes to the target server. Your themes are located in /usr/local/jive/applications/sbs/
      home/themes.
   3. Copy your production templates to the targer server. Your templates are located in /usr/local/jive/applications/sbs/
      home/templates.
   4. For each customized theme and template, run a 3-way diff against core (e.g., current core version on the left, new
      version on the right, customized version in the middle). DiffMerge is a useful tool for performing diffs.
   5. Merge from the right all differences between the old and new core themes/templates. Keep your custom
      modifications.
                                                                                                                           | Upgrading | 7




Upgrading on a Cluster
   Before you get started with your upgrade, you might want to read the clustering and caching overview topics.
   Clustering and caching interoperate closely on a clustered installation.
   In addition, be sure to confirm that the plugins you're using are compatible with the version you're upgrading to. In
   some cases, you might need to make changes to plugins to ensure they work on the later version of the application.
   When you're upgrading from a version prior to 4.5.0, be sure to follow the steps listed here. Note that you must
   upgrade from version 4.0.0 or later.
   1. Remove all plug-ins from your existing instance. (You'll need to re-install them via the Admin Console after
      you've successfully upgraded).
   2. Stop all application server nodes in the cluster.
   3. Use the application package (such as the RPM on Linux) to set up a cache server on a separate machine. See
      Setting Up a Cache Server for more information. Note the cache server address for use later in setting up
      application servers.
   4. Before proceeding, make sure the cache server you set up is running. It must be running while you set up the
      application server nodes.
   5. On each node in the cluster, upgrade the application instance using the package (RPM on Linux), but don't run the
      setup tool yet.
       For more information on upgrading the package, see Upgrading a Linux Package.
   6. Start one web app node (and only one web app node) and navigate to its instance with a web browser. Work
       through the upgrade tool, allowing it to run the upgrade tasks it lists.
   7. Restart the application server you've upgraded and navigate to it with a web browser again. In the setup screen
       provided, enter the address of the cache server you installed, then complete the setup tool.
   8. After you've finished with the setup tool, restart the application server.
   9. Start the application server on each of the other nodes. Because it's connecting to the same database used by the
       server on the node you've already set up, the server on each subsequent node will detect that clustering is enabled.
       Each will also pick up configuration you set on the first node.
   10. After setting up all of the application server nodes and running them once, restart all servers in the cluster to
       ensure that the address of each node in the cluster is known to all the other nodes. The entire cluster must be
       bounced after all the nodes are set up.
   11. You can now reapply any plugins you installed. See Post-Upgrading Tasks for your next steps.


Post-Upgrade Tasks
   After you have upgraded, there are a few key issues to be aware of:

   Email
   Your production instance is typically set up to both send email notifications (SMTP) and access an email account
   (Email Monitor) or server (Advanced Incoming Email). You'll definitely want to temporarily change these settings
   in your test production instance; otherwise, you may find that the new test instance generates email notifications that
   look like they're coming from your production instance. This can be very confusing to end users, and might end up
   unnecessarily burdening your email servers.
   To make this problem less painful:
   •   Change all email addresses to a dummy value with:

        UPDATE jiveuser SET email = 'dummy@localhost';
   •   Turn off SMTP by changing the SMTP server name to nomail.
   •   Disconnect or reconfigure the Email Monitor to point to a different mailbox.
                                                                                                                          | Upgrading | 8



    •    Disconnect or reconfigure the Advanced Incoming Email feature.
    If you had customized email templates, they are not overwritten during an upgrade. We recommend testing them after
    an upgrade to ensure your customizations have been maintained.

    JiveURL
    You'll definitely want to change the jiveURL system property to match the URL at which you're hosting the test
    instance. The jiveURL is used throughout the app to render links. If you do not change this property, you will find
    that links to content in your test instance redirect you back to production. Additionally, this will help people recognize
    when they're using the test instance instead of production.

    Analytics
    This is VERY IMPORTANT: make sure you disable the Analytics module on the test server. Otherwise, you will
    have two instances, production and test, writing data to the same Analytics database. This can cause data corruption
    and ETL task failures. Additionally, if you leave the analytics settings in place and run a major upgrade, you may
    break analytics functionality on the production server by upgrading the analytics database schema to the new version.
    You can, of course, set up a new database for analytics for your test instance. Just make sure you do one or the other.

    Video
    Video keys are meant to work only with a single instance. Remove the video keys from the test instance to ensure that
    you do not "confuse" the video provider and break video functionality on your production instance.


Troubleshooting Upgrades
    This section details issues that may arise during the upgrade process, as well as their solutions.

Troubleshooting Upgrades from 3.0 and Higher

    Driver Not Found Errors
    Because of licensing restrictions, Jive cannot ship database drivers for all previously-supported databases.
    Specifically, the JDBC drivers for DB2 and MySQL are not included with the Jive platform package. The platform
    will attempt to install these drivers when you install the platform, but in some cases automated installation will not
    be possible. If the package cannot download the appropriate drivers, an error message will be printed to the console
    similar to “No suitable driver found for…”. The following code example shows the response when the runtime
    system fails to find the MySQL database driver :


        java.sql.SQLException: No suitable driver found for >jdbc:mysql://soul:3306/
        csc252
        at java.sql.DriverManager.getConnection(DriverManager.java:602)
        at java.sql.DriverManager.getConnection(DriverManager.java:185)
        at com.jivesoftware.migration.schema.DbUtil.getConnection(DbUtil.java:133)
        at
         com.jivesoftware.migration.etl.DbConfig.getInputConnection(DbConfig.java:161)
        at com.jivesoftware.migration.etl.DbConfig.getVersion(DbConfig.java:263)
        at com.jivesoftware.cli.Main.exportBlobs(Main.java:198)
        at com.jivesoftware.cli.Main.run(Main.java:100)
        at com.jivesoftware.cli.Main.main(Main.java:66)
        Exception in thread "main" java.lang.RuntimeException:
         java.lang.NullPointerException
        at com.jivesoftware.cli.Main.main(Main.java:68)
        Caused by: java.lang.NullPointerException
        at com.jivesoftware.migration.etl.DbConfig.getVersion(DbConfig.java:273)
        at com.jivesoftware.cli.Main.exportBlobs(Main.java:198)
        at com.jivesoftware.cli.Main.run(Main.java:100)
                                                                                                                        | Upgrading | 9



 at com.jivesoftware.cli.Main.main(Main.java:66)

To resolve this issue, download the MySQL JDBC driver and place the JAR file for the driver in the jive user’s bin/
migrate/lib directory. The following sequence demonstrates downloading the file and unpacking to the /usr/local/jive/
bin/migration/lib directory of the target host. Note that it is necessary to change the permissions on the /usr/local/jive/
bin/migration/lib directory to move the expanded tar.gz file to the lib directory. This directory is read-only by default
on a managed host.

 [1632][jive@targethost:~]$ wget http://dev.mysql.com/get/Downloads/
 Connector-J/mysql-connector-java-5.1.7.tar.gz/from/http://mysql.llarian.net/
 --16:32:11-- http://dev.mysql.com/get/Downloads/Connector-J/mysql-
 connector-java-5.1.7.tar.gz/from/http://mysql.llarian.net/
 Resolving dev.mysql.com... 213.136.52.29
 Connecting to dev.mysql.com|213.136.52.29|:80... connected.
 HTTP request sent, awaiting response... 302 Found
 Location: http://mysql.llarian.net/Downloads/Connector-J/mysql-connector-
 java-5.1.7.tar.gz [following]
 --16:32:13-- http://mysql.llarian.net/Downloads/Connector-J/mysql-
 connector-java-5.1.7.tar.gz
 Resolving mysql.llarian.net... 209.221.142.116, 2001:5d8:11::14
 Connecting to mysql.llarian.net|209.221.142.116|:80... connected.
 HTTP request sent, awaiting response... 200 OK
 Length: 8640154 (8.2M) [application/x-gzip]
 Saving to: `mysql-connector-java-5.1.7.tar.gz'
 100%[================================================================>]
  8,640,154   5.11M/s   in 1.6s
 16:32:14 (5.11 MB/s) - `mysql-connector-java-5.1.7.tar.gz' saved
  [8640154/8640154]
 [1632][jive@targethost:~]$ tar zxf mysql-connector-java-5.1.7.tar.gz
 [1632][jive@targethost:~]$ mv mysql-connector-java-5.1.7/
 build.xml                           docs/
  README
 CHANGES                             EXCEPTIONS-CONNECTOR-J
  README.txt
 COPYING                             mysql-connector-java-5.1.7-bin.jar
  src/

 [1632][jive@targethost:~]$ mv mysql-connector-java-5.1.7 bin/migration/lib/
 mv: cannot move `mysql-connector-java-5.1.7' to `bin/migration/lib/mysql-
 connector-java-5.1.7': Permission denied
 [1632][jive@targethost:~]$ chmod 755 bin/migration/lib
 [1632][jive@targethost:~]$ mv mysql-connector-java-5.1.7 bin/migration/lib/
 [1632][jive@targethost:~]$ ./bin/migration/bin/migration ./
 migration.properties

								
To top