Appboard/old/backup and restore

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.

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.

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.