Appboard/old/unix installation: Difference between revisions

imported>Mike.berman
(update language to reflect dual use for AppBoard and enPortal applications)
imported>Mike.berman
(add Restoring an Archive section)
Line 50: Line 50:
** 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.
=== 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 [[Backup_and_Restore|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.

Revision as of 21:35, 11 November 2012

Linux and UNIX Installation

Installation Tasks

  1. Install the Java Development Kit
  2. 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
  3. Save your license file into [INSTALL_HOME]/webapps/enportal/WEB-INF/config/license.properties


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.

  1. As root, 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.


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