Appboard/old/unix installation - Revision history

imported>Jason.nicholls: /* Binding to Port <1024 as non-root */

2014-07-17T11:30:07Z

Binding to Port <1024 as non-root

← Older revision		Revision as of 11:30, 17 July 2014
Line 61:		Line 61:
	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/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. To change the listening port then edit the HTTP_PORT value in <tt>setenv-custom.sh</tt> (see [[~~Runtime_Options~~\|Runtime Options]]). It will be necessary to restart AppBoard/enPortal 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. To change the listening port then edit the HTTP_PORT value in <tt>setenv-custom.sh</tt> (see [[appboard/old/runtime_options\|Runtime Options]]). 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/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 ===		=== Restoring an Archive ===

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

2014-07-17T11:29:36Z

Post Installation Tasks

← Older revision		Revision as of 11:29, 17 July 2014
Line 28:		Line 28:
	# 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 [[~~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/old/runtime_options\|Runtime Options]] page for further information. Please also note that some options are managed by the post_install script, see below.

	<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.
Line 37:		Line 37:
	# JAVA_HOME from your env		# JAVA_HOME from your env
	# JRE_HOME from your env		# JRE_HOME from your env


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

imported>Jason.nicholls: /* Restoring an Archive */

2014-07-17T10:38:54Z

Restoring an Archive

← Older revision		Revision as of 10:38, 17 July 2014
Line 69:		Line 69:
	=== Restoring an Archive ===		=== Restoring an Archive ===

	The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see [[~~Backup_and_Restore~~\|Backup and Restore]]) it actually replaces files on the filesystem and you '''must''' review:		The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see [[appboard/old/backup_and_restore\|Backup and Restore]]) it actually replaces files on the filesystem and you '''must''' review:

	# If using a ''Restore'' then <tt>setenv-custom.sh</tt> is replaced		# If using a ''Restore'' then <tt>setenv-custom.sh</tt> is replaced
Line 76:		Line 76:

	The recommendation whether restoring with a ''Restore'' or ''Apply'' is to re-run <tt>post_install.sh</tt> after the import completes. In cases where the archive originates from a different system then ''Apply'' is the recommended import command.		The recommendation whether restoring with a ''Restore'' or ''Apply'' is to re-run <tt>post_install.sh</tt> after the import completes. In cases where the archive originates from a different system then ''Apply'' is the recommended import command.


	== Stopping AppBoard ==		== Stopping AppBoard ==

imported>Jason.nicholls: /* Stopping AppBoard */

2014-07-17T07:17:30Z

Stopping AppBoard

← Older revision		Revision as of 07:17, 17 July 2014
Line 81:		Line 81:
	To stop AppBoard, terminate the Tomcat process that is running on the AppBoard server.		To stop AppBoard, terminate the Tomcat process that is running on the AppBoard server.

	{{Warning\|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_Management~~\|Session Manager]].}}		{{Warning\|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 [[appboard/old/session_management\|Session Manager]].}}

	* For instances running as a system service make sure it is shutdown as a service, i.e.		* For instances running as a system service make sure it is shutdown as a service, i.e.

imported>Jason.nicholls at 05:08, 17 July 2014

2014-07-17T05:08:07Z

← Older revision		Revision as of 05:08, 17 July 2014
Line 1:		Line 1:
	{{DISPLAYTITLE:Linux / UNIX Installation}}		{{DISPLAYTITLE:Linux / UNIX Installation}}
			[[Category:AppBoard old]]

	===Prerequisites===		===Prerequisites===

imported>Jason.nicholls: moved UnixInstallation to appboard/old/unix installation

2014-07-17T05:05:59Z

moved UnixInstallation to appboard/old/unix installation

← Older revision	Revision as of 05:05, 17 July 2014
(No difference)

imported>Jason.nicholls at 09:34, 5 July 2013

2013-07-05T09:34:28Z

← Older revision		Revision as of 09:34, 5 July 2013
Line 1:		Line 1:
	==Linux ~~and~~ UNIX Installation==		{{DISPLAYTITLE:Linux / UNIX Installation}}

	===Prerequisites===		===Prerequisites===

imported>Mike.berman: update for runtime options

2013-06-16T15:57:47Z

update for runtime options

← Older revision		Revision as of 15:57, 16 June 2013
Line 10:		Line 10:
	## <tt>$ mkdir /opt/appboard</tt>		## <tt>$ mkdir /opt/appboard</tt>
	## <tt>$ cd /opt/appboard</tt>		## <tt>$ cd /opt/appboard</tt>
	## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>		## <tt>$ unzip ''AppBoard-2.3.15.zip''</tt>
	# Save your license file into <tt>[INSTALL_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>
	# Run the post installation tasks.		# Run the post installation tasks.


	===Post Installation Tasks===		===Post Installation Tasks===
Line 28:		Line 27:
	# 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>~~[~~INSTALL_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 runtime options. Refer to the [[Runtime_Options\|Runtime Options]] page for further information. Please also note that some options are managed by the post_install script, see below.


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

			<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:		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:
Line 64:		Line 61:
	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/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~~ <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.		* 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 [[Runtime_Options\|Runtime Options]]). 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/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.
Line 71:		Line 68:
	=== Restoring an Archive ===		=== 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~~.		The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see [[Backup_and_Restore\|Backup and Restore]]) it actually replaces files on the filesystem and you '''must''' review:

			# If using a ''Restore'' then <tt>setenv-custom.sh</tt> 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 <tt>post_install.sh</tt> 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.

			{{Warning\|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_Management\|Session Manager]].}}

			* For instances running as a system service make sure it is shutdown as a service, i.e.
			*: <tt>$ /etc/init.d/appboard stop</tt>
			* When running on the command line then use:
			*: <tt>[INSTALL_HOME]/server/bin/stop.sh</tt>
			* When running attached to the console (<tt>./catalina.sh run</tt>) then use a CTRL+C signal to terminate.
			* As a general alternative locate the process and send a <tt>TERM</tt> signal.


	~~When [[Backup_and_Restore~~\|~~restoring from an archive]], there are a few items to consider and review:~~		{{Warning\|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.}}
	* 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~~.

imported>Mike.berman: add notes regarding lsb-release and JAVA_HOME

2013-04-01T09:58:57Z

add notes regarding lsb-release and JAVA_HOME

← Older revision		Revision as of 09:58, 1 April 2013
Line 1:		Line 1:
	==Linux and UNIX Installation==		==Linux and UNIX Installation==

			===Prerequisites===
			# Install the Java Development Kit (1.6 or later)
			# Install unzip
			# Install lsb-release (redhat-lsb for RHEL; lsb-release for Ubuntu, SuSE and Debian).

	===Installation Tasks===		===Installation Tasks===
	~~# Install the Java Development Kit~~
	# 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 8:		Line 12:
	## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>		## <tt>$ unzip ''AppBoard-2.2.0.zip''</tt>
	# Save your license file into <tt>[INSTALL_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>
			# Run the post installation tasks.


Line 14:		Line 19:
	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.

	~~# As~~ root, ~~change~~ into the <tt>[INSTALL_HOME]/bin/helpers</tt> directory
			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 <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>
Line 20:		Line 29:
	# 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>[INSTALL_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>[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.		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.


			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:

			# java from your path ($ which java)
			# JAVA_HOME from your env
			# JRE_HOME from your env

imported>Mike.berman: add Restoring an Archive section

2012-11-11T21:35:33Z

add Restoring an Archive section

← Older revision		Revision as of 21:35, 11 November 2012
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.