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 is only one target container for this project, however, we are working on containers for a slim version and a version compatible with Singularity.
Below is a table of the various docker tags and their meanings as seen on this page.
| Tag | Description |
|---|---|
| x.y.z | Build of official OpenStudio release (recommended use) |
| latest | Latest official release of OpenStudio (e.g. 2.5.1) |
| develop | Release of develop branch |
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.6.0 - OPENSTUDIO_SHA: e3cb91f98a
-
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
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.6.1 --build-arg OPENSTUDIO_SHA=ab0dddde0b .
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.
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.1.1 docker-openstudio image, the command would
be docker pull nrel/openstudio:2.1.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.1.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, Ry Horsey, and Dan Macumber at their NREL email addresses.
Please submit issues on the project's Github page.