nrel/openstudio repository overview

⁠OpenStudio

This repo provides a container for OpenStudio as well as several dependencies, including Ruby 2.x, Bundler, build-essentials and various development libraries for gem support.

At the moment, there are two target containers for this project, Docker and Singularity⁠. We are working on a slim version container.

⁠Docker Tags

Below is a table of the various docker tags and their meanings as seen on this page⁠.

⁠Building OpenStudio Container

These images are automatically built in TravisCI. To trigger TravisCI for a new build do the following:

• On develop branch update the .travis.yml⁠ with the new version of OpenStudio and SHA

   - OPENSTUDIO_VERSION: 2.9.1
   - OPENSTUDIO_SHA: 3472e8b799
  

  Copy

• Push changes to feature branch, make and merge a pull-request to develop

• Wait for CI to finish and verify new develop image is available on docker hub⁠.

• Test locally (if needed)

  docker pull nrel/openstudio:develop
  docker run -it --rm nrel/openstudio:develop bash
  irb
  require 'openstudio'
  puts OpenStudio.getOpenStudioCLI
  

  Copy

⁠Building Locally

Begin by installing the docker tool-kit⁠ version 17.03.1 or later, as described in the linked documentation. Once the tool-kit is installed and activated, run the command below to build the base image with OpenStudio 2.6.1.

docker build --target base -t openstudio-local --build-arg OPENSTUDIO_VERSION=2.9.1 --build-arg OPENSTUDIO_SHA=3472e8b799 .

The version of OpenStudio and the SHAs are listed here⁠.

If the --target is not passed, then the docker build will contain only the CLI.

⁠Executing OpenStudio Container

There are two options to acquire the docker container required for execution. Both assume that the docker tool-kit⁠ version 17.03.1 or later is installed. The first option, building the container from a GitHub checkout, is outlined above. Additionally, it is typically easiest to tag the resulting container⁠ as nrel/openstudio:latest. For a more extensive discussion of the latest tag and associated best practices please refer to this Medium article⁠. The second option, downloading a release from DockerHub, requires determining the docker-openstudio tagged release⁠ that is desired, and then running docker pull nrel/openstudio:<tag>. As an example, to download the 2.9.1 docker-openstudio image, the command would be docker pull nrel/openstudio:2.9.1.

Once the desired container is available, either through a build or pull process, the next step is to run the container. To simply access the container tagged with 'tag', (where tag was respectively 'latest' or '2.9.1' in the above paragraph,) run docker run -it --rm nrel/openstudio:tag /bin/bash.

To execute an OpenStudio Workflow directly from the command line requires mounting the requisite files to the container⁠, as well as invoking the OpenStudio CLI⁠ (command line interface.) The docker container by default executes commands in the /var/simdata/openstudio directory, (this is defined in the Dockerfile⁠.) If the desired OSW was located at /Users/myuser/demo_os_files/example.osw on the host computer, the appropriate docker command to execute the OSW would be docker run -it --rm -v=/Users/myuser/demo_os_files:/var/simdata/openstudio nrel/openstudio /usr/bin/openstudio run -w example.osw

If gem dependencies are required as part of the CLI outside of those packed with OpenStudio⁠ please contact Kyle Benne, Tim Coleman, or Nicholas Long at their NREL email addresses.

⁠Releasing New Containers

• Update the

⁠Issues

Please submit issues on the project's Github⁠ page.