Appboard/old/unix installation: Difference between revisions

imported>Mike.berman
(add notes regarding lsb-release and JAVA_HOME)
imported>Mike.berman
(update for runtime options)
Line 10: Line 10:
## <tt>$ mkdir /opt/appboard</tt>
## <tt>$ mkdir /opt/appboard</tt>
## <tt>$ cd /opt/appboard</tt>
## <tt>$ cd /opt/appboard</tt>
## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>
## <tt>$ unzip ''AppBoard-2.3.15.zip''</tt>
# Save your license file into <tt>[INSTALL_HOME]/webapps/enportal/WEB-INF/config/license.properties</tt>
# Save your license file into <tt>[INSTALL_HOME]/webapps/enportal/WEB-INF/config/license.properties</tt>
# Run the post installation tasks.
# Run the post installation tasks.


===Post Installation Tasks===
===Post Installation Tasks===
Line 28: Line 27:
# Answer the prompted questions. Defaults or previous preferences are provided where appropriate.
# Answer the prompted questions. Defaults or previous preferences are provided where appropriate.
# The script will verify selected options before making any changes, so review and continue if correct.
# The script will verify selected options before making any changes, so review and continue if correct.
# [optional] Make changes to the default ports, java memory tuning, and other options by updating <tt>[INSTALL_HOME]/bin/setenv-custom.sh</tt>. However, see notes below for options managed by the post_install script.
# [optional] Make changes to the default ports, java memory tuning, and runtime options. Refer to the [[Runtime_Options|Runtime Options]] page for further information. Please also note that some options are managed by the post_install script, see below.
 
 
User-supplied preferences are stored in <tt>[INSTALL_HOME]/bin/setenv-custom.sh</tt>. In particular, the options from the post_install script are TOMCAT_USER, TOMCAT_SERVICE, JAVA_HOME, and USE_JSVC. Although these can be modified directly, it is best to re-run the post_install script to make changes.


<tt>post_install.sh</tt> manages the <tt>TOMCAT_USER</tt>, <tt>TOMCAT_SERVICE</tt>, <tt>USE_JSVC</tt>, and <tt>JAVA_HOME</tt> options stored in <tt>setenv-custom.sh</tt>. These can be edited directly but it's recommend to just re-run the post_install script instead.


If "java" is not found in the system path, the script will check for JAVA_HOME and use $JAVA_HOME/bin/java instead.  Detection is done in this order/preference:
If "java" is not found in the system path, the script will check for JAVA_HOME and use $JAVA_HOME/bin/java instead.  Detection is done in this order/preference:
Line 64: Line 61:
If AppBoard/enPortal is ''not'' running as root, Tomcat will not be able to bind to a port less than 1024. By default, AppBoard/enPortal is configured to listen on port 8080 so this is not an issue. However in production systems it may be necessary to have AppBoard/enPortal listen on a port < 1024 and have AppBoard/enPortal run as non-root. In these situations, the following options apply:
If AppBoard/enPortal is ''not'' running as root, Tomcat will not be able to bind to a port less than 1024. By default, AppBoard/enPortal is configured to listen on port 8080 so this is not an issue. However in production systems it may be necessary to have AppBoard/enPortal listen on a port < 1024 and have AppBoard/enPortal run as non-root. In these situations, the following options apply:


* Use JSVC to run AppBoard/enPortal. This allows JSVC to run as root, bind to the port, and then start Tomcat as the non-root user. To configure JSVC, run the Post Installation script and answer ''yes'' to the question about using JSVC. Also, update <tt>[INSTALL_HOME]/bin/setenv-custom.sh</tt> to update HTTP_PORT with the desired value. It will be necessary to restart AppBoard/enPortal for these changes to take effect.
* Use JSVC to run AppBoard/enPortal. This allows JSVC to run as root, bind to the port, and then start Tomcat as the non-root user. To configure JSVC, run the Post Installation script and answer ''yes'' to the question about using JSVC. To change the listening port then edit the HTTP_PORT value in <tt>setenv-custom.sh</tt> (see [[Runtime_Options|Runtime Options]]). It will be necessary to restart AppBoard/enPortal for these changes to take effect.
** NOTE: in some cases the included JSVC binary may not work and will need to be re-compiled to suit your platform/configuration (see http://commons.apache.org/daemon/jsvc.html).
** NOTE: in some cases the included JSVC binary may not work and will need to be re-compiled to suit your platform/configuration (see http://commons.apache.org/daemon/jsvc.html).
* As an alternative to using JSVC, you can use some kind of port forwarding that is transparent to the client which listens on the desired port and forwards traffic to AppBoard/enPortal. On Linux systems, this can be achieved using iptables.
* As an alternative to using JSVC, you can use some kind of port forwarding that is transparent to the client which listens on the desired port and forwards traffic to AppBoard/enPortal. On Linux systems, this can be achieved using iptables.
Line 71: Line 68:
=== Restoring an Archive ===
=== Restoring an Archive ===


The instructions above detail the procedures for a new installation. However, in some cases you will be installing from an archive of a previous system. This would be done, for example, in the case of upgrading to a new version of AppBoard, or migrating a system from one server to another.
The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see [[Backup_and_Restore|Backup and Restore]]) it actually replaces files on the filesystem and you '''must''' review:
 
# If using a ''Restore'' then <tt>setenv-custom.sh</tt> is replaced
# If using a ''Restore'' the license file may be replaced
# Both ''Restore'' and ''Apply'' cases may include files with incorrect permissions and/or ownership
 
The recommendation whether restoring with a ''Restore'' or ''Apply'' is to re-run <tt>post_install.sh</tt> after the import completes. In cases where the archive originates from a different system then ''Apply'' is the recommended import command.
 
 
== Stopping AppBoard ==
To stop AppBoard, terminate the Tomcat process that is running on the AppBoard server.
 
{{Warning|When AppBoard is stopped, all current Users who are logged in to the system will receive an error message the next time they make a request to the AppBoard server.  Subsequent Users will not be able to access the login page until AppBoard is re-started.  If you are stopping a production instance of AppBoard, it is recommended that you schedule a maintenance window and send advance notification to Users of the system.  You can check if there are any active Users logged in to AppBoard before stopping it, by using the [[Session_Management|Session Manager]].}}
 
* For instances running as a system service make sure it is shutdown as a service, i.e.
*: <tt>$ /etc/init.d/appboard stop</tt>
* When running on the command line then use:
*: <tt>[INSTALL_HOME]/server/bin/stop.sh</tt>
* When running attached to the console (<tt>./catalina.sh run</tt>) then use a CTRL+C signal to terminate.
* As a general alternative locate the process and send a <tt>TERM</tt> signal.
 


When [[Backup_and_Restore|restoring from an archive]], there are a few items to consider and review:
{{Warning|You must properly shut down Tomcat. Do not kill the process by clicking the window "close" button ("X") or by using the Unix kill command (kill -9 <processid>). If the database does not properly shut down, residual lock files have been documented to cause problems when restoring archives.}}
* It is possible that the JAVA_HOME setting can be overwritten when you restore the archive. Check to verify that the JAVA_HOME variable setting matches the Java installation location on the current server.
* It is necessary to run the post_install script again after restoring the archive. See instructions above for running this command.

Revision as of 15:57, 16 June 2013

Linux and UNIX Installation

Prerequisites

  1. Install the Java Development Kit (1.6 or later)
  2. Install unzip
  3. Install lsb-release (redhat-lsb for RHEL; lsb-release for Ubuntu, SuSE and Debian).

Installation Tasks

  1. Extract the turnkey installation archive to the desired location on the server. For example:
    1. $ mkdir /opt/appboard
    2. $ cd /opt/appboard
    3. $ unzip AppBoard-2.3.15.zip
  2. Save your license file into [INSTALL_HOME]/webapps/enportal/WEB-INF/config/license.properties
  3. Run the post installation tasks.

Post Installation Tasks

On Linux and UNIX systems, it is necessary to run a script to update file ownership and permissions, and set some initial configuration parameters. To be prepared to run this script, make sure you know which java you want AppBoard/enPortal to use (e.g. /usr/bin/java), what user to run AppBoard/enPortal as, and whether you wish to install a system service to automaticaly start/stop AppBoard/enPortal on boot and shutdown.


This script can be run as root or non-root. When run as non-root some options are not available, such as installing a system service.


  1. Change into the [INSTALL_HOME]/bin/helpers directory
  2. Run: $ ./post_install.sh
    • if this script is not set executable, then run and try again: $ chmod u+x post_install.sh
  3. Answer the prompted questions. Defaults or previous preferences are provided where appropriate.
  4. The script will verify selected options before making any changes, so review and continue if correct.
  5. [optional] Make changes to the default ports, java memory tuning, and runtime options. Refer to the Runtime Options page for further information. Please also note that some options are managed by the post_install script, see below.

post_install.sh manages the TOMCAT_USER, TOMCAT_SERVICE, USE_JSVC, and JAVA_HOME options stored in setenv-custom.sh. These can be edited directly but it's recommend to just re-run the post_install script instead.

If "java" is not found in the system path, the script will check for JAVA_HOME and use $JAVA_HOME/bin/java instead. Detection is done in this order/preference:

  1. java from your path ($ which java)
  2. JAVA_HOME from your env
  3. JRE_HOME from your env


Verifying the Installation

  1. Start AppBoard/enPortal:
    • If a system service was installed, then use the appropriate command to start, such as $ service service_name start for RedHat Enterprise Linux
    • Or start on the command line from the [INSTALL_HOME]/bin directory: ./startup.sh
  2. Any errors will be logged into [INSTALL_HOME]/logs
  3. Go to the following URL in a web browser, using a system that has network access to the server: http://server_ip:8080/enportal/ab/home. If the system started correctly, a login page will be displayed.
    • The default login credentials are: administrator / administrator / System


Additional Configuration Options

Linux / UNIX Services (Starting AppBoard/enPortal automatically on boot)

To have AppBoard/enPortal start and stop automatically on boot and shutdown, it is necessary to use a system service. The Post Installation script will handle setting up and configuring the system service on supported platforms.

NOTE: if the AppBoard/enPortal installation directory has to be moved, or AppBoard/enPortal is to be removed, then make sure to remove the system service first. This can be done using the unix services utility as root from the [INSTALL_HOME]/bin/helpers directory: $ ./unix_services.sh remove


Binding to Port <1024 as non-root

If AppBoard/enPortal is not running as root, Tomcat will not be able to bind to a port less than 1024. By default, AppBoard/enPortal is configured to listen on port 8080 so this is not an issue. However in production systems it may be necessary to have AppBoard/enPortal listen on a port < 1024 and have AppBoard/enPortal run as non-root. In these situations, the following options apply:

  • Use JSVC to run AppBoard/enPortal. This allows JSVC to run as root, bind to the port, and then start Tomcat as the non-root user. To configure JSVC, run the Post Installation script and answer yes to the question about using JSVC. To change the listening port then edit the HTTP_PORT value in setenv-custom.sh (see Runtime Options). It will be necessary to restart AppBoard/enPortal for these changes to take effect.
  • As an alternative to using JSVC, you can use some kind of port forwarding that is transparent to the client which listens on the desired port and forwards traffic to AppBoard/enPortal. On Linux systems, this can be achieved using iptables.


Restoring an Archive

The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see Backup and Restore) it actually replaces files on the filesystem and you must review:

  1. If using a Restore then setenv-custom.sh is replaced
  2. If using a Restore the license file may be replaced
  3. Both Restore and Apply cases may include files with incorrect permissions and/or ownership

The recommendation whether restoring with a Restore or Apply is to re-run post_install.sh after the import completes. In cases where the archive originates from a different system then Apply is the recommended import command.


Stopping AppBoard

To stop AppBoard, terminate the Tomcat process that is running on the AppBoard server.

Template-warning.png
When AppBoard is stopped, all current Users who are logged in to the system will receive an error message the next time they make a request to the AppBoard server. Subsequent Users will not be able to access the login page until AppBoard is re-started. If you are stopping a production instance of AppBoard, it is recommended that you schedule a maintenance window and send advance notification to Users of the system. You can check if there are any active Users logged in to AppBoard before stopping it, by using the Session Manager.
  • For instances running as a system service make sure it is shutdown as a service, i.e.
    $ /etc/init.d/appboard stop
  • When running on the command line then use:
    [INSTALL_HOME]/server/bin/stop.sh
  • When running attached to the console (./catalina.sh run) then use a CTRL+C signal to terminate.
  • As a general alternative locate the process and send a TERM signal.


Template-warning.png
You must properly shut down Tomcat. Do not kill the process by clicking the window "close" button ("X") or by using the Unix kill command (kill -9 <processid>). If the database does not properly shut down, residual lock files have been documented to cause problems when restoring archives.