Installing on Linux

You'll find that both installation and upgrade go more smoothly if most database-related tasks are done before you begin installing. This is especially true if the database the application will be using is administered separately by a DBA. This section describes the database tasks that are required for a successful installation.

• Make a backup of your existing database. This probably goes without saying.
• Ensure that the target database allows access through which the application's setup tool can create tables. After you install the application, you'll finish installation (or upgrade) by using the application's admin tools to connect to the target database. The tool will create or upgrade the tables needed by this version of the application. You'll want to be sure that permission to create tables is granted at least until that process is completed.

  For example, if you'll be using an Oracle database for a new installation, you'll be creating a user representing a schema. That schema will be empty until the application setup tool creates tables in it. Here's an example script for creating such a user:

  create user jiveuser identified by changeme default tablespace jivedata;
  grant create session, create table, create view, create sequence, create procedure, create synonym to jiveuser;
  alter user jiveuser quota unlimited on jivedata;

  The username can be any legal Oracle identifier -- "jiveuser" is just an example. The application does not require a dedicated tablespace, but many DBAs have that practice. The tablespace must be created separately. For more on the create user statement, see the Oracle documentation.

  When creating the database user, the user be not be granted view access to any schema other than the one it owns. During upgrades the application will read metadata about its tables defined in the database. Since the application does not know what the default schema is, it may inadvertently retrieve information about its tables defined in other schemas. If you have setup application instances using other schemas in the same database, this can result in erroneous information passed to the application.

  If you absolutely must use a database user with access to other schemas, ensure that there is only one set of application tables defined across all schemas to prevent this object name conflict.

• Create or migrate your application database. How you do this will vary depending on whether you're installing a new instance or upgrading.
  • If you're installing a new instance:
    • If you're using the included PostgreSQL DBMS, installation handles database setup for you. You don't need to create a database.
    • If you're using an external DBMS, create the empty target database before you begin installing the application. Ensure that the new database allows the application setup tool to create tables. After you install, and during setup, the application will connect to your existing database and create the necessary tables.
  • If upgrading an existing instance:
    • If you're upgrading from an instance that uses a DBMS supported for this version:
      • If you're upgrading "in place" to continue to use the existing database, then the application handles the change after installation when you use the upgrade console. After you install, and during setup, the application will connect to your existing database and upgrade it.
    • If you're upgrading from an instance that uses a DBMS not supported on this version, create the empty target database before you begin installing the application. Migrate the data from the unsupported database to the supported one using the process described in Migrating Data from an Unsupported DBMS. Ensure that the new database allows the application setup tool to create tables. After you install, and during setup, the application will connect to your existing database and upgrade it.
• Confirm that the drivers required for the DBMS you'll be using are installed. Due to licensing restrictions, Jive is unable to ship and install all of the drivers for supported DBMSes. Use the table below to determine whether the driver you need is included, and install the driver if it's not.

  To install the driver, place the driver's JAR file in the application file system where it will be on the classpath, such as at /usr/local/jive/applications/template/application/WEB-INF/lib.

  DBMS	Driver Included	Action Needed
  Oracle	OCI driver required, but not included. (Thin driver is included for evaluation purposes only and should not be used under load.)	For more information on installing the OCI driver, see the Oracle Instant Client page. Please consult the Oracle documentation to choose the version of the JDBC driver best for you.
  PosgreSQL	Required driver included.	None.
  MySQL	Required driver not included.	You'll need to install the correct driver.
  SQL Server	Required driver not included.	You'll need to install the correct driver.

The following illustration lays out the high-level steps for installing Jive SBS and upgrading from a previous version. These steps are described in detail in this guide. Note that you're strongly encouraged to complete the database tasks described above before you start installing the application.

The jiveHome directory is the place where the application stores a number of things 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.

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 examples:

• MySQL — Use the "mysqldump" tool
• Postgres — Use the "pg_dump" tool

There are many tools for each database; pick one that suits your environment.

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 upgraded to this version.

To make moving the home directory easier, Jive SBS includes an export tool you can execute on the current host where the home directory resides. This export tool is packaged as a Java JAR file that you can execute directly from any Java 1.5-compliant Java Runtime Environment. This tool is intended to be executed with the JRE used to host the existing instance.

You'll find the tool in a package installation on the target host at:

/usr/local/jive/bin/export/export.jar

1. Locate the export tool in a package installation on the target host at:

   /usr/local/jive/bin/export/export.jar

2. Copy this file to the source host containing the existing home directory:

   [1638][jive@targethost:~/bin/export]$ scp export.jar root@oldhost:
   root@oldhost's password:
   export.jar

3. From the source machine, use the export tool to archive the existing home directory (formerly referred to as jiveHome) from the file system.

   Note: Before invoking the following commands, be sure to stop the current instance (stopping an existing instance will depend on the current application server).

   You should invoke the export tool from a command shell (for Windows cmd.exe, for Unix or Linux any standard shell). Commonly, the java command will be on the path of the shell executing the command. If it's not, prefix the following examples with the full path to a Java 1.5 JRE on the local system.

   To invoke the export tool, pass the “-jar <path_to_export.jar>” option to the java command in the working shell, as well as the path to the current home directory.

   For example, the following commands demonstrate how to export the home directory at “/usr/local/jive/jiveHome” when the “java” command is on the local user’s path:

   root@oldhost ~/opt/jive/home $ cd /home/eonnen/opt/jive/home/
   root@oldhost ~/opt/jive/home $ java -jar export.jar csc csc.zip

   For detailed export instructions, the “--help” option may be passed to the command which results in the following output:

   root@oldhost ~ $ cd opt/jive/home/
   root@oldhost ~/opt/jive/home $ java -jar export.jar --help
   usage: java -jar export.jar [options] jive_home archive_output
   
   Where jive_home is the path to the existing jive home directory and
   archive_output is the path where the export archive will be written.
    -a,--all          Include all artifacts in the existing jive home.
    -c,--caches       Include local attachment and plugin caches [default
                      disabled].
    -h,--help         Display this message.
    -i,--indexes      Include calculated search indexes [default disabled].
    -l,--logs         Include log files [default disabled].
    -o,--overwrite    Overwrite an existing artifact if one exists [default
                      disabled].
    -v,--verbose      Be verbose.
    -x,--no-exports   Do not include database exports [default enabled].
    -z,--no-themes    Do not include themes [default enabled].
   
   
   Home directory is required.

   In most cases, you should use the “--all” option. In large deployments, the size of index files may be too large to copy practically across a network. If this is the case, you can specify the “--indexes" option to exclude the index files from the export.

After you complete the preceding export step, you should copy the exported file to the installation host where the Jive SBS platform was installed.

1. Before using the export, make sure the target application is stopped. In a default Jive SBS Platform package installation, a single application named “sbs” will be running. Stop this application by using the “appstop” command as the jive user.

   [root@targethost ~]# su - jive
   [1055][jive@targethost:~]$ appstop --verbose sbs
   Stopping sbs...
   Executing /usr/local/jive/applications/sbs/bin/manage stop
   sbs stopped successfully.

2. After stopping the application, back up the existing home directory installed with the package. Unzip the exported home directory to the application’s home directory. In a standard package installation, the application’s home directory will be “/usr/local/jive/applications/sbs/home”. In the following example, the csc.zip archive of the exported home is located in the user’s home directory and is readable by the jive user.

   [root@targethost ~]# su - jive
   [1104][jive@targethost:~]$ appstop --verbose sbs
   Stopping sbs...
   Executing /usr/local/jive/applications/sbs/bin/manage stop
   sbs stopped successfully.
   sbs stopped successfully.
   [1104][jive@targethost:~]$ cd applications/sbs/home/
   [1104][jive@targethost:~/applications/sbs/home]$ cd ~
   [1104][jive@targethost:~]$ cd applications/sbs
   [1105][jive@targethost:~/applications/sbs]$ ll
   total 16K
   lrwxrwxrwx  1 jive jive   49 Jan 20 15:52 application 
       -> /usr/local/jive/applications/template/application
   drwxr-x---  2 jive jive 4.0K Jan 20 15:52 bin
   drwxr-x---  2 jive jive 4.0K Jan 20 15:51 conf
   drwxr-x--- 16 jive jive 4.0K Jan 22 11:02 home
   -rw-r--r--  1 jive jive  694 Jan 20 15:20 README
   [1105][jive@targethost:~/applications/sbs]$ mv home home.bak
   [1106][jive@targethost:~/applications/sbs]$ mkdir home
   [1107][jive@targethost:~/applications/sbs]$ cd home
   [1107][jive@targethost:~/applications/sbs/home]$ unzip ~/csc.zip 
   Archive:  /usr/local/jive/csc.zip
   [1108][jive@targethost:~/applications/sbs/home]$ ll
   total 32K
   drwxr-xr-x 2 jive jive 4.0K Jan 22 11:08 conf
   drwxr-xr-x 2 jive jive 4.0K Jan 22 11:08 database
   drwxr-xr-x 2 jive jive 4.0K Jan 22 11:08 geoip
   -rw-r--r-- 1 jive jive  958 Jan 22  2009 jive.license
   -rw-r--r-- 1 jive jive 1.7K Jan 22  2009 jive_startup.xml
   drwxr-xr-x 3 jive jive 4.0K Jan 22 11:08 resources
   drwxr-xr-x 2 jive jive 4.0K Jan 22 11:08 spelling
   drwxr-xr-x 3 jive jive 4.0K Jan 22 11:08 themes

The migration utility has been extensively tested on a variety of database and operating system platforms. Still, it is possible that a specific scenario may have been overlooked. This FAQ will try to answer some of the issues that you may encounter during the migration.