Page Comparison

...

Datameer highly recommends that a MySQL application database be in production before the Git plug-in is installed. If the internal HSQL database is being used with Datameer when the Git plug-in is installed, a later HSQL to MySQL migration is not possible due to a discrepancy between the application databases' schemas.

Installing the Plug-in

1. Before you install the plugin, you might want to configure the folder where plug-in configurations are stored. To check the current path setting, open the file system for Datameer and navigate to the conf/default.properties file. Search for the property that defines the folder where plug-in configurations are stored.

   Code Block
   title Example
   <datameer-install-path>/conf/default.properties # Defines the folder where to store plugin configurations system.property.plugin.configs.dir=<folder name>

   It is important to note where plug-in configurations are stored if you are upgrading Datameer in the future, since you need to copy the contents of the previous plug-in configurations folder into the file system of the upgraded version of Datameer.

2. Create a new folder to store the Git repository on the Datameer server. Make sure the user who is running Datameer has read and write capabilities for this folder.

3. In the command line, go to your Git folder and type in the command git init. If it is working correctly, you receive a response that the Git repository was initialized. 

4. Use the directions under Managing Plug-ins and Extension Points to  to install the plug-in. On the Plug Plug-ins page page, click the cog symbol next to to Git Versioning Plug-in to  to configure the settings.

5. The following example creates a Git repository in Datameer's installation folder:

   Code Block
   title Example
   $ mkdir /opt/datameer/current/versioning $ cd /opt/datameer/current/versioning $ git init Initialized empty Git repository in /opt/datameer/current/versioning/.git/

6. Create a first backup of the Git repository. In the future, back up this repository frequently.

   Code Block
   title Example
   cp conf/plugins/plugin-versioning-git.json versioning tar -zcvf `date +%Y_%m_%d`.versioning.tar.gz versioning/*

Configuring the Plug-in

1. On the the Plug-ins page page, click the cog symbol next to to Git Versioning Plug-in to  to configure the settings.
   
2. In the Local Path field field, enter the path to the folder created on the Datameer server.
3. Select the Request Snapshots of File Browser Artifacts option to start an initial tracking of all artifacts in Datameer. If selected, users shouldn't use Datameer during this time. You can check to see that the process is complete by opening the new folder and checking that snapshots exist for each of the workbooks. If they do, users can access Datameer again.

...

drwxr-xr-x  52   !files-by-uuid/
-rw-r--r--   1   !folder.json
drwxr-xr-x  21   !folders-by-uuid/
drwxr-xr-x  13   .git/
drwxr-xr-x   5   .system/
drwxr-xr-x   4   Analytics/
drwxr-xr-x   8   Data/
drwxr-xr-x   4   Images/
drwxr-xr-x   4   Users/
drwxr-xr-x   4   Visualization/

In this example: 

• The The !files-by-uuid/directory stores  stores symbolic links to the metadata of all workbooks in Datameer, identified by their UUID.
• The The !folder.json file shows the metadata of the root folder of the File Browser, including permissions and UUID.
• !folders-by-uuid/ is a directory that stores symbolic links to the metadata all folders in Datameer, identified by their UUID.
• .git/ is a directory that represents the local Git repository.
• .system/ is a hidden directory in Datameer's File Browser with internal artifacts.
• The directories from Analytics/ on represent the folders that the user has set up in the File Browser.

...

1. To roll back changes while Datameer is running, create a clone of the configured Git repository to avoid conflicts while Datameer is writing to the original repository using the git clone command.

   Code Block
   title Example
   # assuming the configured repository is located under /opt/datameer/current/versioning $ cd /opt/datameer/current $ git clone versioning/ versioning-clone Cloning into bare repository 'versioning-clone'... done.

2. Sync the cloned repository with the original repository to make sure the commits are the same using using git checkout and  and git pull.

   Code Block
   title Example
   # to sync the clone with the origin once (repeat as needed) $ cd /opt/datameer/current/versioning-clone $ git checkout master $ git pull

3. See a history of changes to a workbook by using the git log command to see all commits over time for a specific workbook.

   Code Block
   title Example
   # assuming the repository is located under /opt/datameer/current/versioning-clone $ cd /opt/datameer/current/versioning-clone $ git log --oneline --follow Analytics/Workbooks/Workbook1.wbk 9499a56 Renamed Column on Workbook "1<UUID>" 6f131f1 Created Formula on Workbook "1<UUID>" 4fb067a Renamed Column on Workbook "1<UUID>" fe11c97 Renamed Sheet on Workbook "1<UUID>" 5d9847a Copied Sheet on Workbook "1<UUID>" a9d8234 Deleted Formula Sheet on Workbook "1<UUID>" 0ca3031 Updated File "1<UUID>" e667f5c Snaphot of Workbook "1<UUID>"

   Info
   Make sure to use git log on the real file of the workbook which lies in the directory, as opposed to using the command on a symbolic link. If you look for the history on the symbolic link, it shows only the creation of the link itself.

4. To see what actually was changed within the workbook, look at a specific commit.

   Code Block
   title Example
   $ git show <commit>

   This command gives an output similar to the following, which shows who changed the formula and who changed the type from a float to an integer:

   Code Block
   title Example
   [datameer@<host> versioning-clone]$ git show <commit> commit <commit> Author: qa <qa@datameer.com> Date: <timestamp> Created Formula on Workbook "<UUID>" diff --git a/Analytics/Workbooks/<workbookName>.wbk b/Analytics/Workbooks/<workbookName>.wbk index <ID> --- a/Analytics/Workbooks/<workbookName>.wbk +++ b/Analytics/Workbooks/<workbookName>.wbk @@ -43,7 +43,7 @@ "position": 0 }, { - "formula": "\u003dRANDBETWEEN(1;10)", + "formula": "\u003dINT(RANDBETWEEN(1;10))", "id": "1", "name": "Int", "position": 1 @@ -85,7 +85,7 @@ "/Analytics/Workbooks", "<UUIID>" ], - "modifiedAt": "<timestamp>", + "modifiedAt": "<timestamp>", "name": "<wortkbookName>", "permission": { "groups": { ...

5. To restore a specific version of the workbook, check out the related state of the repository using its commit ID using the the git checkout command command.

   Code Block
   title Example
   $ git checkout <commit>

6. If you want to review the workbook to make sure you have the right version, you can print the metadata of the workbook using the the cat command command.

   Code Block
   title Example
   # print the contents of a workbook $ cat \!files-by-uuid/1<UUID>.json { "_version": "5.11.18", ... }

7. Restore the workbook by using the roll back a workbook REST API.

   Code Block
   title Example
   # rollback a workbook by using cURL $ curl -u admin:admin -X PUT -H "Content-Type:application/json" -d @\!filesfolders-by-uuid/1<UUID><uuid>.json 'http://localhost:80888080/api/filesystemworkbooks/workbook-rollback'

8. Reset the repository to the latest state using the the git checkout command command.

   Code Block
   title Example
   $ git checkout master Switched to branch 'master'

9. Re-sync the cloned repository with the original using the the git checkout and  and git pull commands commands, to make sure both are up-to-date.

   Code Block
   title Example
   # to sync the clone with the origin $ cd /opt/datameer/current/versioning-clone $ git checkout master $ git pull

Other REST API tools

You can also also create or  or overwrite a  a workbook based on the JSON representation in a Git repository used by the Git versioning plug-in.

Installing the Git Versioning Plug-in After Upgrade

After upgrading Datameer, you might need to re-install the plug-in.

1. Double-check that the Datameer service is stopped.

2. Create a folder to store the Git repository on the Datameer server. Make sure the user who is running Datameer has read and write capabilities for the new folder.

   Code Block
   [datameer@<host> current]$ mkdir /opt/datameer/current/versioning

3. Unpack the Git repository backup.

   Code Block
   tar zxvf <date>.versioning.tar.gz

4. Move the configuration file to the correct folder.

   Code Block
   [datameer@<host> current]$ mv versioning/plugin-versioning-git.json conf/plugins

5. Install the downloaded Git versioning plug-in into the plug-ins folder. This installation ensures that plug-in becomes loaded automatically during Datameer service start.

   Code Block
   [datameer@<host> current]$ mv plugin-versioning-git-<version>.zip plugins/

    The  The plug-in is installed now and the Datameer service is safe for start.

...