Regular backups of AnthillPro is advisable to protect your data. As generally understood by the common public, having a backup of any digital data is vital for integrity & restoration of the chance a corruption might occur. Something as simple as a power surge could cause corruption, along with how data can be accidentally deleted, damaged by a virus or a hard disk failure, etc. This is one of the most important, yet also one of the most neglected areas of computing. Backing up your data should be at the top of your computer maintenance list; without data backup, you are running the risk of losing your data. And it will happen; don’t think that you don’t have to worry about it.

AnthillPro Backups w/Apache Derby

AnthillPro supports scheduled backups of the Derby database through the UI, using a backup schedule. The backup interval will vary depending on the size of your organization, number of artifacts, etc. Backup schedules may be deactivated or changed on the Server Settings page. Backups are saved in the var\db\backup directory (e.g., %SERVER_HOME%\var\db\backup\). Every update will be named according to the date and time of the backup (in the format year-month-day_hour-minute-second; i.e., similar to 2008-10-08_10-59-48).

Prerequisites

• You must have read & write permissions to the System page.
• Before editing a backup setting, create a special schedule or use an existing schedule.
• You must have a file archiver installed (such as 7-Zip, WinZip, WinRAR, WinACE, WIM, Tar, Gzip, etc.)

Automated Backup Schedule

Create Backup Schedule

1. Go to the System --> Schedules page.
2. Click the Create Schedule button to create a new schedule.
3. For backups, creating a basic schedule with a rather long interval works well. Select the Interval Schedule option and click Set.
4. Configure the schedule. Click Set.

Use Backup Schedule

1. Go to System --> Backup Settings page.
2. To manually perform a backup, click the Backup Now button.
3. To choose a schedule or change the number of stored backups, on the Main tab click the Edit button.

PROTIP: You can click on History to see the list of previous database backups!

Deactivate Backup Schedule

When deactivating or changing a backup schedule, make sure that the schedule is not inadvertently deactivated or deleted. Because different AnthillPro activities may rely on a single schedule, deleting or deactivating the actual schedule may effect other activities.

1. Go to System --> Backup Settings page.
2. Click Edit on the Backup Setting Main tab.
3. To deactivate backups: Select None from the Backup Schedule drop-down menu to deactivate backups. When none is selected, no further backups will occur.
4. To change to a different schedule: Select it from the drop-down menu. This may require creating a new schedule. One complete, a backup will occur when the new schedule fires.
5. Click Save then Done.

Clean Restoration

Restoring AnthillPro to a clean state requires overlaying the installation with backed-up data files. The directions outlined below are for backups of the embedded Derby database. If using another database type, you cannot use most of the concepts in this section. Typically, restoring AnthillPro to a backed-up version is an option of last resort, and should only be used if there is no other way to correct an issue.

Note that restoration requires shutting down the server and agent(s).

1. Shutdown the server and the agent(s).
2. Go to the AnthillPro instance.
3. In the %SERVER_HOME%\var\db\ directory, rename the data folder to data_old. In Item 7, a copy of the backed-up data folder will be added (renaming the existing data folder reduces the chances of corruption).
4. Go to the %SERVER_HOME%\var\db\backup\ directory and open the appropriate backup folder. Every backup is identified in the format year-month-date_hour-minute-second (e.g., 2008-10-08_10-59-48).
5. Open the backup you want to restore AnthillPro to, and copy the data folder located within the directory (e.g., the data folder is located in the var\db\backup\2008-10-08_10-59-48\ directory of a backup that was performed on October 8, 2008 at 10:59:48 a.m.).
6. Go back to the %SERVER_HOME%\var\db\ directory.
7. Paste the backup's data folder here. Do not delete the old (renamed) data folder until you have verified that the restoration was successful.
8. Restart the server and agent(s). Ensure that the restoration was successful. If there is a problem, contact the AnthillPro support team with details.

Filesystem

KEEP IN MIND THAT ALL THE STEPS LISTED ABOVE ARE ONLY FOR CHANGING THE DATABASE STATES. In actuality, no other files are backed up, which leaves your previous build artifacts, codestation artifacts, job logs, test results, etc. at risk. To negate this, it is recommended to backup the entire anthillpro directory filesystem as well so that the filesystem can be restored to the same timeframe as the server.

Unfortunately, there are some cases that warrant a server not being able to have its entire filesystem backed up. The order of precedence on how to continue is thus:

1. Attempt to make a backup of the entire server filesystem. If this is not an option, see #2.
2. Attempt to backup any customized files (such as custom startup scripts in the bin directory, changed libraries in the lib directory, etc.) in addition to the var directory. If this is not an option, see #3.
3. Attempt to back up the entire var directory. If this is not an option, see #4.
4. Attempt to back up the most important parts of the var directory. This includes the following:
   1. artifacts - Where your build artifacts live for each buildlife.
   2. codestation - Where your codestation project artifacts live for each codestation buildlife.
   3. published - Where your published reports are stored.
   4. logs - Where your server logs, in addition to job logs, lie.

Make sure that whichever method you choose, you have an archive of it, and be sure to TEST THE ARCHIVE after creation to verify its integrity. For example, if backing up the entire server filesystem using 7-zip, one's command might look like thus:

7z a -t7z -m0=LZMA2 -mx9 -md256m -ms=on -mmt2 %ARCHIVE_DIRECTORY%\backup.7z %SERVER_HOME%

Filesystem Restoration

It would be best to rename the old server installation (as to not lose the current file structure/contents if the unarchive should go awry) first before unarchiving a backup, but all you need to do is unarchive the backup into the %SERVER_HOME% directory. Then, your server's filesystem should be back in the state the archive was.

AnthillPro Backups w/Other Databases

If using AnthillPro with Oracle, MySQL, or Microsoft SQL Server database, backups are not performed through the AnthillPro UI. Each database has its own backup tool that should be used for backups (see documentation for your vendor's particular tool). Some examples are listed below:

• MySQL uses mysqldump, which there is additional examples on how to use it, here.
• Oracle can use expdp, and we have some internal notes on how to use it, here.

Prerequisites

• You must consult the previous statement.
• You must have a file archiver installed (such as 7-Zip, WinZip, WinRAR, WinACE, WIM, Tar, Gzip, etc.)

Filesystem

KEEP IN MIND THAT ALL THE STEPS LISTED ABOVE ARE ONLY FOR CHANGING THE DATABASE STATES. In actuality, no other files are backed up, which leaves your previous build artifacts, codestation artifacts, job logs, test results, etc. at risk. To negate this, it is recommended to backup the entire anthillpro directory filesystem as well so that the filesystem can be restored to the same timeframe as the server.

Unfortunately, there are some cases that warrant a server not being able to have its entire filesystem backed up. The order of precedence on how to continue is thus:

1. Attempt to make a backup of the entire server filesystem. If this is not an option, see #2.
2. Attempt to backup any customized files (such as custom startup scripts in the bin directory, changed libraries in the lib directory, etc.) in addition to the var directory. If this is not an option, see #3.
3. Attempt to back up the entire var directory. If this is not an option, see #4.
4. Attempt to back up the most important parts of the var directory. This includes the following:
   1. artifacts - Where your build artifacts live for each buildlife.
   2. codestation - Where your codestation project artifacts live for each codestation buildlife.
   3. published - Where your published reports are stored.
   4. logs - Where your server logs, in addition to job logs, lie.

Make sure that whichever method you choose, you have an archive of it, and be sure to TEST THE ARCHIVE after creation to verify its integrity. For example, if backing up the entire server filesystem using 7-zip, one's command might look like thus:

7z a -t7z -m0=LZMA2 -mx9 -md256m -ms=on -mmt2 %ARCHIVE_DIRECTORY%\backup.7z %SERVER_HOME%

Filesystem Restoration

It would be best to rename the old server installation (as to not lose the current file structure/contents if the unarchive should go awry) first before unarchiving a backup, but all you need to do is unarchive the backup into the %SERVER_HOME% directory. Then, your server's filesystem should be back in the state the archive was.

Database Restoration

Please consult your database vendor's documentation for restoring databases.

Appendix A: Key Files

These layouts are all assumed from the %SERVER_HOME% directory.

Appendix B: Note on Import/Export Method

A lot of customers mistakenly use the import/export option of anthillpro to make "full backups" of their projects, library jobs, etc. While this may seem like a good idea, the fidelity & integrity of projects most likely will become compromised. Therefore it is recommended to do a database backup/clone if trying to copy projects to a new server. Exporting and importing projects is not meant for moving projects around from one server to another. It was included in AnthillPro primarily for debugging off of the production server, mainly for our needs in checking out customer project configurations etc., and is not intended for production.

Documentation Contradiction

Recently is has come to our attention that the out-of-date documentation stated that importing and exporting projects are perfectly safe. We strongly advise you to disregard what the documentation states and note the bugs that appear here in this section. A clone of the database is much more reliable than import/exports.

Conflicting Documentation

• Importing and exporting projects is done from the Administration page. AnthillPro exports the project configurations as an XML file. The exported file may be used to transfer project configurations between multiple instances of AnthillPro, for troubleshooting purposes, etc. A project may be imported either into the Administration folder or into any sub-folder on the Administration page. Once successful, the imported project will have the same configurations as the original.

Fidelity/Integrity

Examples of losses in fidelity and corruption in integrity include (but are not limited to):

• Assign Status Steps
  • Steps are blanked out upon import; need reset
• Life Cycle Model Creation
  • If a Life Cycle Model already exists with this name, the exported project's Life Cycle Model information will not be imported
• Populate Workspace Steps
  • Some newer versions of anthillpro have been known to blank the workspace script upon import of projects that contain a Populate Workspace step
• Run Another Workflow Steps
  • Steps are blanked out upon import; need reset
• Statuses Within Life Cycle Model
  • If a status already exists with this name in a Life Cycle Model, the exported project's statuses within its Life Cycle Model information will not be imported
• This bad error:

  • com.urbancode.anthill3.domain.persistent.PersistenceException: Error inserting object in database: 
    Cannot add or update a child row: a foreign key constraint fails (`anthill3`.`BUILD_PROFILE_ARTIFACT_DELIVER`,
     CONSTRAINT `BPAD_ARTIFACT_SET_FK` FOREIGN KEY (`ARTIFACT_SET_ID`) REFERENCES `ARTIFACT_SET` (`ID`))
    

• Missing Plugins or wrong versions of Plugins

Sample Warnings Thrown in UI

The UI is generally a great place to start and see if any issues have arisen with the import of the project. If there are no additional details there, it is also possible the ah3server.out and ah3server.err have additional details. If after still consulting both of those places you cannot locate any details, it might still be possible that certain aspects of the import have different results. [h See the next section for some examples that could cause a general warning to be thrown].

General Warnings

The following will cause a general warning to be thrown, with no other details in the server logs and/or UI:

• Agent Filters on Workflow Definition didn't update properly
• Agent Filters on Quiet Periods didn't update properly
• Statuses not set up properly in "Assign Status" steps
• etc.

Example Screenshots

A screenshot showing that some secondary workflows were not imported 100% successfully and will require some manual intervention. In this case, the library workflow definition could not be set up on the secondary workflow, nor could the Run Another Workflow steps be configured properly.

A screenshot showing that there is a very good chance something may not have been imported correctly. In this case, the project was imported successfully & no steps needed changing/updating. However, the agent filter (--Make Selection--) was not configured properly (No Agent). This warning is thrown when miscellaneous issues could be at risk.