Enportal/5.4/admin/unix installation - Revision history

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

2014-07-18T11:45:59Z

Post Installation Tasks

← Older revision		Revision as of 11:45, 18 July 2014
Line 22:		Line 22:

	# Change into the <tt>[INSTALL_HOME]/server/bin/helpers</tt> directory		# Change into the <tt>[INSTALL_HOME]/server/bin/helpers</tt> directory
	# Run: <tt>$ ./post_install.sh</tt><br>If this script is not set executable, then run and try again: <tt>$ chmod u+x post_install.sh</tt>		# Run: <tt>$ ./post_install.sh</tt><br>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 runtime options. Refer to the [[enportal/5.4/admin/enPortal_installation/installation/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 [[enportal/5.4/admin/enPortal_installation/installation/runtime_options\|Runtime Options]] page for further information. Please note that some runtime options are managed by the post_install script.
			# [optional] enPortal comes with a pre-configured H2 database for storing configuration. An external configuration database can also be used, see the [[enportal/5.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 ===

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

	~~# java from your path ($ which java)~~		* <tt>TOMCAT_USER</tt>
	# JAVA_HOME ~~from your env~~		* <tt>TOMCAT_SERVICE</tt>
	~~# JRE_HOME from your env~~		* <tt>USE_JSVC</tt>
			* <tt>JAVA_HOME</tt>

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

	~~[optional] enPortal comes with a pre~~-~~configured H2 database for storing basic system information~~, ~~but this functionality~~ can be ~~achieved using other databases if desired~~. ~~To configure enPortal~~ to ~~use your own database, follow the instructions on the [[Database_Configuration\|Database Connection Configuration]] page~~.		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 <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: /* Prerequisites */

2014-03-31T05:26:21Z

Prerequisites

← Older revision		Revision as of 05:26, 31 March 2014
Line 2:		Line 2:
	{{DISPLAYTITLE:Linux / UNIX Installation}}		{{DISPLAYTITLE:Linux / UNIX Installation}}
	==Prerequisites==		==Prerequisites==
	# Install the Java Development Kit (1.6 or ~~later)~~		# Install the JRE (Java Runtime Environment) or JDK (Java Development Kit) 1.6 or higher
	# Install unzip		# Install unzip
	~~# Install lsb-release (redhat-lsb for RHEL; lsb-release for Ubuntu, SuSE and Debian).~~

	{{Note\|~~Some Linux distributions come with lsb-release/redhat-lsb installed by default~~. ~~Regardless of whether~~ lsb-release/~~redhat-lsb is~~ installed ~~by default or you are manually installing it, its existence on the system should be confirmed before moving~~ on to the ~~installation tasks~~.}}		{{Note\|enPortal 5.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 enPortal 2.4.2 or newer.}}

	==Installation Tasks==		==Installation Tasks==

imported>David.moore: /* Prerequisites */

2014-03-28T16:48:43Z

Prerequisites

← Older revision		Revision as of 16:48, 28 March 2014
Line 5:		Line 5:
	# Install unzip		# Install unzip
	# Install lsb-release (redhat-lsb for RHEL; lsb-release for Ubuntu, SuSE and Debian).		# Install lsb-release (redhat-lsb for RHEL; lsb-release for Ubuntu, SuSE and Debian).

			{{Note\|Some Linux distributions come with lsb-release/redhat-lsb installed by default. Regardless of whether lsb-release/redhat-lsb is installed by default or you are manually installing it, its existence on the system should be confirmed before moving on to the installation tasks.}}

	==Installation Tasks==		==Installation Tasks==

imported>Jason.nicholls: 1 revision

2013-12-19T15:17:44Z

1 revision

← Older revision	Revision as of 15:17, 19 December 2013
(No difference)

imported>Mylene.stolpe at 22:41, 17 December 2013

2013-12-17T22:41:05Z

New page

[[Category:enPortal 5.4]]
{{DISPLAYTITLE:Linux / 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==
# Extract the turnkey installation archive to the desired location on the server. For example:
## <tt>$ mkdir /opt/enPortal</tt>
## <tt>$ cd /opt/enPortal</tt>
## <tt>$ unzip ''enPortal-5.4.0.zip''</tt>
# Save your license file into <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/license.properties</tt>
# 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 enPortal to use (e.g. <tt>/usr/bin/java</tt>), what user to run enPortal as, and whether you wish to install a system service to automaticaly start/stop enPortal 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 <tt>[INSTALL_HOME]/server/bin/helpers</tt> directory
# Run: <tt>$ ./post_install.sh</tt><br>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.
# 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 [[enportal/5.4/admin/enPortal_installation/installation/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.

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

[optional] enPortal comes with a pre-configured H2 database for storing basic system information, but this functionality can be achieved using other databases if desired. To configure enPortal to use your own database, follow the instructions on the [[Database_Configuration|Database Connection Configuration]] page.

==Verifying the Installation==

# Start 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
#* Or start on the command line from the <tt>[INSTALL_HOME]/server/bin</tt> directory: <tt>./startup.sh</tt>
# Any errors will be logged into <tt>[INSTALL_HOME]/server/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</tt>. 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 enPortal automatically on boot)===

To have 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 enPortal installation directory has to be moved, or 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===

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

* Use JSVC to run 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 [[enportal/5.4/admin/enPortal_installation/installation/runtime_options|Runtime Options]]). It will be necessary to restart 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).
* 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 enPortal. On Linux systems, this can be achieved using iptables.

=== Restoring an Archive ===

The instructions above detail the procedures for a new installation. However, when restoring or applying an archive (see [[enportal/5.4/admin/enPortal_installation/backup_and_recovery|Backup and Recovery]]) 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 enPortal ==
To stop enPortal, terminate the Tomcat process that is running on the enPortal server.

{{Warning|When enPortal 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 enPortal server. Subsequent users will not be able to access the login page until enPortal is restarted. If you are stopping a production instance of enPortal, 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 enPortal before stopping it by using the [[enportal/5.4/admin/system_administration/manage_sessions|Session Manager]].}}

* For instances running as a system service make sure it is shutdown as a service, i.e.
*: <tt>$ service ''service_name'' stop</tt> or
*: <tt>$ /etc/init.d/enPortal 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.

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