Version 1.5

Definition of Terms

• Nodes = GOBii Nodes
  • The term "nodes" here will always refer to the GOBii nodes, which are Docker containers that can be deployed to different servers or virtual environments. Server nodes, on the other hand, will be explicitly called "server node".

Background

GOBii is made up of multiple modules and categorized according to functions.  A system diagram that shows these categories (by Docker container), the data flow, and the modules is available here.

Depending on your server topology, the instructions on this page may require some tweaking. For each section with significant differences on steps, depending on server topology, a "Note Box" like the one below will be written.

Server 1:
	Server Head: GOBII Test (all nodes)
	Server Node1: GOBII Prod Database Node
	Server Node2: GOBII Prod Web Node
	Server Node3: GOBII Prod Compute Node

1. The official repository for the deployment scripts is here. Make sure you clone or download the scripts from there. The branch you should get is release/<version> (ex. release/1.5). You can also get the master branch if you are deploying the latest, but because our clients can have varying versions on different servers, all release branches are kept.
2. Finalize your topology and write it down, because if you are deploying all three GOBii nodes to just one server, you run a different script as opposed to when you deploy GOBii into one server per node or any other variations (you run three scripts).
3. The servers should have the Docker engine version 17 and up installed. Make sure the servers have access to the dockerhub site.
   1. Ubuntu: https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#upgrade-docker-ce-1
   2. CentOS: https://docs.docker.com/install/linux/docker-ce/centos/
4. A mount point or a shared drive that all the nodes can access — this will be a volume mounted to all the three Docker containers.

5. The user that will run the scripts needs to be a sudoer and under the GOBii and Docker groups. So preferably, the user 'gadm'. But the username is arbitrary, it just needs to be consistent. You may find gadm sudoer used in the rest of this document. Note that the name is flexible.

   1. sudo usermod -aG docker gadm

6. (Optional) A directory where the data of postgres will reside. The default will be Ubuntu's postgres directory in the DB Docker (ex. /var/lib/pgsql/data) which will be linked to Docker's default volume directory (ex. /usr/local/docker/volumes/postgreslibubuntu)

1. Copy the deployment scripts and files from the cloned repository (prerequisite #1) to the shared drive (prerequisite #4).

   We update the param files from time to time (i.e. new features being added), so please don't just copy-paste the sample param files below. They are just shown in this page for reference. Instead, pull from our deployment scripts git repository for a particular release you are deploying (ex. release/1.5).

   The templates shown below were last updated for version 1.4.

2. Edit the main parameter file. You can find a template in the repository (gobiideployment/params/template_main.parameter). This file should be placed in the same directory as the deployment scripts (as of 1.4, this is no longer the case). It will contain all the topology information and deployment credentials. The template is shown below, with each parameter explained on top of the corresponding line: 

   Go through this parameter file line by line. Make sure all the values are correct, especially on the names of the crops and the Docker images you want to deploy. Go to hub.docker.com and look at the containers under our repository gadm01 to make sure you got the image name correctly.

   Default Credentials

   All the passwords and some usernames have been omitted on the parameter file templates in this page for security. Make sure you check Version 1.5 to replace the parameters with the correct values. If you can't access the page with the default credentials, contact 00d483e952a2545b0152a4b36870000e or 00d483e961e2874401621ac073490001.

   #This file will be used by the_gobii_ship_*.sh to deploy and configure the docker images to target hosts.
   
   #This is your shared directory (will be mounted as volume to the dockers), it needs to be accessible from the 3 dockers
   BUNDLE_PARENT_PATH="/mnt/temp-gobii"
   #The name of the first crop - this needs to match what is in the provisioned docker image in our docker hub.
   DOCKER_CROP1_NAME="maize"
   #The name of the second crop - this needs to match what is in the provisioned docker image in our docker hub.
   DOCKER_CROP2_NAME="wheat"
   #IP/Hostname of the docker compute host
   DOCKER_COMPUTE_HOST="172.1.2.5"
   #Name of the compute docker. This is more of an alias to let you access it conveniently.
   DOCKER_COMPUTE_NAME="gobii_compute_cimmyt"
   #Port number that will be mapped to compute node's default SSH port. Make sure it's open and doesn't conflict with anything in the host server.
   DOCKER_COMPUTE_SSH_PORT="2222"
   #The number of minutes the instruction files age should be before the cronjobs pick them up. This needs to be prefixed by '+', which means 'pick up the files that are greater than n minutes'.
   DOCKER_CRON_FILE_AGE="+2"
   #The number of minutes between each cron jobs execution.
   DOCKER_CRON_INTERVAL="2"
   #IP/Hostname of the docker DB host
   DOCKER_DB_HOST="172.1.2.4"
   #Name of the database docker. This is more of an alias to let you access it conveniently.
   DOCKER_DB_NAME="gobii_db_cimmyt"	
   #Port number that will be mapped to the DB docker's 5432 port for postgres connection. Make sure it's open and doesn't conflict with anything in the host server.
   DOCKER_DB_PORT="5433"
   #IP/Hostname of the docker DB host
   DOCKER_WEB_HOST="172.1.2.3"
   #Name of the web docker. This is more of an alias to let you access it conveniently.
   DOCKER_WEB_NAME="gobii_web_cimmyt"
   #Port number that will be mapped to port 8080 in the web docker (the Tomcat default port). Make sure it doesn't conflict with anything in the host.
   DOCKER_WEB_PORT="8081"
   #The group ID of the 'gobii' group in the host machine. The name can be arbitrary, ex. 'icrisat-gobii', as long as this GID corresponds correctly to it. The 'gobii' group in all the 3 dockers will be linked to it.
   #Sample command to get it: getent group gobii (then take the first number) - this depends on your host's OS
   GOBII_GID="12345"
   #The user ID of the 'gadm' sudoer in the host machine. The name can be arbitrary, ex. 'icrisat-gadm', as long as this UID corresponds correctly to it. The 'gadm' user in all the 3 dockers will be linked to it.
   #Sample command to get it: getent passwd gadm (then take the first number) - this depends on your host's OS
   GOBII_UID="123456789"
   #As of 1.4, this parameter is passed directly, hence this line is ignored. OBSOLETE: File name of the parameter file that will be used for the GOBII instance's configuration once installed. The gobii-web.xml file will be generated based on the values in this parameter file. 
   CONFIGURATOR_PARAM_FILE="template_install.parameters"
   #The gadm password inside the docker containers, you can find the actual password in a restricted page "Defaut Credentials" in GOBii confluence.
   DOCKER_GOBII_ADMIN_PASSWORD="changeme"
   #Name of the compute docker repository under GOBII's account (gadm01) you want to pull from.
   DOCKER_HUB_COMPUTE_NAME="gobii_compute_cimmyt"
   #Name of the DB docker repository under GOBII's account (gadm01) you want to pull from.
   DOCKER_HUB_DB_NAME="gobii_db_cimmyt"
   #Name of the web docker repository under GOBII's account (gadm01) you want to pull from.
   DOCKER_HUB_WEB_NAME="gobii_web_cimmyt"
   #Username of the docker hub account you want to use. Change accordingly. If you get permission issues
   DOCKER_HUB_USERNAME="gadm01"
   #Name of the sudoer account in the HOST server that the dockers' gadm account will correspond to (it can be named differently as long as their UIDs match)
   DOCKER_SUDOER_USERNAME="i-am-super"
   #The name of the GOBII application data bundle. Keep the default unless otherwise changed in the docker images.
   DOCKER_BUNDLE_NAME="gobii_bundle"
   #Internally used by the dockers. Keep the default unless otherwise changed in the docker images.
   BUNDLE_TEMP_PATH="/var/gobii_bundle"
   #Postgres Volumes Path -- No need to change this, just create a symlink from the docker volume directory to where you want postgres datafiles to reside. Because as of now, changing these volumes path from here hasn't been tested.
   POSTGRES_ETC="gobiipostgresetcubuntu"
   POSTGRES_LOG="gobiipostgreslogubuntu"
   POSTGRES_LIB="gobiipostgreslibubuntu"
   
   
   #activate/decativate encryption
   ACTIVATE_ENCRYPTION="false"
   
   #Docker KDC Node name as it will appear on host
   DOCKER_KDC_NAME="gobii_kdc_node"
   #KDC Image name as it appears in docker hub
   DOCKER_HUB_KDC_NAME="gobii_kdc_ubuntu"
   #KDC file storage on host. Assumption is this dir lies with gobii_parent and accessible via "/data" symlink
   #This value should match with the param kdcompute.working-directory in kdc-application.properties in kdc docker image
   KDC_FILE_STORAGE_DIR="kdcompute_file_storage"
   
   ###Post 1.2 params starts here###
   
   #Liquibase contexts
   #This handles the migration path and the seed data -- depending on the flavor of GOBii that you are trying to deploy. A quick summary of what these contexts are:
   #1. general = this context contains schema changes (ie. dropped columns, new tables, dropped tables, etc)
   #2. seed_general = this context contains the basic seed data. It is mainly for controlled vocabularies and ontologies, ie. all seed data that needs to exist in all clients' databases.
   #3. seed_crop1 and seed_crop2 = these are example crop-specific seed contexts. You will need to ensure that the context you are using exists. New clients will have specific contexts created for them.
   #   These contexts contain contact information (ie. list of GOBii users for that instance, along with their usernames, email, and roles). Anything seed-data related that are specific to certain crops goes to this context.
   LIQUIBASE_CROP1_CONTEXTS="general,seed_general,seed_crop1"
   LIQUIBASE_CROP2_CONTEXTS="general,seed_general,seed_crop2"
   
   

   You can name this file however you want. The full file path is passed to the deployment script.

   For anything not clear or if you're not sure of what to put on a parameter's value, please ask 00d483e952a2545b0152a4b36870000e.

   If a seed context for your crop is not available and you would like to have one (ex. seed_crop3), please contact 00d483e961e2874401621ac073490001 or 00d483e952a2545b0152a4b36870000e.

3. Edit the install parameter file. You can find a template in the repository (gobiideployment/params/template_install.parameter). This file should be placed in the same directory as the deployment scripts (as of 1.4, this is no longer the case). It will contain all the GOBii instance's configuration (i.e. runtime configuration via the gobii-web.xml content). The template is shown below, with each parameter explained on top of the corresponding line:

   #This parameter file will be used by gobiiconfig_wrapper.sh to generate a proper gobii-web.xml -- the main configuration file of a GOBII instance.
   #Note that you need to specify this file into the *_main.parameters so that the deployment script will pick it up.
   #Also note that all the paths here are on the point of view of the running dockers, mainly the web docker, hence the /data prefix on most of them.
   #The /data directory is the default working directory of all the GOBII dockers, this is also where the application bundle is located. It is a volume mapped to the shared directory visible to all 3 dockers.
   
   #The GOBII application data bundle's path in the context of the docker containers. Keep the default unless otherwise changed in the docker images.
   BUNDLE_PATH="/data/gobii_bundle"
   #The generated gobii-web.xml path. Keep the default unless otherwise changed in the docker images.
   CONFIG_XML="/data/gobii_bundle/config/gobii-web.xml"
   #The authentication type. If you want to be able to login using the test user upon installation, set this to "TEST". If you want to immediately connect to LDAP upon installation, set to "LDAP".
   #We suggest to set it to "TEST" at first, then verify that everything works by logging into the extractor UI. Then manually set it to "LDAP" in the gobii-web.xml file, then restart Tomcat and you're all set.
   AUTH_TYPE="TEST"
   #The LDAP distinguised name
   LDAP_DN="uid={0}"
   #The LDAP URL
   LDAP_URL="ldaps://test.cornell.edu/ou=people,dc=testl,dc=testnet"
   #The LDAP Bind User
   LDAP_BIND_USER="uid=gobii-user"
   #The LDAP Bind User's password
   LDAP_BIND_PASSWORD="dummypass"
   #The LDAP background user -- the webservices use this to query for valid users, etc
   LDAP_BACKGROUND_USER="gobii-user"
   #The LDAP backround user's password
   LDAP_BACKGROUND_PASSWORD="dummypass"
   #The mail host. This can be your local mail host or a Gmail SMTP server.
   MAIL_HOST="smtp.gmail.com"
   #The mail server's port.
   MAIL_PORT=587
   #The mail user account.
   MAIL_USERNAME="gobii.test@gmail.com"
   #The mail user account's password.
   MAIL_PASSWORD="dummypass"
   #The type of mail server, Gmail defaults to SMTP.
   MAIL_TYPE="SMTP"
   #The mail server's hash
   MAIL_HASH="na"
   #The name of the first crop. This should match what is in the docker hub images.
   CROP1="maize"
   #The name of the first crop. This should match what is in the docker hub images.
   CROP2="wheat"
   #The web host's domain name or IP address
   WEB_HOST="172.1.2.3"
   #The web host's web server port. This should match what is in the *_main.parameter file.
   WEB_PORT="8081"
   #The first crop's context path (the web application). This should match what is in the docker hub images.
   CROP1_CONTEXT_PATH="/gobii-maize"
   #The second crop's context path (the web application). This should match what is in the docker hub images.
   CROP2_CONTEXT_PATH="/gobii-wheat"
   #The database host's domain name or IP address
   DB_HOST="172.1.2.4"
   #The database host's postgres port. This should match what is in the *_main.parameter file.
   DB_PORT="5433"
   #The main GOBII database user
   DB_USERNAME="dummyuser"
   #The main GOBII database user's password. If you want to change this password, you can do so once the whole automated deployment finish successfully. But make sure after changing it in postgres, change the corresponding tag in the gobii-web.xml file.
   DB_PASS="dummypass"
   #The database name of the first crop. This should match what is in the docker hub images.
   DB_NAME_CROP1="gobii_maize"
   #The database name of the second crop. This should match what is in the docker hub images.
   DB_NAME_CROP2="gobii_wheat"
   #KDCompute related params used by gobiiconfig jar
   #KDcompute host
   KDC_HOST="kdchost"
   #KDcompute port
   KDC_PORT="8083"
   #kdcompute application context on server
   KDC_CONTEXT_PATH="kdcompute"
   #KDcompute job start param
   KDC_JOB_START="qcStart"
   #KDcompute job status param
   KDC_JOB_STATUS="qcStatus"
   #KDcompute job downloand
   KDC_JOB_DOWNLOAD="qcDownload"
   #Seconds to wait between status checks
   KDC_JOB_CHECK_STATUS="60"
   #Minutes until job is hung
   KDC_JOB_FAIL_THRESHOLD="2880"
   #KDcompute purge the jobs
   KDC_PURGE="qcPurge"
   #KDcompute is active (false|true) for GOBII 
   KDC_ACTIVE="false"
   
   
   

   You can name this file however you want, just as long as you specify the correct name in the CONFIGURATOR_PARAM_FILE value of main.parameter file in step 3.

   As of version 1.3, the *install.parameter file is also passed as a parameter to the main call to the gobii_ship scripts. Hence, it is not necessary to be set in the CONFIGURATOR_PARAM_FILE of the *main.parameter file.

   For anything not clear or if you're not sure of what to put on a parameter's value, please ask 00d483e952a2545b0152a4b36870000e.

   
   

4. Run the deployment scripts

   1. If you are deploying GOBii into just one machine, run the_gobii_ship.sh to pull, deploy, and configure all three Docker containers to one target server. To do so, run a command similar to:

      #Usage: bash.sh the_gobii_ship.sh <path-of-main-param-file> <path-of-install-param-file> <dockerhubpassw | askme> <gobii_release_version>
      #Set dockerhubpassw parameter to 'askme' for the script to prompt for password instead.
      
      bash the_gobii_ship.sh params/template_main_<CG Center File Name>.parameters params/template_install_<CG Center File Name>.parameters askme release-1.5-7

      No Sudo

      This script should not be run using sudo, or as the root user. Some commands will automatically prompt you if they need elevated permissions.

      Troubleshooting

      If you made a mistake and want to start over or if there are other Dockers in the server you want to get rid of, do a cleanup by running Docker stop, rm, and rmi.

   2. When deploying GOBii to more than one machine, run three scripts: the_gobii_ship_db.sh, the_gobii_ship_web.sh, and the_gobii_ship_compute.sh – strictly in that order.
      

      Topology Differences

      Regardless of how the GOBii nodes are distributed, you still have to run these three scripts sequentially on their respective servers.

      For example, if you have two servers (servers A and B), and you want to put both the DB and COMPUTE nodes to server A then the WEB node to server B, then you run the_gobii_ship_db.sh in server A first, then go to server B and run the_gobii_ship_web.sh, then finally go back to server A and run the_gobii_ship_compute.sh.

      
      

      1. Run the modularized scripts exactly the same way as you would run the one-server script in 4.a.:

         #Usage: bash.sh the_gobii_ship_<node>.sh <path-of-parms-file> <dockerhubpassw | askme> <gobii_release_version>
         #Set dockerhubpassw parameter to 'askme' for the script to prompt for password instead.
         
         
         #go to DB server and run
         bash the_gobii_ship_db.sh gobii_main.parameters askme release-1.5-7
         #go to WEB server and run
         bash the_gobii_ship_web.sh gobii_main.parameters askme release-1.5-7
         #go to COMPUTE server and run
         bash the_gobii_ship_compute.sh gobii_main.parameters askme release-1.5-7

         
         

         Here you see the importance of having the scripts and the param files together in a directory that's accessible to all servers.

5. After running the deployment scripts and doing the verification step #1 below, turn on LDAP authentication, if it wasn't on already. (details on verification step #2). When turning on LDAP, make sure that the LDAP certificate is loaded to the JVM. You can do so by:

   1. #########
      #run the install cert
      #Usage: bash install_cert.sh </data/mycert.der> <ldap_host> </usr/local/lib/keytool> </usr/local/jdk/jre/lib/cacerts> <changeit>
        
      docker exec gobii-web-node bash -c '
      cd /data/gobii_bundle/config;
      bash install_cert.sh /data/cacert_mgs1.der cbsu_mgs1 /usr/lib/jvm/java-8-oracle/bin/keytool /usr/lib/jvm/java-8-oracle/jre/lib/security/cacerts changeit;
      '
      #########

      You should see a confirmation message saying "certificates added to keystore". Finally, restart Tomcat, making sure it runs via user gadm:

      docker exec gobii-web-node bash -c '
      sudo su gadm;
      sh /usr/local/tomcat/bin/shutdown.sh;
      sh /usr/local/tomcat/bin/startup.sh;
      '

      As you can see, /data/cacart_mgs1.der is the certificate file. The command above looks for it in the web Docker home volume, which is /data. So wherever that volume points to in the host server, make sure you put the DER file there first before running the command. Lastly, the paths to keytool and cacerts will most likely stay the same as we're only distributing Dockers based on Ubuntu, but in case in the future we offer other linux flavor, or JVM changes, then those paths may change.

6. Make sure that the ports you assigned the Dockers with (typically 8081, 5433, and 2222) are open. Otherwise the containers won't be able to communicate with each other and will fail with internal server error 500 (although, in the future, we may have more specific error message than this). The more specific error message will be shown in Tomcat's log (catalina.out). Opening a port will differ from OS to OS. 
   

   1. Just to give you an example, in CentOS 6 and 7:
      
      

      $ sudo iptables -I INPUT -p tcp -m tcp --dport <port_number> -j ACCEPT
      $ sudo service iptables save

7. Make sure that the /data symlink in the web node was created for the LoaderUI to work properly. If not, do the following:

   1. If ran in the same terminal session you ran gobii_ship*.sh scripts, then run this as is, the $BUNDLE_PARENT_PATH variable should be there. If not, replace it with that parameter's value in the *_main.parameters file that you have.

      /data symlink

      sudo ln -sfn $BUNDLE_PARENT_PATH /data 

      If it is not possible for the /data symlink to be created because in the target host, /data is already a directory or, a drive mount point, create a symlink manually from /data/gobii_bundle to point to $BUNDLE_PARENT_PATH/gobii_bundle, effectively still making /data/gobii_bundle point to the correct location.

As of version 1.5, we are adding a new web application called "Timescope". This will allow users to browse and delete data permanently from the database.

With this, there are additional steps that needs to be done – but only needs to be done once (i.e. if you upgrade to any version >1.5 in the future you won't need to do the following anymore).

1. The shell scripts have created a new database user for Timescope, called "timescoper". See Version 1.5. Take note of this. You can either use the default or change the password of this database user.

2. Configure the Timescope web app to use the new timescoper database user

   1. SSH into the web node, then go into the web docker container and switch t:

      1. docker exec -ti <gobii_web_node> bash

   2. Modify the timescope config file ( /usr/local/tomcat/webapps/timescope/WEB-INF/classes/config.properties), replacing the credentials with the ones you made in step 1c.

      1. # Timescope credentials
         #db
         db.username=timescoper
         db.pw=<default or yourpassword if you've changed it>
         #do not change the version parameter
         version=1.5

   3. Reload the webapp via Tomcat Manager

      1. Open your browser and go to <web_node_url>:<web_node_port>, then click on Tomcat Manager
      2. You should see timescope from the link, click "reload":
         
         1. 

To verify that Timescope is properly deployed: Open your browser and navigate to <web_node_url>:<web_node_port>/timescope. Upon initial install, there will only be one superuser account in your Timescope database. The credentials are in this page: Version 1.5. When you first log in, please change this password using the Timescope UI for security. If you cannot access it, contact either  (00d483e952a2545b0152a4b36870000e ) or 00d483e961e2874401621ac073490001.

1. Verify that the deployment was successful and that all Docker containers can communicate with each other. You can do so by a simple test:
   1. Go to the URL of the ExtractorUI for each of your crop. For example, http://yourwebnodeip.or.hostname:8081/gobii-wheat/. You should see a login page:
      
      
      1. If you set "TEST" as the value to the authentication protocol in the earlier param file, you can use the test user here, USER_READER. If not, and your LDAP is connected, you use a valid user credential in your LDAP system.
   2. Click login. You should see the extractorUI page:
      
   3. Simply select any value for the Principal Investigator, Project, and Experiment (or just leave them at the defaults). Make sure the data sets checkbox is ticked. Also, make sure the principal investigator drop-down gets populated with names.
      
   4. Click submit.
   5. Verify that the "Status Message" box shows the following:
      
   6. If you have more than one crop, try navigating to the other crop by the crop dropdown:
      

   7. Congratulations! This verifies that your Dockers are all running and communicating with each other.

      Rationale

      Web Docker is working as the login to the web application goes through, even with the test user USER_READER.

      Database Docker is working as the drop-down controls in the extractor UI get populated with values.

      Compute docker is working as the "Status Message" box didn't show any errors when you submitted a job.

      IP addresses/Host names are correct as you were able to navigate from one crop to another.

2. Verify that your LDAP is connected properly to GOBii.

   1. To turn on LDAP authentication, do the following:
      1. Go to web Docker's host server
      2. Navigate to /data/gobii_bundle/config/
      3. Open gobii-web.xml for editing
      4. Change the value of gobiiAuthenticationType to LDAP, ie. <gobiiAuthenticationType>LDAP</gobiiAuthenticationType>
      5. Save the file

      6. Restart the web server via:

         Restarting the web server

         docker exec -ti -u gadm gobii-web-node bash
         sh /usr/local/tomcat/bin/shutdown.sh
         sh /usr/local/tomcat/bin/startup.sh

         Make sure Tomcat always run under the docker user gadm. This ensures that files created via the web server will always get proper group permissions.

   2. Verify that LDAP is working by doing everything in verification step #1, only this time using a valid LDAP user instead of the user USER_READER.

   3. You should now get an email like the one below:
      

      This is expected to fail as you don't have any data to extract yet, but you have verified that everything's working, including the mailer.

3. Verify that the LoaderUI is working by loading valid files from your projects.

1. Backup the data files from the existing GOBii instance. You can do so by using the backup script we provide. You can find usage instructions here: Version 1.5#onScripts-IncrementalDataBundleBackups. Ideally, you already have this setup to do incremental backups (as a cron job), so that prior to the upgrade you just need to do run the script in incremental mode to make sure you capture all changes, then disable access to the system to make sure nobody loads new data while the upgrade is in progress. If that's not the case, you can run the script on full backup mode – just note that this may take several hours depending on the size of your data.
2. Backup the database (postgres) from the existing GOBii instance. You have two options:
   1. Run the script we provide (Version 1.5#onScripts-PostgresqlRotatingIncrementalBackup) - this also is ideally set up as a cron job.
   2. Manually back up the database

      1. Go into the database node and run pg_dumpall

         $> docker exec -ti <gobii_db_node> bash
         $> su postgres
         $> pg_dumpall > /data/all_databases.bak

   3. The data from postgres actually persists as long as you don't delete the Docker volumes. However, we still recommend you back up the database to make sure we have redundancy.

3. OPTIONAL: If you have KDCompute Docker container running, back up its files by copying the directory /data/kdcompute_file_storage to a directory of your choice. This contains previous output and logs of QC jobs.

1. The official repository for the deployment scripts is here. Make sure you clone or download the scripts from there. The branch you should get is release/<version> (ex. release/1.5). You can also get the master branch if you are deploying the latest, but because our clients can have varying versions on different servers, all release branches are kept.
2. Ensure that your *.param files are updated. There are two possibilities that they are not: we added new parameters (in which case, always compare the templates you get from the scripts git repo as we always update those accordingly) OR you manually changed something from the gobii-web.xml (ex. new email address, password changed, etc.) and so those changes need to be captured in the param files as well.

   1. This step is very important as wrong parameter values may ruin the GOBii instance you are deploying to or worse, another instance you are not deploying to (in the case of a wrong server address).

3. Run the_gobii_ship scripts (or the 3 per-module scripts, depending on your topology) on your server, using the parameter files from step 1. The way to run the scripts is the same as if you're installing from scratch. It will handle the Docker container replacement for you. The steps are below for your reference:

   1. Run the deployment scripts

      1. If you are deploying GOBii into just one machine, you run the_gobii_ship.sh to pull, deploy, and configure all three Docker containers to one target server. To do so, you run a command similar to:

         #Usage: bash.sh the_gobii_ship.sh <path-of-main-param-file> <path-of-install-param-file> <dockerhubpassw | askme> <gobii_release_version>
         #Set dockerhubpassw parameter to 'askme' for the script to prompt for password instead.
         
         bash the_gobii_ship.sh main_<CG Center File Name>.parameters install_<CG Center File Name>.parameters askme release-1.5-7

         No Sudo

         This script should not be run using sudo or as the root user. Some commands will automatically prompt you if they need elevated permissions.

         Troubleshooting

         If you made a mistake and want to start over or if there are other Dockers in the server you want to get rid of, do a cleanup by running Docker stop, rm, and rmi.

      2. when deploying GOBii to more than one machine, run three scripts: the_gobii_ship_db.sh, the_gobii_ship_web.sh, and the_gobii_ship_compute.sh – strictly in that order.
         

         Topology Differences

         Regardless of how the GOBii nodes are distributed, you still have to run these three scripts sequentially on their respective servers.

         For example, if you have two servers (servers A and B), and you want to put both the DB and COMPUTE nodes to server A then the WEB node to server B, then run the_gobii_ship_db.sh in server A first, then go to server B and run the_gobii_ship_web.sh, then finally go back to server A and run the_gobii_ship_compute.sh.

         
         

         1. Run the modularized scripts exactly the same way  you would run the one-server script in 4.a.:

            #Usage: bash.sh the_gobii_ship_<node>.sh <path-of-parms-file> <dockerhubpassw | askme> <gobii_release_version>
            #Set dockerhubpassw parameter to 'askme' for the script to prompt for password instead.
            
            
            #go to DB server and run
            bash the_gobii_ship_db.sh gobii_main.parameters askme release-1.5-7
            #go to WEB server and run
            bash the_gobii_ship_web.sh gobii_main.parameters askme release-1.5-7
            #go to COMPUTE server and run
            bash the_gobii_ship_compute.sh gobii_main.parameters askme release-1.5-7

            
            

            Here you see the importance of having the scripts and the param files together in a directory that's accessible to all servers.

   2. Once the script is done, you should have the new Dockers. Verify by running:
      

      1. docker ps -qa

4. OPTIONAL: Install KDC

   1. The KDC installation script also uses the GOBii param files. Make sure you have the correct KDC values in before running the script. Also, back up the kdcompute_file_storage before running this. The command is almost the same as the_gobii_ship.sh

      1. #Usage: bash the_gobii_ship_kdc.sh <path-of-main-param-file> <path-of-install-param-file> <dockerhubpassw | askme> <kdc_release_version>
         #example
         bash the_gobii_ship.sh main_<CG Center File Name>.parameters install_<CG Center File Name>.parameters askme 1.5.2

         Take note that the kdc_release_version is different from the GOBii release version. As of the time of this writing, the latest version is 1.5.2. You can find all versions here: https://hub.docker.com/r/gadm01/gobii_kdc_ubuntu/tags/

1. Simply run the restore script with the correct parameters: Version 1.5#onScripts-RestoreDataBundlefromBackup

   1. Go to the link above, as the syntax in running these scripts have changed slightly from version 1.4.

2. Verify that the data was restored by opening any crop's ExtractorUI. You should see previously loaded datasets.
3. OPTIONAL: If you have a KDCompute Docker container running before, restore its files from backup simply by copying the TestOutput_UserDirs subdirectory of kdcompute_file_storage backup to /data/kdcompute_file_storage/TestOutput_UserDirs

As of version 1.5, we are adding a new web application called "Timescope". This will allow users to browse and delete data permanently from the database.

With this, there are additional steps that needs to be done – but only needs to be done once (i.e. if you upgrade to any version >1.5 in the future you won't need to do the following anymore).

1. Create the database user for timescope:

   1. SSH into the database node, then go into the database Docker container via:

      docker exec -ti <gobii_db_node> bash

   2. Switch to the postgres user

      1. su - postgres 

   3. Create the timescoper db user

      1. create user timescoper with superuser password 'yourpasswordofchoice' valid until 'infinity';

2. Configure the Timescope web app to use the newly created timescoper database user

   1. SSH into the web node, then go into the web Docker container and switch t:

      1. docker exec -ti <gobii_web_node> bash

   2. Switch to the gadm user

      1. su - gadm

   3. Modify the timescope config file ( /usr/local/tomcat/webapps/timescope/WEB-INF/classes/config.properties), replacing the credentials with the ones you made in step 1c.

      1. # Timescope credentials
         #db
         db.username=timescoper
         db.pw=yourpasswordofchoice
         #do not change the version parameter
         version=1.5

   4. Reload the webapp via Tomcat Manager

      1. Open your browser and go to <web_node_url>:<web_node_port>, then click on Tomcat Manager
      2. You should see timescope from the link, click "reload":
         
         1. 

To verify that Timescope is properly deployed: Open your browser and navigate to <web_node_url>:<web_node_port>/timescope. Upon initial install, there will only be one superuser account in your Timescope database. The credentials are in this page: Version 1.5. When you first log in, please change this password using the Timescope UI for security. If you cannot access it, contact either (00d483e952a2545b0152a4b36870000e ) or 00d483e961e2874401621ac073490001.