Edge Documentation

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.2.0.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 other options by updating [INSTALL_HOME]/bin/setenv-custom.sh. However, see notes below for options managed by the post_install script.

User-supplied preferences are stored in [INSTALL_HOME]/bin/setenv-custom.sh. 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.

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. Also, update [INSTALL_HOME]/bin/setenv-custom.sh to update HTTP_PORT with the desired value. 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).
• 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, 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.

When restoring from an archive, there are a few items to consider and review:

• 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.