GangaDB User Guide

With the completion of GSoC 2020 project, ganga project now supports the usage of databases to store job information instead of saving them as files in the gangadir folder. To upgrade and get the new features, install ganga from the feature branch [database-master](https://github.com/ganga-devs/ganga/tree/database-master):

1. Install from source

   # clone the repository
   $ git clone https://github.com/ganga-devs/ganga
   $ git checkout database-master
   # install the package
   $ python setup.py install

2. Install using pip from source

$ pip install https://github.com/ganga-devs/ganga/tree/database-master/archive/master.zip

3. Install from pypi:

# Will be updated soon.

Documentation

The usage documentation can be found here:

User Guide for Existing Users:

This guide is for users who have used ganga before and wish to use gangaDB ( and also migrate the current jobs from xml format to the database ).

Choose the preferred method of database:

1. Native Database: Instructions to install

2. Docker Container: Instructions to install

3. uDocker Container: Instructions to install. Make sure the update the location of the udocker binary in the config ( in case the location is not ~/udocker or the binary is not linked ) in the .gangarc:

   ## UPDATE THE UDockerlocation var in the gangarc
   UDockerlocation = ~

   Make sure the udocker binary is not execute restricted as ganga uses sub-processes to run commands using the binary.

4. Singularity Container: Instructions to install

Once the controller of choice is installed, update the gangarc config:

## UPDATE THE FOLLOWING SECTION OF gangarc, this example assumes docker

#  Selection of database for ganga
[DatabaseConfiguration]
#  Docker Image for the database
#baseImage = mongo
#  Database Controller [Native, Docker, uDocker, Singularity]
controller = docker
#  host
#host = localhost
#  password
#password = default
#  username
#username = default

Also update the repositorytype:

## LocalXML for using xml and Database for using gangaDB
repositorytype = Database

Now one last thing remains to run gangaDB with the mentioned controller. Download the mongodb image from the container repository ( skip in the case of native installation ).

The commands for the respective controllers are ( the controllers are listed in the order of reliability ):

1. Singularity: We use a custom image sif file that is hosted here. Users can manually download the sif file and store it in the gangadir folder or let ganga do it for them. In the case of the latter, the file is downloaded and stored in the gangadir folder mentioned in the gangarc file.
2. Docker: docker pull mongo
3. uDocker: udocker pull mongo

Now the user is ready for using gangaDB. To test the installation, run a simple ganga session

*** Welcome to Ganga ***
Version: 8.3.3 - DEV
Documentation and support: http://cern.ch/ganga
Type help() or help('index') for online help.

This is free software (GPL), and you are welcome to redistribute it
under certain conditions; type license() for details.

INFO     reading config file /home/dumbmachine/work/ganga/.database.rc
INFO     Docker gangaDB has started in background at 58207

[16:48:20]                                                                                                                                                                                                         
Ganga In [1]: jobs                                                                                                                                                                                                 
Ganga Out [1]: 
Registry Slice: jobs (0 objects)

Now jobs are shown as we have none in the database.

Previous users of ganga who wish to port their old job files to the database can do so:

# download the migrating script
$ wget https://raw.githubusercontent.com/ganga-devs/ganga/develop/ganga/GangaCore/Core/GangaRepository/migrate.py
# run the script and all your jobs will be stored in the database
$ ganga migrate.py

Ganga will start the container with random free ports on the OS to avoid clash.