Appboard/old/unix installation: Difference between revisions

imported>Mike.berman
(created page)
 
imported>Mike.berman
(update language to reflect dual use for AppBoard and enPortal applications)
Line 7: Line 7:
## <tt>$ cd /opt/appboard</tt>
## <tt>$ cd /opt/appboard</tt>
## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>
## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>
# Save your license file into <tt>[APPBOARD_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>




===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. <tt>/usr/bin/java</tt>), what user to run AppBoard as, and whether you wish to install a system service to automaticaly start/stop AppBoard on boot and shutdown.
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. <tt>/usr/bin/java</tt>), 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.


# As root, change into the <tt>[APPBOARD_HOME]/bin/helpers</tt> directory
# As root, change into the <tt>[INSTALL_HOME]/bin/helpers</tt> directory
# Run: <tt>$ ./post_install.sh</tt>
# Run: <tt>$ ./post_install.sh</tt>
#* if this script is not set executable, then run and try again: <tt>$ chmod u+x post_install.sh</tt>
#* if this script is not set executable, then run and try again: <tt>$ chmod u+x post_install.sh</tt>
# 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>[APPBOARD_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 other options by updating <tt>[INSTALL_HOME]/bin/setenv-custom.sh</tt>. However, see notes below for options managed by the post_install script.


User-supplied preferences are stored in <tt>[APPBOARD_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.
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.




===Verifying the Installation===
===Verifying the Installation===


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


===Linux / UNIX Services (Starting AppBoard automatically on boot)===
===Linux / UNIX Services (Starting AppBoard/enPortal automatically 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.
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 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 <tt>[APPBOARD_HOME]/bin/helpers</tt> directory: <tt>$ ./unix_services.sh remove</tt>
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 <tt>[INSTALL_HOME]/bin/helpers</tt> directory: <tt>$ ./unix_services.sh remove</tt>




===Binding to Port <1024 as non-root===
===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:
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. 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>[APPBOARD_HOME]/bin/setenv-custom.sh</tt> to update HTTP_PORT with the desired value. It will be necessary to restart AppBoard 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. 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.
** 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. 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.

Revision as of 16:35, 27 March 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.