OCI:Set up account

• Tutorial 1 OCI:Set up account THIS TUTORIAL
• Tutorial 2: OCI:Upload files for docking
• Tutorial 3: OCI:Submit docking job
• Tutorial 4: OCI:Merge and download results
• Tutorial 5: OCI:Cleanup

Installation

Docker is required to run the oci-setup scripts. https://www.docker.com/get-started/. You can install docker desktop to your personal machine, or log on to a machine where docker is already installed.

An Oracle OCI account is also required, with payment attached. (payment page goes here)

On a linux/mac/windows computer with docker or docker desktop installed, run the following commands in a terminal:

docker pull dockingorg/oci-setup
docker run -v /var/run/docker.sock:/var/run/docker.sock --rm -it dockingorg/oci-setup

Explanation of arguments:

• -v /var/run/docker.sock:/var/run/docker.sock Allows the container to use your system's Docker
• --rm Cleans up the container once you've exited
• -it Runs the container interactively

It may be necessary to give the container additional privileges. When you enter the image, test this with the following command:

root@f54f423d64b1:/home/ociuser# docker ps

If you get a permission denied error, exit the container and run again with the --privileged option enabled:

docker run --privileged --rm -v /var/run/docker.sock:/var/run/docker.sock -it dockingorg/oci-setup

Container Environment

The container uses the ubuntu distribution. Some utilities such as curl and vi are installed so you can download files and edit them. You can also install whatever software you like using "apt install", e.g "apt install git".

If you have files you'd like to access from the container, you can link them in using the docker "-v" option. By default we link the docker socket using this option ("-v /var/run/docker.sock:/var/run/docker.sock"), but you can link any number of directories or files in this manner. For example, if you would like the contents of the "/tmp" directory on your local machine to be available under "/temp" in the docker image, you would add the following option to your "docker run" command: "-v /tmp:/temp", for a final command of:

docker run -v /tmp:/temp -v /var/run/docker.sock:/var/run/docker.sock --rm -it dockingorg/oci-setup:latest

If you're an advanced user and you'd like to create your own version of the oci-setup image with certain software preinstalled, you can request us for access to the oci-setup repository, which contains the scripts and Dockerfile we use to set up the docker image. You can also build your own image using our oci-setup image as a base.

Quickstart - Creating your first OCI docking environment

Setup

Credentials & Region

When you enter the docker image, you will be in /home/ociuser. There should be two directories in front of you, oci-setup and ocidock. We start off by going into the oci-setup directory and configuring our OCI credentials. (This needs to be done every time you log in to the container)

root@f54f423d64b1:/home/awsuser# cd oci-setup
root@f54f423d64b1:/home/awsuser# oci configure

You'll now be prompted to enter your OCI access key ID & OCI secret access key. If you already know what these are you can enter them and move on. If you don't know what your OCI secret key and access key are, follow this tutorial: (my secret access key web page) Make sure to save your keys somewhere safe that you will remember!!

Next, you'll be prompted on which OCI region you would like to use. If this is your first environment, set the region to (oci region). Our lab's molecule data OCI bucket (zinc3d) is also located in this region, so this is the most economical region to run docking jobs in, due to the cost of moving data between OCI regions. (see diagram)

Diagram showing the cost of transferring S3 data between regions and across to the internet

More info on regions & region codes here: (oracle zones)

The last prompt sets the preferred output format- feel free to leave this blank, or set it to "json".

S3 Bucket

An OCI bucket is a virtual hard drive that your OCI resources can access from anywhere. You will need to create one on your account prior to creating your OCI environment. Follow the Oracle tutorial on how to do this: (how to create a bucket in OCI)

The quickstart guide will show you how to create an OCI environment in (region), so it is best to create your OCI bucket in this region.

It is best to have a dedicated OCI bucket for each region you create an environment for, due to the cost of inter-region data transfer.

Diagram explaining how to create an S3 bucket. Note the region- N.Virginia aka (regions). This is the optimal region for running docking.

First time setup

If it is your first time setting up an environment on your OCI account, you will need to run initialize-aws-batch.bash. This script only needs to be run once per account.

root@f54f423d64b1:/home/ociuser/oci-setup# bash initialize-oci-batch.bash

You should see this script spit out a bunch of JSON text. If you accidentally run this script when it has already been run before, you may see a bunch of errors along the lines of: "Service role name <blank> has been taken in this account". Don't worry about these, they don't mean anything.

Environment Creation

root@f54f423d64b1:/home/awsuser/oci-setup# bash create-oci-batch-env.bash /home/awsuser/ocidock/oci-setup-configs/ocidock_quickstart.config

The quickstart configuration will name your environment (ashburn??). This name serves as the unique identifier for this environment, you'll refer to it later when submitting jobs. If you try to create an environment that already exists with the same name, the script will update the existing environment instead of creating a new one.

If you would like to set up an environment with a different name or based in a region other than (ashburn??), you can use oci-setup-configs/ocidock.config instead.

Attach the bucket you created to the environment. Don't qualify this with the (oci://??) path, just the plain name.

Set MAX_CPUS for your environment to desired value. This parameter refers to the maximum number of jobs that can be run in parallel. You should set this at or below the suggested value- this value is derived from the OCI-imposed resource limit. You can learn more about resource limits and how to increase them at this page: Docking_Submission_On_OCI#Resource_Limits

Set BID_PERCENTAGE for your environment to desired value. See section below for more explanation of this parameter, it can potentially save you money. If you're not sure, keep the default.

Bid Percentage

In order to save money, our OCI batch environment uses the "spot" allocation strategy, which allows us to bid on compute resources at a discount.

The BID_PERCENTAGE parameter indicates what % of the on-demand price our environment is willing to pay for compute resources. At 50%, the environment will wait for at least a 50% discount of the on-demand price to be available before purchasing resources. At 100%, the environment will pay lower prices when they're available, but failing that will pay the full on-demand price. This is the best option for those that want to save money but also don't want to waste time.

Advanced Usage

For advanced usage of the oci-setup tool, see here: OCI DOCK Environment Setup Advanced Usage