Installation Guide

The following instructions guide the installation of the openVA Pipeline on Ubuntu 16.04 operating system.

Note

To make the installation process easier, all of the required software can be installed by downloading and running the bash script install_software_ubuntu16_04.sh located in the main folder of the openVA_Pipeline repository. There is a corresponding script for installing the pipeline (and dependencies) on Ubuntu 18.04: install_software_ubuntu18_04.sh

  1. Add the apt key (signed by Michael Rutter marutter@gmail.com) to authenticate R package from CRAN and add the CRAN repository to get the latest version of R (for more details see CRAN page: Ubuntu packages for R).

    $ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9
    $ sudo bash -c "echo 'deb https://cloud.r-project.org/bin/linux/ubuntu xenial-cran35/' >> /etc/apt/sources.list"
    
  2. Install Python, OpenJDK, R, SQLite3, SQLCipher, and Git by typing the following commands at a terminal prompt (indicated by $)

    $ sudo apt update
    $ sudo apt install python3-pip python3-dev openjdk-8-jre r-base sqlite3 libsqlite3-dev sqlcipher libsqlcipher-dev git -y
    
  3. (optional) Download the ODK-Briefcase-v1.12.2.jar file to a folder that will serve as the openVA_Pipeline working directory.

  4. Configure OpenJDK with R by running the following command

    $ sudo R CMD javareconf JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/bin/jar
    
  5. In a terminal, start R by simply typing R at the prompt, or use sudo R for system-wide installation of the packages. The necessary packages can be installed (with an internet connection) using the following command:

    > install.packages(c("openVA", "CrossVA"))
    

    Note that > in the previous command indicates the R prompt (not part of the actual command). This command will prompt the user to select a CRAN mirror (choose a mirror close to your geographic location), as well as a location for the library where the R packages will be installed (this does not happen if R is run as sudo). After the installation of the packages has been completed, you can exit R with the following command:

    > q('no')
    
  6. Python version 3.5 was installed during the initial sudo apt install command above, but we still need to update the package installer, setup a virtual environment with Pipenv, and install the openva-pipeline package. These tasks can be accomplished at the terminal as follows:

    $ pip3 install --upgrade pip --user
    $ hash -d pip3
    $ pip3 install --upgrade setuptools --user
    $ pip3 install pipenv --user
    $ pipenv install openva-pipeline
    

    We can enter the virtual environment and import the openva-pipeline package with the following terminal commands:

    $ pipenv shell
    $ python
    
    
    >>> import openva_pipeline as ovaPL   # import package
    >>> help(ovaPL)                       # access primary help file (hit q to exit)
    >>> help(ovaPL.runPipeline)           # access help file for a particular function
    >>> quit()                            # return to virtualenv terminal shell
    
    $ exit
    

    Note: the first command: pip3 install --upgrade pip --user will produce a warning message:

    You are using pip version 8.1.1, however version 10.0.1 is available.
    You should consider upgrading via the 'pip install --upgrade pip' command.
    

    However, after running the command hash -d pip3, the command pip3 --version shows that version 10.0.1 is indeed installed.

  7. Install DB Browser for SQLite with the commands

    $ sudo apt install build-essential git-core cmake libsqlite3-dev qt5-default qttools5-dev-tools libsqlcipher-dev -y
    $ git clone https://github.com/sqlitebrowser/sqlitebrowser
    $ cd sqlitebrowser
    $ mkdir build
    $ cd build
    $ cmake -Dsqlcipher=1 -Wno-dev ..
    $ make
    $ sudo make install
    

Alternative Installation Options

Using Java JDK (instead of OpenJDK)

Instructions for installing JDK 8 on Ubuntu 16.04 can be found here. After installing JDK 8, run the following command at the terminal to properly configure R

$ sudo R CMD javareconf

and then install the R packages (as described above).

Installing the Pipeline package with using a virtual environment (and pipenv)

Simply use pip3 to install the openva-pipeline package as follows

$ pip3 install openva-pipeline --user