docker.html



<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Using OpenDrift in a container &mdash; OpenDrift  documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=4ae1632d" />
      <link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
      <link rel="stylesheet" type="text/css" href="_static/sg_gallery.css?v=d2d258e8" />
      <link rel="stylesheet" type="text/css" href="_static/sg_gallery-binder.css?v=f4aeca0c" />
      <link rel="stylesheet" type="text/css" href="_static/sg_gallery-dataframe.css?v=2082cf3c" />
      <link rel="stylesheet" type="text/css" href="_static/sg_gallery-rendered-html.css?v=1277b6f3" />
      <link rel="stylesheet" type="text/css" href="_static/theme_overrides.css" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="_static/documentation_options.js?v=5929fcd5"></script>
      <script src="_static/doctools.js?v=9bcbadda"></script>
      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Graphical User Interface" href="gui.html" />
    <link rel="prev" title="Interaction with coastline" href="interaction_with_coastline.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          <a href="index.html" class="icon icon-home">
            OpenDrift
              <img src="_static/opendrift_logo.png" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul>
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to OpenDrift</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="history_link.html">History</a></li>
<li class="toctree-l1"><a class="reference internal" href="install.html">Installing OpenDrift</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance in OpenDrift</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="theory/index.html">Theory</a></li>
<li class="toctree-l1"><a class="reference internal" href="theory/index.html#drift-in-the-ocean">Drift in the Ocean</a></li>
<li class="toctree-l1"><a class="reference internal" href="choosing_a_model.html">How to choose which model to use</a></li>
<li class="toctree-l1"><a class="reference internal" href="writing_a_new_model.html">How to write a new module</a></li>
<li class="toctree-l1"><a class="reference internal" href="gallery/index.html">Gallery</a></li>
<li class="toctree-l1"><a class="reference internal" href="oil_types.html">Oil types</a></li>
<li class="toctree-l1"><a class="reference internal" href="interaction_with_coastline.html">Interaction with coastline</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Using OpenDrift in a container</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#pull">Pull</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build">Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="#singularity">Singularity</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#installation">Installation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pull-the-container">Pull the Container</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-the-image">Using the image</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="gui.html">Graphical User Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="references.html">Publications</a></li>
<li class="toctree-l1"><a class="reference internal" href="services.html">Services using OpenDrift</a></li>
<li class="toctree-l1"><a class="reference internal" href="autoapi/index.html">API Reference</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">OpenDrift</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Using OpenDrift in a container</li>
      <li class="wy-breadcrumbs-aside">
            <a href="_sources/docker.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="using-opendrift-in-a-container">
<h1>Using OpenDrift in a container<a class="headerlink" href="#using-opendrift-in-a-container" title="Link to this heading"></a></h1>
<p>In this tutorial we will walk through building a Docker container with opendrift,
and then interacting with it. If desired, you can use this same container to
create a [Singularity image](<a class="reference external" href="https://www.sylabs.io/guides/3.0/user-guide/">https://www.sylabs.io/guides/3.0/user-guide/</a>) that is usable on
a shared resource cluster. We will do the latter by pulling the image on Docker Hub
directly into a Singularity container. This folder contains two Dockerfiles:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="https://github.com/OpenDrift/opendrift/blob/master/Dockerfile">Dockerfile</a>: builds a vanilla container with opendrift, Python 3</p></li>
</ul>
</div></blockquote>
<section id="pull">
<h2>Pull<a class="headerlink" href="#pull" title="Link to this heading"></a></h2>
<p>These images are available on Docker Hub as <a class="reference external" href="https://hub.docker.com/r/opendrift/opendrift">opendrift/opendrift</a>, with instructions provided
below for building locally. You should look at the “tags” tab of each to determine the
version of Open Drift and Python that you are interested in. For example:</p>
<blockquote>
<div><ul class="simple">
<li><p><strong>opendrift/opendrift:latest</strong> refers to OpenDrift (latest version) with Python 3</p></li>
<li><p><strong>opendrift/opendrift:v1.0.7-</strong> refers to OpenDrift (version 1.0.7) with Python 3</p></li>
</ul>
</div></blockquote>
<p>If you want to pull a particular version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ docker pull opendrift/opendrift:1.0.7
</pre></div>
</div>
</section>
<section id="build">
<h2>Build<a class="headerlink" href="#build" title="Link to this heading"></a></h2>
<p>If needed, you can develop locally! You should first <a class="reference external" href="https://docs.docker.com/install/">install Docker</a> so that you
can build images on your host. To build the image, after cloning the repository,
from the base of the repo issue this command, where <cite>opendrift/opendrift</cite> refers
to the name of the container (on Docker Hub it coincides with a <cite>&lt;username&gt;&lt;reponame&gt;</cite>
You should select the name of the file that you want to build (e.g., docker/Dockerfile)
and then build as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ docker build -f docker/Dockerfile -t opendrift/opendrift .
</pre></div>
</div>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
<p>We will show usage examples for the base container, and you can change the name if you
desire to use a different container or version (the tag). Likely you will want to interact with the software, and you can do this via
an interactive (i) terminal (t) session:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ docker run -it opendrift/opendrift
</pre></div>
</div>
</section>
<section id="singularity">
<h2>Singularity<a class="headerlink" href="#singularity" title="Link to this heading"></a></h2>
<p>We will now walk through dumping the Docker layers (you might know Docker images are composed
of layers, like a cake!) into a Singularity container. Why would you want a Singularity container? It doesn’t have the security issues of Docker, and could be used on a shared resource.</p>
<section id="installation">
<h3>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h3>
<p>You should first <a class="reference external" href="https://singularityware.github.io/install-linux">install Singularity</a> so that you can build images on your host. If you use a Mac, you will need to install Singularity in a virtual machine like Vagrant. Singularity is going to allow us to interact exactly the same, but with an image that we can use on our shared resource. The biggest difference is that a Singularity image is a read only single file (a format called <a class="reference external" href="https://en.wikipedia.org/wiki/SquashFS">squashfs</a> so it is compressed) that we can physically move around and execute like a script.
Unlike Docker images that are assembled from layers and the whole thing is sort of mysterious to the
average user, your Singularity container is a single file that can sit on your desktop.
You can read more about Singularity <a class="reference external" href="https://singularityware.github.io">here</a>.</p>
</section>
<section id="pull-the-container">
<h3>Pull the Container<a class="headerlink" href="#pull-the-container" title="Link to this heading"></a></h3>
<p>Wherever you are working, the image layers (used to create the Singularity container) will be pulled by default
to the Singularity default cache, which is <cite>$HOME/.singularity</cite>. If there is absolutely any chance that your
<cite>$HOME</cite> has a quota (e.g., on a shared resource) then you should define the environment variable <cite>SINGULARITY_CACHEDIR</cite>
to be somewhere that you <strong>do</strong> have room. For example, it may be the folder defined at the environment variable <cite>$SCRATCH</cite> on your shared resource. You might do something like this before using Singularity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ export SINGULARITY_CACHEDIR=$SCRATCH/.singularity
</pre></div>
</div>
<p>Next, we will pull the Docker Image for OpenDrift from <a class="reference external" href="https://hub.docker.com/opendrift/opendrift/">Docker Hub</a>
directly into a Singularity container. You actually don’t need to be a superuser (root / sudo) to do this.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ singularity pull --name opendrift.sif docker://opendrift/opendrift
</pre></div>
</div>
</section>
<section id="using-the-image">
<h3>Using the image<a class="headerlink" href="#using-the-image" title="Link to this heading"></a></h3>
<p>Let’s shell inside the image to interact with the software! I’m not sure how OpenDrift
is used, but I can show you where it is. First, shell inside to explore!</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ singularity shell opendrift.sif
</pre></div>
</div>
<p>You can also just run the image to get an interactive shell, with working directory <cite>/code</cite>
where the repository was cloned. Here is an example of running directly (without build) to
pull the latest tag:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ docker run -it opendrift/opendrift

Unable to find image &#39;opendrift/opendrift:latest&#39; locally
latest: Pulling from opendrift/opendrift
cc1a78bfd46b: Already exists
bad124d5894e: Pull complete
ab2b0b173074: Pull complete
018d53043894: Pull complete
4987762b1e47: Pull complete
d58a7f3e3615: Pull complete
86f53a067a28: Pull complete
4c17ec80ca72: Pull complete
aae597ea9e38: Pull complete
Digest: sha256:33807a79ced6ca9c0960bd942e9d12381c7f1066feb75c5c6992ae5b8802f94c
Status: Downloaded newer image for opendrift/opendrift:latest
(base) root@d7ca5fe730b8:/code# python
Python 2.7.15 |Anaconda, Inc.| (default, May  1 2018, 23:32:55)
[GCC 7.2.0] on linux2
Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
&gt;&gt;&gt; import opendrift
&gt;&gt;&gt; opendrift.__version__
&#39;1.0.4&#39;
</pre></div>
</div>
<p>To execute a command to the container from the outside (on the host without shelling
inside) you can use exec:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[vsochat@sh-08-37 ~]$ singularity exec opendrift.sif python myscript.py
</pre></div>
</div>
<p>The opendrift software (this repository) can be found at <cite>/code/opendrift</cite> in the container.
Note that the creators used / more robustly tested the Singularity container on the
<a class="reference external" href="https://www.sherlock.stanford.edu/docs/">Sherlock cluster</a>.</p>
</section>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="interaction_with_coastline.html" class="btn btn-neutral float-left" title="Interaction with coastline" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="gui.html" class="btn btn-neutral float-right" title="Graphical User Interface" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020, Knut-Frode Dagestad (knutfd@met.no) and Gaute Hope (gauteh@met.no)..</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>