yetus-docker-image/index.html - yetus - Git at Google

 <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html>
     <head>
         <meta charset="utf-8">
         <title>Apache Yetus</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta name="description" content="">
         <meta name="author" content="">

         <link href="../assets/css/bootstrap.css" rel="stylesheet">
         <link href="../assets/css/bootstrap-theme.css" rel="stylesheet">
         <link href="../assets/css/font-awesome.css" rel="stylesheet">

         <!-- JS -->
         <script type="text/javascript" src="../assets/js/jquery-2.1.4.min.js"></script>
         <script type="text/javascript" src="../assets/js/bootstrap.js"></script>
   </head>
     <body>

 <div class="navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container">
         <div class="navbar-header">
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
             </button>
             <a class="img-responsive pull-left" href="/">
                 <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
             </a>
         </div>
         <div class="navbar-collapse collapse">
             <ul class="nav navbar-nav">
                 <li><a href="/downloads/">Downloads</a>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu">
                       <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
                       <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
                       <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
                       <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
                       </li>
                       <li><a href="/documentation/history/">History of the Project</a>
                       </li>
                     </ul>
                 </li>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
                         </li>
                     </ul>
                 </li>
                 <li>
                     <li class="dropdown">
                         <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
                         <ul class="dropdown-menu" role="menu">
                             <li><a href="https://www.apache.org">Apache Homepage</a>
                             </li>
                             <li><a href="https://www.apache.org/licenses/">Apache License</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                             </li>
                             <li><a href="https://www.apache.org/security/">Security</a>
                             </li>
                         </ul>
                     </li>
                 </li>
             </ul>
         </div>
         <!--/.nav-collapse -->
     </div>
 </div>

       <div class="container">
         <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <h1 id="convenience-docker-hub-images">Convenience Docker Hub Images</h1>

 <!-- MarkdownTOC levels="1,2" autolink="true" indent="  " bullets="*" bracket="round" -->

 <ul>
   <li><a href="#file-access">File Access</a></li>
   <li><a href="#a-note-about-precommit">A Note About Precommit</a></li>
 </ul>

 <!-- /MarkdownTOC -->

 <p>While not official releases, the Apache Yetus project makes available two types of images available via<br />
 the GitHub Container Registry:</p>

 <ul>
   <li>
     <p>ghcr.io/apache/yetus-base</p>

     <p>This image is the same as the 'built-in' Dockerfile when <code>--docker</code> is used without <code>--dockerfile</code>  on the precommit command line.  It includes all of the pre-requisites as needed by the various Apache Yetus components. It is located in <code>precommit/src/main/shell/test-patch-docker/</code>.</p>
   </li>
   <li>
     <p>ghcr.io/apache/yetus</p>

     <p>This image is the same as ghcr.io/aapache/yetus-base but includes a pre-built version of Apache Yetus as part of the base OS image. In other words, qbt, releasedocmaker, shelldocs, test-patch, etc., are in /usr/bin and available in the default path. It is generated from the Dockerfile located in the root of the source and is built with the options provided in the hooks directory.</p>
   </li>
 </ul>

 <p>Both images should be suitable to be used as a building block or even directly if your build environment needs no other dependencies.  These images are especially useful for various CI systems that require a Docker image to be used.</p>

 <p>Images are tagged such that 'main' represents the last successful Docker image build of the main branch.  Images based off of the official source releases are tagged with a matching version number (e.g., 0.9.0).  There is no 'latest' tagged image.  It is recommended that users choose a stable tag so as not to be surprised by incompatible changes.</p>

 <h1 id="file-access">File Access</h1>

 <p>All of the executables that Apache Yetus provides requires access to one or more directories.  These directories should be provided on the command line via the volume flags to docker run. For example, to run shelldocs against test-patch.sh:</p>

 <div class="highlight"><pre class="highlight shell"><code>docker run <span class="se">\</span>
   <span class="nt">--rm</span> <span class="se">\</span>
   <span class="nt">-v</span> /tmp/out:/output <span class="se">\</span>
   <span class="nt">-v</span> /src/precommit/src/main/shell:/input:ro <span class="se">\</span>
   ghcr.io/apache/yetus:0.14.0 <span class="se">\</span>
     shelldocs <span class="nt">--output</span> /output/test-patch.md <span class="nt">--input</span> /input/test-patch.sh
 </code></pre></div>
 <p>In this example, we mount two volumes: one for input (marked read-only), one for output.  After execution, shelldocs has processed test-patch.sh and generated a test-patch.md file in /tmp/out on our local machine.</p>

 <p>Precommit also works, assuming that Apache Yetus image has all of your project's dependencies.  For example:</p>

 <div class="highlight"><pre class="highlight shell"><code>docker run <span class="se">\</span>
   <span class="nt">--rm</span> <span class="se">\</span>
   <span class="nt">-v</span> /tmp/patchdir:/patchdir <span class="se">\</span>
   <span class="nt">-v</span> /src:/basedir <span class="se">\</span>
   ghcr.io/apache/yetus:0.14.0 <span class="se">\</span>
   qbt <span class="se">\</span>
     <span class="nt">--plugins</span><span class="o">=</span>all <span class="se">\</span>
     <span class="nt">--basedir</span><span class="o">=</span>/basedir <span class="se">\</span>
     <span class="nt">--patch-dir</span><span class="o">=</span>/patchdir <span class="se">\</span>
     <span class="nt">--project</span><span class="o">=</span>yetus
 </code></pre></div>
 <p>If your project needs additional dependencies, it is trivial to build off of the Apache Yetus image:</p>

 <div class="highlight"><pre class="highlight docker"><code><span class="k">FROM</span><span class="s"> ghcr.io/apache/yetus:0.14.0</span>
 <span class="k">RUN </span>apt-get <span class="nt">-q</span> update <span class="o">&amp;&amp;</span> apt-get <span class="nt">-q</span> <span class="nb">install</span> <span class="nt">-y</span> <span class="se">\
 </span>      clang <span class="se">\
 </span>      libssl-dev <span class="se">\
 </span>      valgrind <span class="se">\
 </span>      zlib1g-dev
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code>docker build <span class="nt">-t</span> project/build:0.9.0 <span class="nt">-f</span> <span class="nb">.</span>
 </code></pre></div>
 <p>This example builds a docker image based off of Apache Yetus 0.9.0 but with the additions of clang, some development libraries, and valgrind.  Now project/build:0.9.0 can be used instead of ghcr.io/apache/yetus:0.14.0 since it has all of Apache Yetus and the additions needed by our project.</p>

 <h1 id="a-note-about-precommit">A Note About Precommit</h1>

 <p>test-patch and friends have direct support for Docker outside of the convenience images.  That information is covered in-depth in the<a href="/documentation/in-progress/precommit/docker/">precommit-docker</a> section.</p>

     </div>

 <div class="container">
     <hr>
     <footer class="footer">
         <div class="row-fluid">
             <div class="span12 text-left">
               <div class="span12">
                 Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
               </div>
             </div>

         </div>

     </footer>
 </div>

   </body>
 </html>
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Yetus</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="description" content="">
	<meta name="author" content="">

	<link href="../assets/css/bootstrap.css" rel="stylesheet">
	<link href="../assets/css/bootstrap-theme.css" rel="stylesheet">
	<link href="../assets/css/font-awesome.css" rel="stylesheet">

	<!-- JS -->
	<script type="text/javascript" src="../assets/js/jquery-2.1.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/bootstrap.js"></script>
	</head>
	<body>

	<div class="navbar navbar-inverse navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="img-responsive pull-left" href="/">
	<img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
	</a>
	</div>
	<div class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li><a href="/downloads/">Downloads</a>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
	<li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
	<li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
	<li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
	</li>
	<li><a href="/documentation/history/">History of the Project</a>
	</li>
	</ul>
	</li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
	</li>
	</ul>
	</li>
	<li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="https://www.apache.org">Apache Homepage</a>
	</li>
	<li><a href="https://www.apache.org/licenses/">Apache License</a>
	</li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	</li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	</li>
	<li><a href="https://www.apache.org/security/">Security</a>
	</li>
	</ul>
	</li>
	</li>
	</ul>
	</div>
	<!--/.nav-collapse -->
	</div>
	</div>

	<div class="container">
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<h1 id="convenience-docker-hub-images">Convenience Docker Hub Images</h1>

	<!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" -->

	<ul>
	<li><a href="#file-access">File Access</a></li>
	<li><a href="#a-note-about-precommit">A Note About Precommit</a></li>
	</ul>

	<!-- /MarkdownTOC -->

	<p>While not official releases, the Apache Yetus project makes available two types of images available via<br />
	the GitHub Container Registry:</p>

	<ul>
	<li>
	<p>ghcr.io/apache/yetus-base</p>

	<p>This image is the same as the 'built-in' Dockerfile when <code>--docker</code> is used without <code>--dockerfile</code> on the precommit command line. It includes all of the pre-requisites as needed by the various Apache Yetus components. It is located in <code>precommit/src/main/shell/test-patch-docker/</code>.</p>
	</li>
	<li>
	<p>ghcr.io/apache/yetus</p>

	<p>This image is the same as ghcr.io/aapache/yetus-base but includes a pre-built version of Apache Yetus as part of the base OS image. In other words, qbt, releasedocmaker, shelldocs, test-patch, etc., are in /usr/bin and available in the default path. It is generated from the Dockerfile located in the root of the source and is built with the options provided in the hooks directory.</p>
	</li>
	</ul>

	<p>Both images should be suitable to be used as a building block or even directly if your build environment needs no other dependencies. These images are especially useful for various CI systems that require a Docker image to be used.</p>

	<p>Images are tagged such that 'main' represents the last successful Docker image build of the main branch. Images based off of the official source releases are tagged with a matching version number (e.g., 0.9.0). There is no 'latest' tagged image. It is recommended that users choose a stable tag so as not to be surprised by incompatible changes.</p>

	<h1 id="file-access">File Access</h1>

	<p>All of the executables that Apache Yetus provides requires access to one or more directories. These directories should be provided on the command line via the volume flags to docker run. For example, to run shelldocs against test-patch.sh:</p>

	<div class="highlight"><pre class="highlight shell"><code>docker run <span class="se">\</span>
	<span class="nt">--rm</span> <span class="se">\</span>
	<span class="nt">-v</span> /tmp/out:/output <span class="se">\</span>
	<span class="nt">-v</span> /src/precommit/src/main/shell:/input:ro <span class="se">\</span>
	ghcr.io/apache/yetus:0.14.0 <span class="se">\</span>
	shelldocs <span class="nt">--output</span> /output/test-patch.md <span class="nt">--input</span> /input/test-patch.sh
	</code></pre></div>
	<p>In this example, we mount two volumes: one for input (marked read-only), one for output. After execution, shelldocs has processed test-patch.sh and generated a test-patch.md file in /tmp/out on our local machine.</p>

	<p>Precommit also works, assuming that Apache Yetus image has all of your project's dependencies. For example:</p>

	<div class="highlight"><pre class="highlight shell"><code>docker run <span class="se">\</span>
	<span class="nt">--rm</span> <span class="se">\</span>
	<span class="nt">-v</span> /tmp/patchdir:/patchdir <span class="se">\</span>
	<span class="nt">-v</span> /src:/basedir <span class="se">\</span>
	ghcr.io/apache/yetus:0.14.0 <span class="se">\</span>
	qbt <span class="se">\</span>
	<span class="nt">--plugins</span><span class="o">=</span>all <span class="se">\</span>
	<span class="nt">--basedir</span><span class="o">=</span>/basedir <span class="se">\</span>
	<span class="nt">--patch-dir</span><span class="o">=</span>/patchdir <span class="se">\</span>
	<span class="nt">--project</span><span class="o">=</span>yetus
	</code></pre></div>
	<p>If your project needs additional dependencies, it is trivial to build off of the Apache Yetus image:</p>

	<div class="highlight"><pre class="highlight docker"><code><span class="k">FROM</span><span class="s"> ghcr.io/apache/yetus:0.14.0</span>
	<span class="k">RUN </span>apt-get <span class="nt">-q</span> update <span class="o">&&</span> apt-get <span class="nt">-q</span> <span class="nb">install</span> <span class="nt">-y</span> <span class="se">\
	</span> clang <span class="se">\
	</span> libssl-dev <span class="se">\
	</span> valgrind <span class="se">\
	</span> zlib1g-dev
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code>docker build <span class="nt">-t</span> project/build:0.9.0 <span class="nt">-f</span> <span class="nb">.</span>
	</code></pre></div>
	<p>This example builds a docker image based off of Apache Yetus 0.9.0 but with the additions of clang, some development libraries, and valgrind. Now project/build:0.9.0 can be used instead of ghcr.io/apache/yetus:0.14.0 since it has all of Apache Yetus and the additions needed by our project.</p>

	<h1 id="a-note-about-precommit">A Note About Precommit</h1>

	<p>test-patch and friends have direct support for Docker outside of the convenience images. That information is covered in-depth in the<a href="/documentation/in-progress/precommit/docker/">precommit-docker</a> section.</p>

	</div>

	<div class="container">
	<hr>
	<footer class="footer">
	<div class="row-fluid">
	<div class="span12 text-left">
	<div class="span12">
	Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
	</div>
	</div>

	</div>

	</footer>
	</div>

	</body>
	</html>