Appboard/2.4/admin/backup and recovery: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
 
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Backup & Recovery}}
{{DISPLAYTITLE:Backup & Recovery}}
[[Category:AppBoard 2.4]]
A typical AppBoard deployment will consist of:


== Backup ==
# 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...


There are several reasons that the AppBoard/enPortal administrator may need to create a backup of the system:
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.


* Migrating a system from development to production, or from one physical location to another
The reasons for performing backups are:
* Upgrading the system to a newer version
* Creating a regular backup to have available in case the system ceases to function properly


* 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.
* provide a way for Edge to further investigate support issues - sometimes we may request a backup archive.


===How To Create a Backup===
== Creating Backups ==


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


Perform the following steps to create a full backup of AppBoard/enPortal:
[[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.


# On the original AppBoard system, log in to AppBoard as administrator.
Select the ''Create'' button to create a new backup, the following options will be presented:
# Under <b>Builder Modes</b>, select <b>Settings</b>.
# Under <b>System Settings</b>, select <b>Backup</b>.
# Click <b>Create</b>.
# Select the desired backup option and click <b>Create Backup</b>:
## <b>Backup All</b> - [Recommended] Backs up all AppBoard and enPortal content
## <b>Backup AppBoard</b> - Backs up only AppBoard components such as configuration of Stacks, Widgets, Data Sources, and adapters
##* See additional notes in section below - "AppBoard-only Backups"
## <b>Backup Portal</b> - Backs up only system configuration, including the following:
##* setenv-custom configuration settings
##* SSL certificate files
##* other system configuration files
# Observe the JAR file created in <tt>\server\webapps\enportal\WEB-INF\archive\</tt>.  The filename contains a timestamp, so previous backups are not erased, and so you can differentiate between different backups and when they were generated.




=== AppBoard-only Backups ===
{|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.
|}


The <b>Backup AppBoard</b> option backs up only AppBoard components.  When performing an AppBoard-only backup, only Stacks, Data Collections, and Data Sources are backed up. Users, Domains, Roles, Stack assignments, and managed variables are not included with the backup. As a result, do not use the <tt>portal Restore</tt> command with an appboard-only archive as the Restore command resets the database and you may lose user/role/variable and all enPortal configuration.




If you are trying to get a complete system backup and restore, then use the full <b>Backup All</b> backup and restore method, not the AppBoard-only backup.
=== ''Backup AppBoard'' Option ===
To load an AppBoard-only backup over an existing installation, then use the <tt>portal FilesImport</tt> command instead of <tt>portal Restore</tt>. It will also be necessary to perform an additional step to ensure data source modifications are loaded:


#Shut down AppBoard.
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'''.
#On the command line in the destination system, go to ...\server\bin\.
#Enter the command: portal FilesImport -jar <appboard-only-archive.jar>.
#Change into the ...\server\webapps\enportal\WEB-INF\xmlroot\appboard\ directory.
#Rename load-restore.txt.disabled to load-restore.txt.
#Start AppBoard.


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


==Restore==
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:


The restore process enables you to install a new version of AppBoard/enPortal and restore your previous data and configurations.
# 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 ===


===How To Restore AppBoard/enPortal===
Recommended best practices 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.


# Shut down AppBoard.
This file can be used for various overrides so may exist for other purposes already. The key part is to define a <tt>export.custom.other</tt> property with the list of files to be exported. 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:
# On the command line in the destination system, go to <tt>\server\bin\</tt>.
# Enter one of the following commands:
#:  <tt>Portal restore –jar ..\webapps\enportal\WEB-INF\archive\<<i>name of backup jar file</i>></tt>
#:* The "restore" command is intended for doing a complete rebuild of AppBoard, such as when you are migrating AppBoard to a new server or upgrading to a new AppBoard version.  It will copy all of the files from the archive JAR on to the destination server where you are running the command.
#:  <tt>Portal apply –jar ..\webapps\enportal\WEB-INF\archive\<<i>name of backup jar file</i>></tt>
#:* The "apply" command skips over copying some of the config files from the archive JAR.  It can be used, for example, if you are loading an archive on to a test server and you do not want the command to extract all of the system configuration settings and wipe out the local settings that are in place (for example, the license file).  The list of files that is skipped by the apply command can be seen (and configured) in <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/export.properties</tt> under the section labeled "import.skip.apply".
# Enter “yes” to confirm replacing any existing content.
# Start AppBoard and confirm that the exported content was loaded successfully.




==== Deciding Whether To Use the "Apply" or "Restore" Command ====
<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>


When to use "portal apply":
In this example two DB driver files, a icon registry file, and a custom graphic will be included in the export.
* You do not want any customization to affect your local /server/bin/setenv-custom scripts (port overrides; memory settings, etc).
* You do not want /server/webapps/enportal/WEB-INF/config/license.properties or any license.* files to affect your local server settings.
* You do not want SSL configuration changes in /server/conf/ to affect your local server settings.
* You only want elements such as Stacks, Channels, Users, or personalizations to be imported.


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


When to use "portal restore":
=== Unattended Backups ===
* You want the restore to truly mirror the full configuration from the original server where the backup archive was created.


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:


Note: In both cases (portal restore and portal apply), the command will reset the database.  Once started, the system will only load the stock configurations plus the configurations imported by the overlay.
<tt>/enportal/servlet/pd/vdir/home/role/portalAdministration/Menu/Admin/Advanced/Backup?requestType=execute&Submit=true</tt>


{{Note|If you are migrating an archive from version 2.2.x to version 2.3.x or higher, certain database drivers that were bundled with previous versions of Appboard are no longer included. After restoring the archive, you need to copy the driver from [AppBoard_Home]/server/webapps/enportal/WEB-INF/lib/ and save it into this same location on the new server. For example, to use MySQL you would need to copy the JDBC driver file (such as mysql-connector-java-5.1.19.jar) into the /lib/ directory of the new server. The error message indicating a missing driver would be "Please install missing [drivertype] Driver" on the screen and in Appboard.log.  Tip: If you rename a database driver file to pkg-<libraryName>.jar, it will be preserved and migrated in archives generated by AppBoard.}}
== Loading Backups (archives) ==


{{Note|On Unix systems, after restoring an archive you need to verify that some of the server settings are correct. For more information, see [[UnixInstallation#Restoring_an_Archive|Unix Installation - restoring an archive]]}}
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).


== Advanced Configuration ==
The process to load an archive:


The set of files that are included in the backup archive is configured in the file <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/export-appboard.properties</tt> and <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/export.properties</tt>.  You can customize the process by adding files to be included in the backup archive.  To do so, create a file called <tt>custom.properties</tt>, and include any custom export commands.
# 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>
# start AppBoard


The applicable Load Types are defined below:


The following is a sample customization block that could be added to <tt>custom.properties</tt>:
{|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, 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 this configuration already set up otherwise AppBoard will not start (i.e. no license).
|}


<code>[xml,N]
# Backup custom theme
export.custom.other=${webapp.webinf}/xmlroot/appboard/config/themes.xml;\
        ${webapp.home}/visualizer/assets/images/backgrounds/bg-red_1600.png;\
        ${webapp.home}/visualizer/assets/images/my_banner.png;\
        ${webapp.home}/login_pages/edgeLight/images/logo.png;\
        ${webapp.webinf}/lib/db2jcc.jar;\
        ${webapp.webinf}/lib/db2jcc_license_cu.jar;\
        ${webapp.home}/version.jsp;\
        ${webapp.webinf}/groovy-script/TrimSiteCode.groovy;
export-appboard.data=${webapp.webinf}/data
</code>


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


== Troubleshooting ==
== Troubleshooting ==
Line 114: Line 119:
** AppBoard is still running.  Make sure AppBoard is shut down prior to running the restore command.
** 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.
** 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.}}

Latest revision as of 15:14, 29 September 2014

A typical AppBoard deployment will consist of:

  1. application configuration: stacks, boards, widgets, users, domains, provisioning information etc...
  2. custom assets on the filesystem such as icons, logos, and additional configuration files.
  3. 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.
  • 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.

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:


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

  1. Shut down AppBoard.
  2. In a terminal change into the [INSTALL_HOME]\server\bin\ directory.
  3. Enter the command: portal FilesImport -jar <appboard-only-archive.jar>
  4. Change into the [INSTALL_HOME]\server\webapps\enportal\WEB-INF\xmlroot\appboard\ directory.
  5. Rename load-restore.txt.disabled to load-restore.txt.
  6. Start AppBoard.

Customizing the Export

Recommended best practices 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 custom.properties file and placing it into the [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/ directory.

This file can be used for various overrides so may exist for other purposes already. The key part is to define a export.custom.other property with the list of files to be exported. This is a semi-colon (;) separated list, with the backslash character (\) used to split the list over multiple lines to improve readability. For example:


# 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

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 then perform a backup and simply unzip the file to inspect (or rename to .zip).

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:

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

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

The process to load an archive:

  1. shutdown AppBoard
  2. in a terminal, change into the [INSTALL_HOME]/server/bin directory
  3. run: portal <Load_Type> -jar <backup_archive.jar>
  4. (Linux / UNIX) re-run post_install.sh
  5. start AppBoard

The applicable Load Types are defined below:

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 (setenv-custom.sh). 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).


Template-note.png
Regardless of a Restore or Apply, on Linux / UNIX platforms it is recommended re-run post_install.sh. See Linux / UNIX Installation - Restoring an Archive for more information.

Troubleshooting

  • Issue: When restoring an archive, you receive the following message in the console: System must be shutdown prior to resetting the database.
  • Possible Causes:
    • 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.
Template-note.png
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.