Enportal/5.4/admin/enPortal installation/backup and recovery - Revision history

imported>Jason.nicholls at 12:42, 20 July 2014

2014-07-20T12:42:23Z

← Older revision		Revision as of 12:42, 20 July 2014
Line 1:		Line 1:
	[[Category:enPortal 5.4]]		[[Category:enPortal 5.4]]
	{{DISPLAYTITLE:enPortal Backup & Recovery}}		{{DISPLAYTITLE:enPortal Backup & Recovery}}
			==Overview==
	A typical enPortal deployment will consist of:		A typical enPortal deployment will consist of:

Line 6:		Line 7:
	# custom assets on the file system such as configuration files.		# custom assets on the file system such as configuration files.
	# external supporting pieces required for operation but not strictly part of enPortal.		# external supporting pieces required for operation but not strictly part of enPortal.
	~~<br>~~

	enPortal provides a configurable export system which will automatically capture all system configuration (1) and much of the custom assets (2). If custom assets are not captured then the export configuration can be modified to include them which would be considered a deployment best practice. Exporting the external supporting pieces (3) is beyond the scope of the product itself but should be considered from an overall perspective.		enPortal provides a configurable export system which will automatically capture all system configuration (1) and much of the custom assets (2). If custom assets are not captured then the export configuration can be modified to include them which would be considered a deployment best practice. Exporting the external supporting pieces (3) is beyond the scope of the product itself but should be considered from an overall perspective.
	~~<br>~~
	The reasons for performing backups are:		The reasons for performing backups are:

Line 16:		Line 16:
	* use a backup when upgrading enPortal itself.		* use a backup when upgrading enPortal itself.
	* provide a way for Edge to further investigate support issues - a backup archive may be requested.		* provide a way for Edge to further investigate support issues - a backup archive may be requested.
	~~<br>~~


	== Creating Backups ==		== Creating Backups ==
Line 31:		Line 29:

	=== Backup Options ===		=== Backup Options ===

	{\|class="wikitable"		{\|class="wikitable"
	! Backup Type		! Backup Type
Line 45:		Line 42:
	\| This is a special purpose backup that will export most server configuration and all enPortal configuration.		\| This is a special purpose backup that will export most server configuration and all enPortal configuration.
	\|}		\|}

	*''Backup AppBoard'' Option		*''Backup AppBoard'' Option
	The ''Backup AppBoard'' option backs up only AppBoard components, specifically: Stacks, Data Collections, and Data Sources. Everything else including server configuration, users, domains, roles, stack assignment, managed variables, and all enPortal specific custom export properties are '''not backed up'''.		The ''Backup AppBoard'' option backs up only AppBoard components, specifically: Stacks, Data Collections, and Data Sources. Everything else including server configuration, users, domains, roles, stack assignment, managed variables, and all enPortal specific custom export properties are '''not backed up'''.
Line 54:		Line 50:
	*''Backup Portal'' Option		*''Backup Portal'' Option
	Use the ''Backup Portal'' option to export all enPortal configuration in addition to most of the server configuration.		Use the ''Backup Portal'' option to export all enPortal configuration in addition to most of the server configuration.


	=== Customizing the Export ===		=== Customizing the Export ===

	Recommended best practice is to ensure that backups include all required files for a functioning system. In many cases this is handled automatically by placing custom files within the supplied ''custom'' directories. Some files fall outside this pattern however and to handle these it's necessary to customize the export file set by creating a <tt>custom.properties</tt> file and placing it into the <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/</tt> directory.		Recommended best practice is to ensure that backups include all required files for a functioning system. In many cases this is handled automatically by placing custom files within the supplied ''custom'' directories. Some files fall outside this pattern however and to handle these it's necessary to customize the export file set by creating a <tt>custom.properties</tt> file and placing it into the <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/</tt> directory.

Line 75:		Line 69:

	=== Unattended Backups ===		=== Unattended Backups ===

	The backup mechanism is only accessible via the web interface.		The backup mechanism is only accessible via the web interface.
	To perform an unattended backup, create a custom script to authenticate and call the following URL to generate the backup (example below calls the ''Backup All'' option):		To perform an unattended backup, create a custom script to authenticate and call the following URL to generate the backup (example below calls the ''Backup All'' option):
Line 82:		Line 75:

	== Loading Backups (archives) ==		== Loading Backups (archives) ==

	Loading backup archives is completed on the command line and the enPortal server must be shutdown beforehand.		Loading backup archives is completed on the command line and the enPortal server must be shutdown beforehand.
	Before proceeding with loading a backup, please be aware that this process is disruptive and will replace the existing configuration. For example, loading a ''Backup All'' archive will replace all existing enPortal and AppBoard content and configuration settings.		Before proceeding with loading a backup, please be aware that this process is disruptive and will replace the existing configuration. For example, loading a ''Backup All'' archive will replace all existing enPortal and AppBoard content and configuration settings.
Line 93:		Line 85:
	# (Linux / UNIX) re-run <tt>post_install.sh</tt>		# (Linux / UNIX) re-run <tt>post_install.sh</tt>
	# start enPortal		# start enPortal
	~~<br>~~

	The applicable Load Types are defined below:		The applicable Load Types are defined below:

	{\|class="wikitable~~" border="1" style="background-color:#eeeeee;~~"		{\|class="wikitable"
	!Load Type		!Load Type
	!Description		!Description
Line 121:		Line 112:

	== Troubleshooting ==		== Troubleshooting ==
	~~<br>~~		{\|class="wikitable"
	{\|class="wikitable~~" border="1" style="background-color:#eeeeee;~~"
	!Issue		!Issue
	!Possible Causes		!Possible Causes

imported>Jason.nicholls: /* Creating Backups */

2014-07-20T12:39:24Z

Creating Backups

← Older revision		Revision as of 12:39, 20 July 2014
Line 22:		Line 22:

	To create backups, hover your mouse over the '''Advanced''' tab and select the ''Backup'' option.		To create backups, hover your mouse over the '''Advanced''' tab and select the ''Backup'' option.
	~~<br>~~
	[[File:~~Enp5_4AdvMenu~~.~~PNG~~\|~~center\|1400px~~\|Backup ~~page~~]]		[[File:enportal-5.4-backup.png\|frame\|Advanced -> Backup]]
	~~<br>~~

	The Backup page allows the user to create new backups, and download or delete existing backups on the server file system.		The Backup page allows the user to create new backups, and download or delete existing backups on the server file system.
Line 31:		Line 31:

	=== Backup Options ===		=== Backup Options ===
	~~<br>~~
	{\|class="wikitable~~" border="1" style="background-color:#eeeeee;~~"		{\|class="wikitable"
	! Backup Type		! Backup Type
	! Description		! Description

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:50, 13 December 2013

2013-12-13T22:50:51Z

New page

[[Category:enPortal 5.4]]
{{DISPLAYTITLE:enPortal Backup & Recovery}}
A typical enPortal deployment will consist of:

# application configuration: users, domains, provisioning information, etc.
# custom assets on the file system such as configuration files.
# external supporting pieces required for operation but not strictly part of enPortal.
 

enPortal provides a configurable export system which will automatically capture all system configuration (1) and much of the custom assets (2). If custom assets are not captured then the export configuration can be modified to include them which would be considered a deployment best practice. Exporting the external supporting pieces (3) is beyond the scope of the product itself but should be considered from an overall perspective.
 
The reasons for performing backups are:

* adhere to backup maintenance good practices.
* provide a mechanism to migrate configuration from one environment to another (for example from development, to staging, to production).
* use a backup when upgrading enPortal itself.
* provide a way for Edge to further investigate support issues - a backup archive may be requested.
 

== Creating Backups ==

To create backups, hover your mouse over the '''Advanced''' tab and select the ''Backup'' option.
 
[[File:Enp5_4AdvMenu.PNG|center|1400px|Backup page]]
 

The Backup page allows the user to create new backups, and download or delete existing backups on the server file system.

Select the ''Create'' button to create a new backup. Multiple backup options will be presented.

=== Backup Options ===
 
{|class="wikitable" border="1" style="background-color:#eeeeee;"
! Backup Type
! Description
|-
| Backup All
| This will backup everything and is typically the form of backup required even if only using AppBoard features. ['''recommended''']
|-
| Backup AppBoard
| This is a special purpose backup that will only export AppBoard content - see below for further information.
|-
| Backup Portal
| This is a special purpose backup that will export most server configuration and all enPortal configuration.
|}

*''Backup AppBoard'' Option
The ''Backup AppBoard'' option backs up only AppBoard components, specifically: Stacks, Data Collections, and Data Sources. Everything else including server configuration, users, domains, roles, stack assignment, managed variables, and all enPortal specific custom export properties are '''not backed up'''.

*''Backup All'' Option
Use the ''Backup All'' option for full system backups.

*''Backup Portal'' Option
Use the ''Backup Portal'' option to export all enPortal configuration in addition to most of the server configuration.

=== Customizing the Export ===

Recommended best practice is to ensure that backups include all required files for a functioning system. In many cases this is handled automatically by placing custom files within the supplied ''custom'' directories. Some files fall outside this pattern however and to handle these it's necessary to customize the export file set by creating a <tt>custom.properties</tt> file and placing it into the <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/</tt> directory.

This file can be used for various overrides so it may exist for other purposes already. The key part is to define an <tt>export.custom.other</tt> property with the list of files to be exported, so for example:

<pre>
# below is a list of additional files to export on a full backup
export.custom.other=${webapp.webinf}/lib/mysql-connector-java-5.1.19.jar;\
${webapp.webinf}/lib/jtds-1.2.4.jar;\
${webapp.xmlroot}/appboard/config/iconregistry/custom_icons.csv;\
${webapp.home}/visualizer/assets/images/custom_banner_logo.png;
</pre>

In this example two DB driver files, a icon registry file, and a custom graphic will be included in the export.

To verify the export contains the files, perform a backup and simply unzip the file to inspect (or rename to <tt>.zip</tt>).

=== Unattended Backups ===

The backup mechanism is only accessible via the web interface.
To perform an unattended backup, create a custom script to authenticate and call the following URL to generate the backup (example below calls the ''Backup All'' option):

<tt>/enportal/servlet/pd/vdir/home/role/portalAdministration/Menu/Admin/Advanced/Backup?requestType=execute&Submit=true</tt>

== Loading Backups (archives) ==

Loading backup archives is completed on the command line and the enPortal server must be shutdown beforehand.
Before proceeding with loading a backup, please be aware that this process is disruptive and will replace the existing configuration. For example, loading a ''Backup All'' archive will replace all existing enPortal and AppBoard content and configuration settings.

To load an archive:

# shutdown enPortal
# in a terminal, change into the <tt>[INSTALL_HOME]/server/bin</tt> directory
# run: <tt>portal ''<Load_Type>'' -jar ''<backup_archive.jar>''</tt>
# (Linux / UNIX) re-run <tt>post_install.sh</tt>
# start enPortal
 

The applicable Load Types are defined below:

{|class="wikitable" border="1" style="background-color:#eeeeee;"
!Load Type
!Description
|-
| Restore
| This command will load an archive effectively creating a "mirror" of the original install. If this is on a different host then the license key and runtime configuration may need to be updated. Alternatively use the ''Apply'' command.
|-
| Apply
| This command is intended when moving an archive from one host to another, but it will not preserve the license file, SSL configuration, or other runtime configuration (<tt>setenv-custom.sh</tt>). The host where the ''Apply'' is run will need to have its own configuration already set up otherwise enPortal will not start (i.e. no license).
|}

{{Note|Regardless of a ''Restore'' or ''Apply'', on Linux / UNIX platforms it is recommended to re-run <tt>post_install.sh</tt>. See [[enportal/5.4/admin/unix_installation|Linux / UNIX Installation - Restoring an Archive]] for more information.}}

In addition, a special procedure is required to load an AppBoard only backup onto an existing server without losing other configuration, i.e. this is not necessary for a clean AppBoard installation. Instead of a ''Restore'' or ''Apply'' command, the ''FilesImport'' command should be used. This will overlay the files onto the file system without resetting the configuration database. All AppBoard content will be replaced however. The following steps are also required to ensure data sources are loaded correctly:

# Shutdown AppBoard.
# In a terminal change into the <tt>[INSTALL_HOME]\server\bin\</tt> directory.
# Enter the command: <tt>portal FilesImport -jar <appboard-only-archive.jar></tt>
# Change into the <tt>[INSTALL_HOME]\server\webapps\enportal\WEB-INF\xmlroot\appboard\</tt> directory.
# Rename <tt>load-restore.txt.disabled</tt> to <tt>load-restore.txt</tt>.
# Start AppBoard.

== Troubleshooting ==
 
{|class="wikitable" border="1" style="background-color:#eeeeee;"
!Issue
!Possible Causes
|-
| When restoring an archive, you receive the following message in the console:
<tt>System must be shutdown prior to resetting the database</tt>.
|
* enPortal is still running. Make sure enPortal is shut down prior to running the restore command.
* The system was improperly shut down and there is a lock file in the H2 folder (/server/webapps/enportal/WEB-INF/h2/).Delete the lock file (persist.lock.db) and run the restore command again.
|}