Edge Documentation

Latest revision as of 10:59, 30 April 2015

Prerequisites

Install Java (refer to the System Requirements for supported versions)
Install unzip

Installation Tasks

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.6.0.zip
Save your license file into [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/license.properties
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 to use (e.g. /usr/bin/java), what user to run AppBoard as, and whether you wish to install a system service to automaticaly start/stop AppBoard 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.

Change into the [INSTALL_HOME]/server/bin/helpers directory
Run: $ ./post_install.sh
if this script is not set executable, then run and try again: $ chmod u+x post_install.sh
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.
[optional] Make changes to the default ports, java memory tuning, and runtime options. Refer to the Runtime Options page for further information. Please note that some runtime options are managed by the post_install script.
[optional] AppBoard comes with a pre-configured H2 database for storing configuration. An external configuration database can also be used, see the Configuration Database page for more information.

post_install Details

The post_install script manages the following environment variables which are updated into setenv-custom.sh. It is recommended to re-run post_install to make changes to these:

TOMCAT_USER
TOMCAT_GROUP
TOMCAT_SERVICE
USE_JSVC
JAVA_HOME

JAVA_HOME is a very important setting and is stored within setenv-custom to ensure a consistent environment whether running portal.sh, running AppBoard from the command line, or running AppBoard as a service.

post_install will determine JAVA_HOME based on the following rules:

The current setting from setenv-custom
If above is not set, or invalid, then JAVA_HOME from the user's environment
If above is not set, or invalid, then based on the user's PATH ($ which java)
Finally, the user is prompted to enter an alternative location.

Due to how Java runtime environments are managed on the various Linux / UNIX systems, the script also completely resolves any symbolic links. This may explain why a simple Java path such as /usr/bin/java can be saved as a more involved JAVA_HOME into setenv-custom.sh. After running post_install it's always possible to edit setenv-custom and set a different JAVA_HOME if necessary.

Verifying the Installation

Start AppBoard:
- 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]/server/bin directory: ./startup.sh
Any errors will be logged into [INSTALL_HOME]/server/logs
Go to the following URL in a web browser, using a system that has network access to the server: http://server_ip:8080. If the system started correctly, a login page will be displayed.
- The default login credentials are: administrator / administrator / System

Additional Configuration Options

Starting on Boot

To have AppBoard 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 installation directory has to be moved, or AppBoard 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]/server/bin/helpers directory: $ ./unix_services.sh remove

Binding to Port <1024 as non-root

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

Use JSVC to run AppBoard. 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 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).
Use OS-supported port forwarding. Depending on the platform, the operating system may offer network layer port forwarding to transparently route traffic from the desired port to the port AppBoard is listening on.
- Example for Linux using iptables. This will redirect port 80 to port 8080 arriving on the eth0 interface. Add this command to /etc/rc.local to enable on boot:
  iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
- Example for Solaris using ipfilter. This will redirect port 80 to port 8080 for traffic on the e1000g0 interface which has IP 192.168.149.131:
  1. create /etc/ipf/ipnat.conf if it does not exist, and add the line:
    rdr e1000g0 192.168.149.131/32 port 80 -> 127.0.0.1 port 8080 tcp
  2. enable the ipfilter system service: $ svcadm enable ipfilter. This will ensure the service is enabled at boot.
  3. verify the forwarding rules: $ ipnat -l

64-bit Java on Solaris

Java for Solaris is packaged differently than for other platforms in that both 32-bit and 64-bit JVMs exist in the same location. In order to use the 64-bit VM it's necessary to either specify the -d64 option, or to explicitly run the 64-bit executable (for example: /opt/java8/bin/amd64/java).

For the best results with AppBoard do the following:

For default (non-jsvc) installs edit setenv-custom.sh and add the following:
CUSTOM_JAVA_OPTS="-d64"
If using JSVC just ensure [INSTALL_HOME]/server/bin/jsvc links to the 64-bit executable. Do not set the variable above as this option is not valid to the jsvc executable.

Restoring an Archive

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

If using a Restore then setenv-custom.sh 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 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.

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.

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.