Appboard/2.4/admin/unix installation - Revision history

imported>Jason.nicholls at 10:55, 18 July 2014

2014-07-18T10:55:15Z

imported>Jason.nicholls: /* Post Installation Tasks */

2014-07-18T10:53:55Z

Post Installation Tasks

← Older revision		Revision as of 10:53, 18 July 2014
Line 17:		Line 17:
	==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. <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.		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.

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

imported>Jason.nicholls: /* Linux / UNIX Services (Starting AppBoard/enPortal automatically on boot) */

2014-07-18T10:52:19Z

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

← Older revision		Revision as of 10:52, 18 July 2014
Line 59:		Line 59:
	==Additional Configuration Options==		==Additional Configuration Options==

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


	===Binding to Port <1024 as non-root===		===Binding to Port <1024 as non-root===

imported>Jason.nicholls: /* post_install Details */

2014-07-18T10:50:43Z

post_install Details

← Older revision		Revision as of 10:50, 18 July 2014
Line 30:		Line 30:
	=== post_install Details ===		=== post_install Details ===

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

	* <tt>TOMCAT_USER</tt>		* <tt>TOMCAT_USER</tt>

imported>Jason.nicholls: /* post_install Details */

2014-07-18T10:50:13Z

post_install Details

← Older revision		Revision as of 10:50, 18 July 2014
Line 46:		Line 46:
	# Finally, the user is prompted to enter an alternative location.		# 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 can be specifified (~~such as <tt>/usr/bin/java</tt> ~~but something~~ more involved ~~saved as~~ JAVA_HOME into setenv-custom.sh. ~~In the worst case~~ setenv-custom~~.sh can be edited after running post_install to ensure the desired value~~.		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 <tt>/usr/bin/java</tt> 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==		==Verifying the Installation==

imported>Jason.nicholls: /* post_install Details */

2014-07-18T10:47:57Z

post_install Details

← Older revision		Revision as of 10:47, 18 July 2014
Line 30:		Line 30:
	=== post_install Details ===		=== post_install Details ===

	The post_install script ~~managed~~ the following environment variables which are updated into <tt>setenv-custom.sh</tt>. It is recommended to re-run post_install to make changes.		The post_install script manages the following environment variables which are updated into <tt>setenv-custom.sh</tt>. It is recommended to re-run post_install to make changes.

	* <tt>TOMCAT_USER</tt>		* <tt>TOMCAT_USER</tt>
Line 37:		Line 37:
	* <tt>JAVA_HOME</tt>		* <tt>JAVA_HOME</tt>

	~~<tt>~~JAVA_HOME~~</tt>~~ 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.		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:		post_install will determine JAVA_HOME based on the following rules:

imported>Jason.nicholls at 10:47, 18 July 2014

2014-07-18T10:47:26Z

← Older revision		Revision as of 10:47, 18 July 2014
Line 1:		Line 1:
	{{DISPLAYTITLE:Linux / UNIX Installation}}		{{DISPLAYTITLE:Linux / UNIX Installation}}
	[[Category:AppBoard 2.4]]		[[Category:AppBoard 2.4]]
	===Prerequisites===		==Prerequisites==
	# Install the JRE (Java Runtime Environment) or JDK (Java Development Kit) 1.6 or higher		# Install the JRE (Java Runtime Environment) or JDK (Java Development Kit) 1.6 or higher
	# Install unzip		# Install unzip
Line 7:		Line 7:
	{{Note\|AppBoard 2.4.1 and prior also require the <tt>lsb-release</tt> executable installed on Linux to correctly identify the distribution. This is not necessary for AppBoard 2.4.2 or newer.}}		{{Note\|AppBoard 2.4.1 and prior also require the <tt>lsb-release</tt> executable installed on Linux to correctly identify the distribution. This is not necessary for AppBoard 2.4.2 or newer.}}

	===Installation Tasks===		==Installation Tasks==
	# Extract the turnkey installation archive to the desired location on the server. For example:		# Extract the turnkey installation archive to the desired location on the server. For example:
	## <tt>$ mkdir /opt/appboard</tt>		## <tt>$ mkdir /opt/appboard</tt>
Line 15:		Line 15:
	# Run the post installation tasks.		# Run the post installation tasks.

	===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. <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.		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.
Line 28:		Line 28:
	# [optional] AppBoard comes with a pre-configured H2 database for storing configuration. An external configuration database can also be used, see the [[appboard/2.4/admin/configuration_database\|Configuration Database]] page for more information.		# [optional] AppBoard comes with a pre-configured H2 database for storing configuration. An external configuration database can also be used, see the [[appboard/2.4/admin/configuration_database\|Configuration Database]] page for more information.

	~~<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.		=== post_install Details ===

	The script ~~will check for JAVA_HOME and use $JAVA_HOME/bin~~/~~java~~. ~~If a valid java installation~~ is ~~not discovered, the script will then check the user's path, instead~~. ~~Detection is done in this order/preference:~~		The post_install script managed the following environment variables which are updated into <tt>setenv-custom.sh</tt>. It is recommended to re-run post_install to make changes.

	~~# Previously used JAVA_HOME as saved in setenv-custom.sh (only if upgrading).~~		* <tt>TOMCAT_USER</tt>
	#* <i>~~Note that if JAVA_HOME refers to a valid Java installation, AppBoard saves the value of this environment variable in setenv-custom.sh.~~</i>		* <tt>TOMCAT_SERVICE</tt>
	# JAVA_HOME ~~from your env~~		* <tt>USE_JSVC</tt>
	~~# java from your path ($ which java)~~		* <tt>JAVA_HOME</tt>
	~~# JRE_HOME from your env~~

	===Verifying the Installation===		<tt>JAVA_HOME</tt> 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 can be specifified (such as <tt>/usr/bin/java</tt> but something more involved saved as JAVA_HOME into setenv-custom.sh. In the worst case setenv-custom.sh can be edited after running post_install to ensure the desired value.

			==Verifying the Installation==

	# Start AppBoard/enPortal:		# Start AppBoard/enPortal:

imported>Jason.nicholls: /* Post Installation Tasks */

2014-07-18T10:29:46Z

Post Installation Tasks

← Older revision		Revision as of 10:29, 18 July 2014
Line 25:		Line 25:
	# 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 runtime options. Refer to the [[appboard/2.4/admin/runtime_options\|Runtime Options]] page for further information. Please ~~also~~ note that some options are managed by the post_install script, see ~~below~~.		# [optional] Make changes to the default ports, java memory tuning, and runtime options. Refer to the [[appboard/2.4/admin/runtime_options\|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 [[appboard/2.4/admin/configuration_database\|Configuration Database]] page for more information.

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

imported>Andy.hopper: /* Post Installation Tasks */

2014-06-05T15:14:13Z

Post Installation Tasks

← Older revision		Revision as of 15:14, 5 June 2014
Line 29:		Line 29:
	<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.		<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:		The script will check for JAVA_HOME and use $JAVA_HOME/bin/java. If a valid java installation is not discovered, the script will then check the user's path, instead. Detection is done in this order/preference:

	# Previously used JAVA_HOME as saved in setenv-custom.sh (only if upgrading).		# Previously used JAVA_HOME as saved in setenv-custom.sh (only if upgrading).

imported>Andy.hopper: /* Post Installation Tasks */

2014-06-05T15:10:24Z

Post Installation Tasks

← Older revision		Revision as of 15:10, 5 June 2014
Line 31:		Line 31:
	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:

			# Previously used JAVA_HOME as saved in setenv-custom.sh (only if upgrading).
			#* <i>Note that if JAVA_HOME refers to a valid Java installation, AppBoard saves the value of this environment variable in setenv-custom.sh.</i>
			# JAVA_HOME from your env
	# java from your path ($ which java)		# java from your path ($ which java)
	~~# JAVA_HOME from your env~~
	# JRE_HOME from your env		# JRE_HOME from your env

← Older revision		Revision as of 10:55, 18 July 2014
Line 50:		Line 50:
	==Verifying the Installation==		==Verifying the Installation==

	# Start AppBoard~~/enPortal~~:		# Start AppBoard:
	#* 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>[INSTALL_HOME]/server/bin</tt> directory: <tt>./startup.sh</tt>		#* Or start on the command line from the <tt>[INSTALL_HOME]/server/bin</tt> directory: <tt>./startup.sh</tt>
Line 61:		Line 61:
	===Starting on Boot===		===Starting 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.		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~~/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]/server/bin/helpers</tt> directory: <tt>$ ./unix_services.sh remove</tt>		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>[INSTALL_HOME]/server/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~~/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 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~~/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 [[appboard/2.4/admin/runtime_options\|Runtime Options]]). It will be necessary to restart AppBoard~~/enPortal~~ for these changes to take effect.		* 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 <tt>setenv-custom.sh</tt> (see [[appboard/2.4/admin/runtime_options\|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).		** 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. On Linux systems, this can be achieved using iptables.