add tutorial on how to run test db

Author: kimberlyh66

metadata/test_database_tutorial.Rmd

@@ -0,0 +1,132 @@
+---
+title: "How to set up local instance of BETY test database using Docker"
+author: "Kimberly Huynh"
+date: "4/19/2019"
+output: html_document
+---
+
+# Overview
+
+The purpose of this tutorial is to demonstrate how to set up a local instance of the BETY test database. 
+
+You will want to set up this test database when preparing to upload data to the master database.
+
+You should make sure that your data can be succesfully uploaded to the test database before trying to upload to master.
+
+# Requirements:
+
+To run a local instance of the BETY test database, you will need to have the following installed on your computer:
+
+   * Docker
+   
+   * PostgreSQL
+
+## Install Docker
+
+The BETY database will be run using Docker. You will be able to access the database by running docker `containers`.
+
+Visit [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop) to download Docker for MAC or Windows. You will need to create a docker account.
+
+## Install PostgreSQL
+
+After you have BETY running, you can connect to the database using the psql command line. You can run queries against the database using this tool.
+
+Visit [https://www.postgresql.org/download/](https://www.postgresql.org/download/) to download PostgreSQL. 
+
+# How to set up and run BETY using docker
+
+Note: You only need to run steps 1 (clone repo), 2 (create docker-compose.override.yml), and 3 (initialize BETY database) the first time you set up BETY. 
+
+After initial set up, you will only need to run step 4 to restart the database. 
+
+## Step 1: Clone bety repository
+
+In a directory of your chioce, clone the bety repository from github and cd to the bety folder:
+
+```sh
+git clone https://github.com/PecanProject/bety.git
+cd bety
+```
+
+## Step 2: Create a `docker-compose.override.yml`
+
+You will need to mount the postgres container to port 5433. This can be done by creating a `docker-compose.override.yml` file in the bety folder. 
+
+Copy and paste the following chunk into the file: 
+
+```sh
+version: "3"
+services:
+  postgres:
+    ports:
+      - 5433:5432
+```
+
+## Step 3: Initialize BETY database
+
+Once you have set up the docker-compose.override.yml file, you should follow these next steps to initialize the database:
+
+```sh
+# Start postgres
+docker-compose -p bety up -d postgres
+# Initialize BETY database
+docker run -ti --rm --network bety_bety -e BETY_INITIALIZE_URL='-w https://terraref.ncsa.illinois.edu/bety/dump/bety0/bety.tar.gz' pecan/bety:terra initialize
+# Sync with server 6 only
+docker run -ti --rm --network bety_bety -e REMOTE_SERVERS='6' pecan/bety:terra sync
+```
+
+## Step 4: Bring up all containers
+
+```sh
+# Bring up full stack
+docker-compose up
+```
+
+You should see something like the following chunk with a cursor blinking on next line:
+
+```sh
+Creating network "bety_bety" with the default driver
+Creating bety_postgres_1 ... done
+Creating bety_bety_1     ... done
+Attaching to bety_postgres_1, bety_bety_1
+postgres_1  | LOG:  database system was interrupted; last known up at 2019-04-19 19:24:36 UTC
+bety_1      | Start running BETY (unicorn)
+postgres_1  | LOG:  database system was not properly shut down; automatic recovery in progress
+postgres_1  | LOG:  invalid record length at 9/261ACFF0
+postgres_1  | LOG:  redo is not required
+postgres_1  | LOG:  MultiXact member wraparound protections are now enabled
+postgres_1  | LOG:  database system is ready to accept connections
+postgres_1  | LOG:  autovacuum launcher started
+bety_1      | I, [2019-04-19T21:58:45.786271 #1]  INFO -- : Refreshing Gem list
+bety_1      | I, [2019-04-19T21:58:51.121928 #1]  INFO -- : listening on addr=0.0.0.0:8000 fd=8
+bety_1      | I, [2019-04-19T21:58:51.147507 #1]  INFO -- : master process ready
+bety_1      | I, [2019-04-19T21:58:51.149629 #7]  INFO -- : worker=0 ready
+```
+## Step 5: Connect to test database using psql command line
+Open a new tab in the terminal and connect to the test database using:
+```sh
+psql -h localhost -p 5433 -U bety
+```
+You should see the following prompt if you have succesfully logged into the test database:
+```sh
+psql (11.2, server 9.5.16)
+Type "help" for help.
+bety=> 
+```
+## Step 6: Exit from psql command line and stop containers
+Once you are done working with the test database, exit the psql command line by typing `exit` following the `bety=>` prompt.
+```sh
+bety=> exit
+```
+To bring down all containers run:
+```sh
+docker-compose down
+```
+You should see the following output after running docker-compose down
+```sh
+Stopping bety_bety_1     ... done
+Stopping bety_postgres_1 ... done
+Removing bety_bety_1     ... done
+Removing bety_postgres_1 ... done
+Removing network bety_bety
+```