Backing up Document.One installation

D1 and Conversion Service installation packages contain the create-backup and restore-backup scripts. See Installation package overview for details on the installation package contents.

We recommend that you use these scripts to back up your current installation before installing a new version of D1 and Conversion Service. In case of errors on installing a newer version of Document.One, you can quickly restore the working runtime from a backup package. This procedure is the same for D1 and Conversion Service.

How the backup and restore scripts work

You run the create-backup script to create a .zip package from a valid D1/ Conversion Service installation directory. You can create as many backups in the same folder as you need.

The create-backup script creates a copy of the entire installation directory of a corresponding server (D1 or Conversion Service) and not a backup of the whole system (which relies on external components, such as databases, file systems or cloud storage at your organization).

You run restore-backup script to unzip the previously created backup package into a new directory.

Backup note

To back up the whole system you need to follow your organization guidelines for backing up the external components, in addition to backing up D1 and Conversion Service installation.

What is backed up?

What is not backed up?

All files saved in the installationPath root directory are backed up. This directory includes existing D1/ Conversion Service runtime and its configuration, as defined in the installation settings file. Installation license Default admin user Tribefire-services URL Database connection settings (but NOT the database data!) File system paths used (but NOT the file system data itself!) Default repository settings - if they were used Runtime properties

The backup script creates a backup only of a the installation folder. Therefore, the backup does not include the following: Any database data, i.e. neither system nor business data. Any files shared between cluster nodes, such as business files (documents, images) and elastic search data. Any other files which are not part of the installation root. Log files and temporary files are not included (if the default configuration wa applied on installation). This depends on the installation settings. If you changed the installation settings when previously installing D1/Conversion so that any of the files mentioned above are written to the installation folder, they will also be backed up. This is not a recommended practice though and it will cause backups to be larger and slower.

Documentation note

Examples provided on this page are based on Linux environment. If you are on Windows, simply use the .bat scripts instead of the .sh scripts mentioned below.

To back up existing D1/ Conversion Service installation

1. Open the deployment package. The following files should be available (for example when you list with ll):

   • README
   • check-health.sh
   • create-backup.sh
   • encrypt.sh
   • example-environment.sh
   • example-installation-settings.yaml
   • install.sh
   • jinni.sh
   • resources/
   • restore-backup.sh

2. Run the following command to create a backup:

   ./create-backup.sh --installationFolder [installation folder] --backupFolder [backup folder]

   Command options

   You can also use the following command aliases:

   • -i for --installationFolder
   • -b for --backupFolder
   • -n for --includeHostInfo.

   To write the host name within the package name, you need to add the --includeHostInfo flag to the create-backup command.

   For command-line help, run ./create-backup.sh.

   Command example

   Assume that your installation folder is /opt/braintribe/adx/installation, and you want to create the backup archive in /opt/braintribe/adx/backups. Run the following command:

   ./create-backup.sh --installationFolder /opt/braintribe/adx/installation --backupFolder /opt/braintribe/adx/backups --includeHostName
   Command output

   As a result of running the create-backup script, a .zip archive named after the D1 version, host name (if enabled) and a timestamp (similar to adx-2.4.391-DESKTOP-J07TD08-20200727-121913) containing your installation files is now available in /opt/braintribe/adx/backups.

To restore D1/ Conversion Service installation from backup

1. Open the deployment package.

2. Run ./restore-backup.sh --backupArchive [backup archive] --installationFolder [installation folder].

   Command options

   You can also use the following command aliases:

   • -b for --backupArchive
   • -i for --installationFolder.

   To see command-line help, run ./restore-backup.sh.

   Command example

   Assume that your backup folder is /opt/braintribe/adx/backups, and you want to restore from the adx-20200206-132812.zip archive. Run the following command:

   ./restore-backup.sh --backupArchive /opt/braintribe/adx/backups/adx-20200206-132812.zip --installationFolder /opt/braintribe/adx/restored_installation
   Command output

   As a result of running the restore-backup script, the following happens:

   • If your --installationFolder directory already contains an D1 or Conversion Service runtime, it is backed up into a new directory. This new directory is appended with a timestamp-based suffix, such as installation-folder-backup-20201224-123456.
   • If the --installationFolder directory does not exist before, it is created.
   • If it exists, but does not contain a valid runtime, the restore script fails.

   Files from the archive are unzipped into the --installationFolder directory, replacing the original runtime (unless the directory has just been created).

3. You can now start the restored D1 runtime. To do so, from the restore directory go to /runtime/host/bin and execute ./tribefire-console-start.sh.

Where to go from here

When you have created a backup of all D1 and Conversion Service servers that you have in your deployment, you can proceed with upgrading Conversion Service servers. See Upgrading Conversion Service.