## Using Dockter

This document will take you through using Dockter to make your work reproducible and easy to reuse.

#### Prerequisites

You should have some basic working knowledge of Docker. [This hands-on tutorial](https://ome.github.io/training-docker/) is a good way to start. You can also
check out the [Katakoda set of Docker courses](https://www.katacoda.com/courses/docker).

#### Motivation

We encourage you to have a look at the above courses but the idea behind Dockter is that you don't need to master Docker. Dockter does most of the things for you
in order to set up a reproducible research environment.

Dockter is a tool to make it easier for researchers to create reproducible research environments. It generates a Docker image for a research project based on the source code in it. That means that you don’t need to learn a new file format (`Dockerfiles`) to create Docker images. Dockter makes it also easy to track dependencies and update the image when they change.

In addition, Dockter manages the image building process to better fit your everyday workflow (determines package system dependencies, manages builds) and generates JSON-LD meta-data describing the image (from which citations etc can be generated).

You can manually edit the files which Dockter generates so that the containers build of it exactly suit your project. 

#### 1. Install

a) Download the latest stable binary package (ready to run) [for your operating system](https://github.com/stencila/dockter/releases):

b) Copy the binary file into the folder where you would like Dockter to be (eg. `Applications` on your Mac OS, or `Program Files` on Windows). 

c) Once the file is downloaded, rename it to `dockter`  Dockter is a command line tool (at least for now) so you need to interact with it through the terminal (on Windows it will be Power Shell). 

**Basic use**

```
  dockter compile [folder] [format]  Compile a project to a software environment
  dockter build [folder]             Build a Docker image for project
  dockter execute [folder] [format]  Execute a project
```


#### 2. Dockter for R

Dockter can create a software environment file which reflects the requirements to run the project written in R.
The software environment file is a file in `JSON` or `yaml` format with comprehensive meta data about the project.
Dockter parses the folder with the R project for `R` and `Rmd` files and extracts the relevant information.

 * For each R package installed or loaded, the meta data is retrieved from [CRAN](http://crandb.r-pkg.org).
    - The packages must be installed and loaded using the standard R command syntax: `install.packages()` and `library()`. If the R source code
    includes a non-standard syntax, for example to load a number of packages in one go using `lapply()`, Dockter will not be able to recognize it and
    the information about the required packages will not be recorded.
 * System dependencies for each package are obtained from [R-Hub](https://sysreqs.r-hub.io/pkg/xml2).
 * Meta data about the authors, title, abstract and so on.


#### 3. Dockter for Python

Dockter can create a software environment file which reflects the requirements to run the project written in Python.
The software environment file is a file in `JSON` or `yaml` format with comprehensive meta data about the project.
Dockter parses the folder with the Python project for `py` files and extracts the relevant information.

#### 4. Examples

**R**

The [r-spatial](r-spatial/) folder includes an example R project based on one of  on the tutorials [Geocoding in R by Claudia Engel](http://www.rpubs.com/cengel248/97543). This series of tutorials is a pretty comprehensive course introducing geospatial researchers into the
world of R. The challenge of getting to run these tutorials hands-on (including trying to complete the exercises included) is that 
the user needs to install a number of R packages for geospatial research and some packages for dealing with formats such as `xml` or `json`.
So there is already one obstacle that an R novice will face - dealing with packages, their versions and compatibilities. One package in particular,
[rgdal]() [requires some system-wide (non-R) libraries](https://gist.github.com/dncgst/111b74066eaea87c92cdc5211949cd1e) to be installed. This
requirement is actually not that easy to figure out from the error messages coming up when you try `install.packages("rgdal")`. So that's
another potential major issue for an R newbie. Not to mention that getting these libraries installed will differ depending on the OS version
that the user is on.

Most of these geospatial-specific packages are unlikely to be available on popular cloud R services out-of-the-box. Hence, if a geospatial researcher
would like to learn how to use R for their work through the above tutorials, they are likely to spend some amount of (frustrating) time trying to set up
the environment. At the same time, the author of the tutorials would have to put a lot of extra time in learning and building up the infrastructure (such
as VMs or containers) to recreate the whole environment.

Here's where Dockter comes handy.

```
dockter compile r-spatial/
```

creates 3 files inside the project folder:

```

```

```
```

```
{
  "@context": "https://stencila.github.io/schema/context.jsonld",
  "type": "SoftwareEnvironment",
  "name": "r-spatial",
  "softwareRequirements": [
    {
      "type": "SoftwarePackage",
      "name": "rspatial",
      "datePublished": "2018-11-04",
      "runtimePlatform": "R"
    }
  ]
}
```



### Resources

[A beginner's guide to containters](https://medium.freecodecamp.org/a-beginner-friendly-introduction-to-containers-vms-and-docker-79a9e3e119b)