Merge pull request #2591 from robkooper/modelinfo_dockerfile_template

add dockerfile, model_info.json to template (fixes #2567)

CHANGELOG.md

@@ -35,6 +35,7 @@ For more information about this file see also [Keep a Changelog](http://keepacha
 - PEcAn.JULES: Removed dependency on `ncdf4.helpers` package, which has been removed from CRAN (#2511).
 
 ### Added
+- model_info.json and Dockerfile to template (#2567)
 - Dockerize BASGRA_N model.
 - Basic coupling for models BASGRA_N and STICS.
 - PEcAn.priors now exports functions `priorfig` and `plot_densities` (#2439).

models/template/.Rbuildignore

@@ -0,0 +1,2 @@
+Dockerfile
+model_info.json

models/template/Dockerfile

@@ -0,0 +1,69 @@
+########################################################################
+# First we build the actual model, this has everything that is needed
+# for the model to compile. Next we create the final image that has the
+# PEcAn code as well as only the model binary.
+########################################################################
+
+# this needs to be at the top, what version are we building
+ARG IMAGE_VERSION="latest"
+
+# ----------------------------------------------------------------------
+# BUILD MODEL BINARY
+# ----------------------------------------------------------------------
+FROM debian:stretch as model-binary
+
+# Some variables that can be used to set control the docker build
+ARG MODEL_VERSION=git
+
+# install dependencies
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       build-essential \
+       curl \
+       gfortran \
+       git \
+       libhdf5-dev \
+       libopenmpi-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# download, unzip and build ed2
+WORKDIR /src
+RUN git clone https://github.com/model/repo.git \
+    && cd repo \
+    && if [ "${MODEL_VERSION}" != "git" ]; then git checkout "v.${MODEL_VERSION}"; fi \
+    && ./configure \
+    && make
+
+########################################################################
+
+# ----------------------------------------------------------------------
+# BUILD PECAN FOR MODEL
+# ----------------------------------------------------------------------
+FROM pecan/models:${IMAGE_VERSION}
+
+# ----------------------------------------------------------------------
+# INSTALL MODEL SPECIFIC PIECES
+# ----------------------------------------------------------------------
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       libgfortran3 \
+       libopenmpi2 \
+    && rm -rf /var/lib/apt/lists/*
+
+# ----------------------------------------------------------------------
+# SETUP FOR SPECIFIC MODEL
+# ----------------------------------------------------------------------
+
+# Some variables that can be used to set control the docker build
+ARG MODEL_VERSION=git
+
+# Setup model_info file
+# @VERSION@ is replaced with model version in the model_info.json file
+# @BINARY@ is replaced with model binary in the model_info.json file
+COPY model_info.json /work/model.json
+RUN sed -i -e "s/@VERSION@/${MODEL_VERSION}/g" \
+           -e "s#@BINARY@#/usr/local/bin/model#g" /work/model.json
+
+# COPY model binary
+COPY --from=model-binary /src/repo/src/model /usr/local/bin/model

models/template/README.md

@@ -8,7 +8,8 @@ Adding a new model to PEcAn in a few easy steps:
 3. implement 3 functions as described below
 4. Add tests to `tests/testthat`
 5. Update README, documentation
-6. execute pecan with new model
+6. Update Dockerfile and model_info.json
+7. execute pecan with new model
 
 
 ### Three Functions
@@ -39,6 +40,41 @@ it is defined in the BETY database.
  format. After this function is finished PEcAn will use the generated
  output and not use the model specific outputs. The outputs should be
  named YYYY.nc
+
+### Dockerization
+
+The PEcAn system is leveraging Docker to encapsulate most of the code.
+This will make it easier to share new model with others, without them
+having to compile the models. The goal is for people to be able to
+launch the model in docker, and it will register with PEcAn and is
+almost immediatly available to be used. To accomplish this you will need to modify two files.
+
+* `Dockerfile`
+
+ The [Dockerfile](https://docs.docker.com/engine/reference/builder/) is
+ like the Makefile for docker. This file is split in two pieces the
+ part at the top is to actually build the binary. This is where you
+ specify all the libraries that are needed, as well as all the build
+ tools to compile your model. The second part, starting at the second
+ `FROM` line, is where you will install only the libraries needed to
+ run the binary and copy the binary from the build stage, using the
+ `COPY --from` line.
+
+* `model_info.json`
+
+ The model_info.json describes the model and is used to register the
+ model with PEcAn. In the model_info.json the only fields that are
+ really required are those at the top: `name`, `type`, `version` and
+ `binary`. All other fields are optional but are good to be filled
+ out. You can leave `version` and `binary` with the special values
+ which will be updated by the Dockerfile.
+
+Once the image can be build it can be pushed so others can leverage
+of the model. For PEcAn we have been using the following naming scheme
+for the docker images: `pecan/model-<model>-<model_version>:<pecan_version>`
+where the `model` and `model_version` are the same as those used to
+build the model, and `pecan_version` is the version of PEcAn this
+model is compiled for.
 
 ### Additional Changes
 

models/template/model_info.json

@@ -0,0 +1,36 @@
+{
+  "name": "Name of model, displayed in UI",
+  "type": "Type of model",
+  "version": "@VERSION@",
+  "binary": "@BINARY@",
+  "description": "Longer description of the model, right now only displayed in the monitor",
+  "creator": "Main creator of model",
+  "contributors": ["List of contributors", "Both for model", "And PEcAn code for model"],
+  "links": [
+    {
+      "type": "git",
+      "description": "Link to source code, if not exist, just remove",
+      "url": "https://github.com/...."
+    },
+    {
+      "type": "issues",
+      "description": "Link to issues, if not exist, just remove",
+      "url": "https://github.com/..../issues"
+    },
+    {
+      "type": "documentation",
+      "description": "Link to documentation, if not exist, just remove",
+      "url": "https://github.com/..../wiki"
+    },
+    {
+      "type": "docker",
+      "description": "Link to docker image, if not exist, just remove",
+      "url": "organization/image"
+    }
+  ],
+  "inputs": {},
+  "bibtex": [
+    "How to cite the model, paper 1",
+    "How to cite the model, paper 2"
+  ]
+}