Appboard/old/backup and restore: Difference between revisions

imported>Mike.berman
(add note regarding Unix additional steps)
imported>Jason.nicholls
No edit summary
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Note|The instructions on this page are for versions 2.2.x of AppBoard.  For versions 2.1.x of AppBoard, please see [[Backup_and_Restore_2.1.x|Backup and Restore 2.1.x]].  For versions 2.0.x of AppBoard, please see [[Backup_and_Restore_2.0.x|Backup and Restore 2.0.x]].}}
{{DISPLAYTITLE:Backup & Restore}}
 
[[Category:AppBoard old]]
AppBoard/enPortal provides utilities for backing up and restoring system data and configuration settings.  This page details the commands and procedures for managing this aspect of the system.
AppBoard/enPortal provides utilities for backing up and restoring system data and configuration settings.  This page details the commands and procedures for managing this aspect of the system.


Line 20: Line 20:




# On the original AppBoard system, log in to AppBoard as administrator
# On the original AppBoard system, log in to AppBoard as administrator.
# Under <b>Builder Modes</b>, select <b>Settings</b>
# Under <b>Builder Modes</b>, select <b>Settings</b>.
# Under <b>System Settings</b>, select <b>Backup</b>
# Under <b>System Settings</b>, select <b>Backup</b>.
# Click <b>Create</b>
# Click <b>Create</b>.
# Select <b>Backup All</b> and click <b>Create Backup</b>
# Select the desired backup option and click <b>Create Backup</b>:
# Observe JAR file created in <tt>\server\webapps\enportal\WEB-INF\archive\</tt>
## <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 ===
 
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.
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.
#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.




Line 35: Line 58:
===How To Restore AppBoard/enPortal===
===How To Restore AppBoard/enPortal===


# Shut down AppBoard
# Shut down AppBoard.
# On the command line in the destination system, go to <tt>\server\bin\</tt>
# On the command line in the destination system, go to <tt>\server\bin\</tt>.
# Enter the command:
# Enter one of the following commands:
#:  <tt>Portal restore –jar ..\webapps\enportal\WEB-INF\archive\<<i>name of backup jar file</i>></tt>
#:  <tt>Portal restore –jar ..\webapps\enportal\WEB-INF\archive\<<i>name of backup jar file</i>></tt>
# Enter “yes” to confirm replacing any existing content
#:* 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.
# Start AppBoard and confirm that the exported content was loaded successfully
#:  <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 ====
When to use "portal apply":
* 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.
When to use "portal restore":
* You want the restore to truly mirror the full configuration from the original server where the backup archive was created.
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.


{{Note|The license file is included in the JAR file that is created by the backup.  After executing a restore, you may need to manually replace the license file on the destination server with the appropriate file for that server.}}


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


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


== Advanced Configuration ==
== Advanced Configuration ==


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




Line 71: Line 110:
export-appboard.data=${webapp.webinf}/data
export-appboard.data=${webapp.webinf}/data
</code>
</code>
== 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.

Latest revision as of 10:35, 17 July 2014

AppBoard/enPortal provides utilities for backing up and restoring system data and configuration settings. This page details the commands and procedures for managing this aspect of the system.


Backup

There are several reasons that the AppBoard/enPortal administrator may need to create a backup of the system:


  • Migrating a system from development to production, or from one physical location to another
  • Upgrading the system to a newer version
  • Creating a regular backup to have available in case the system ceases to function properly


How To Create a Backup

Perform the following steps to create a full backup of AppBoard/enPortal:


  1. On the original AppBoard system, log in to AppBoard as administrator.
  2. Under Builder Modes, select Settings.
  3. Under System Settings, select Backup.
  4. Click Create.
  5. Select the desired backup option and click Create Backup:
    1. Backup All - [Recommended] Backs up all AppBoard and enPortal content
    2. Backup AppBoard - Backs up only AppBoard components such as configuration of Stacks, Widgets, Data Sources, and adapters
      • See additional notes in section below - "AppBoard-only Backups"
    3. Backup Portal - Backs up only system configuration, including the following:
      • setenv-custom configuration settings
      • SSL certificate files
      • other system configuration files
  6. Observe the JAR file created in \server\webapps\enportal\WEB-INF\archive\. 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

The Backup AppBoard 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 portal Restore 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 Backup All backup and restore method, not the AppBoard-only backup. To load an AppBoard-only backup over an existing installation, then use the portal FilesImport command instead of portal Restore. It will also be necessary to perform an additional step to ensure data source modifications are loaded:

  1. Shut down AppBoard.
  2. On the command line in the destination system, go to ...\server\bin\.
  3. Enter the command: portal FilesImport -jar <appboard-only-archive.jar>.
  4. Change into the ...\server\webapps\enportal\WEB-INF\xmlroot\appboard\ directory.
  5. Rename load-restore.txt.disabled to load-restore.txt.
  6. Start AppBoard.


Restore

The restore process enables you to install a new version of AppBoard/enPortal and restore your previous data and configurations.


How To Restore AppBoard/enPortal

  1. Shut down AppBoard.
  2. On the command line in the destination system, go to \server\bin\.
  3. Enter one of the following commands:
    Portal restore –jar ..\webapps\enportal\WEB-INF\archive\<name of backup jar file>
    • 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.
    Portal apply –jar ..\webapps\enportal\WEB-INF\archive\<name of backup jar file>
    • 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 [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/export.properties under the section labeled "import.skip.apply".
  4. Enter “yes” to confirm replacing any existing content.
  5. Start AppBoard and confirm that the exported content was loaded successfully.


Deciding Whether To Use the "Apply" or "Restore" Command

When to use "portal apply":

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


When to use "portal restore":

  • You want the restore to truly mirror the full configuration from the original server where the backup archive was created.


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.


Template-note.png
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.
Template-note.png
On Unix systems, after restoring an archive you need to verify that some of the server settings are correct. For more information, see Unix Installation - restoring an archive

Advanced Configuration

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


The following is a sample customization block that could be added to custom.properties:

[xml,N]

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


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.