Edge Documentation

{{DISPLAYTITLE:Backup & Recovery}}
[[Category:AppBoard 2.6]]
== Overview ==

A typical AppBoard deployment will consist of:

# application configuration: stacks, boards, widgets, users, domains, provisioning information etc...
# custom assets on the filesystem such as icons, logos, and additional configuration files.
# external supporting pieces required for operation but not strictly part of AppBoard, such as an additional external database, scripts, etc...

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

As for external supporting pieces that's beyond the scope of the product itself but should be considered from a overall perspective.

The reasons for performing backups are:

* it's best practices to keep backups
* provide a mechanism to migrate configuration from one environment to another, for example from development, to staging, to production.
* used when upgrading AppBoard itself.
* used in cluster configurations (refer to [[appboard/2.6/admin/clustering_and_failover|Clustering & Failover]])
* provide a way for Edge to further investigate support issues - sometimes we may request a backup archive.


== Creating Backups ==

Creating backups is done by navigating to the ''System Administration'' builder mode, and selecting the ''Backup'' icon.

[[File:appboard-2.4-backup.png|thumb|750px|Backup system administration page]]

This page allows new backups to be created as well as existing backups on the server filesystem to be downloaded or deleted.

Select the ''Create'' button to create a new backup, the following options will be presented:

{|class='wikitable'
! Backup&nbsp;Type
! Description
|-
| Backup All
| ('''recommended''') This will backup everything and is typically the form of backup required even if only using AppBoard features.
|-
| 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'''.

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

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

# Shut down 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.

=== 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 a list of rules defining the files to export. This is a semi-colon (<tt>;</tt>) separated list, with the backslash character (<tt>\</tt>) used to split the list over multiple lines to improve readability. 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.34.jar;\
                    ${webapp.xmlroot}/appboard/config/iconregistry/custom_icons.csv;\
                    ${webapp.home}/visualizer/assets/images/custom_banner_logo.png;\
                    ${webapp.home}/framework/laf/banner_my_custom_laf;\
                    ${webapp.webinf}/test_dir;\
                    ${webapp.webinf}/image_dir,,,.*\.png
</pre>

In this example a DB driver, a icon registry file, a custom graphic, a custom Look and Feel (LAF), and the <tt>test_dir</tt> are specific paths to be exported. The last example specifies a path and file expression so that only files ending with <tt>.png</tt> are included.

The format for each export rule is noted below. The initial <tt>Path</tt> is not a regular expression and must match exactly a single file or directory. <tt>PathExpression</tt> and <tt>FileExpression</tt> are ''regular expressions'', not wildcards. The use of the <tt>exclude</tt> keyword is optional and implies the preceding expression should be excluded.

<pre>
<Path>,<PathExpression>,exclude,<FileExpression>,exclude,<FileExpression>,exclude,...
</pre>


After making changes to the set of excludes perform a backup and verify the resulting (.jar) archive contains the desired set of files. The archive can be uncompressed using unzip, depending on the unzip tool it may need to be renamed to end with <tt>.zip</tt>.

=== Unattended Backups ===
The backup mechanism is only accessible via the web interface. In order to perform a backup unattended it is necessary to create a custom script to authenticate and call the following URL to generate the backup, in this case it would be 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 AppBoard server must be shutdown beforehand. This process is disruptive and will replace the existing configuration - be sure that is what you want to do. Specifically all enPortal and AppBoard content and configuration will be replaced (assuming a ''Backup All'' archive).


{{Warning|Loading archives created from a newer version of AppBoard onto an older version of AppBoard is '''not supported'''. While it may be ''possible'' to load the archive it may lead to unknown configuration issues.}}


The process to load an archive:

# shutdown AppBoard
# 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><br>This is required to ensure correct system configuration and file ownership, permissions, and any included scripts are set executable as jar archives do not store this information.
# start AppBoard

The applicable Load Types are defined below:

{|class='wikitable'
!Load&nbsp;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 and intended to preserve the host specific configuration. Any license file, SSL configuration, configuration database setting, or other runtime configuration (<tt>setenv-custom.sh</tt>) included in the archive will be ignored. The host where the ''Apply'' is run will need to have this configuration already set up otherwise AppBoard will not start (i.e. no license). 
|}

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

== Troubleshooting ==

*<b>Issue:</b> When restoring an archive, you receive the following message in the console: <tt>System must be shutdown prior to resetting the database.</tt>
*<b>Possible Causes</b>:
** AppBoard is still running.  Make sure AppBoard 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.

{{Note|AppBoard stores widget configuration in XML which cannot contain some non-printable characters. If such characters are identified during a backup or restore operation, they will be removed to avoid runtime errors. However, introducing such characters is not a pitfall that users would typically fall into: the board or widget configuration itself would have to contain the non-printable characters.}}