Skip to content

Commit

Permalink
Render course
Browse files Browse the repository at this point in the history
  • Loading branch information
@github-actions
github-actions[bot] committed Dec 19, 2024
1 parent e56c7e1 commit 32a6d71
Show file tree
Hide file tree
Showing 16 changed files with 1,012 additions and 43 deletions.
6 changes: 6 additions & 0 deletions docs/01-intro.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,12 @@ <h1 class="quarto-secondary-nav-title">
<a href="./References.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">12</span>&nbsp; <span class="chapter-title">References</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./About.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">About the Authors</span></a>
</div>
</li>
</ul>
</div>
Expand Down
6 changes: 6 additions & 0 deletions docs/02-why-containers.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,12 @@ <h1 class="quarto-secondary-nav-title">
<a href="./References.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">12</span>&nbsp; <span class="chapter-title">References</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./About.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">About the Authors</span></a>
</div>
</li>
</ul>
</div>
Expand Down
36 changes: 23 additions & 13 deletions docs/03-using-containers.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,12 @@ <h1 class="quarto-secondary-nav-title">
<a href="./References.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">12</span>&nbsp; <span class="chapter-title">References</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./About.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">About the Authors</span></a>
</div>
</li>
</ul>
</div>
Expand Down Expand Up @@ -227,14 +233,14 @@ <h1 class="title d-none d-lg-block">
<section id="a-note-about-window-juggling" class="level3" data-number="3.0.1"><h3 data-number="3.0.1" class="anchored" data-anchor-id="a-note-about-window-juggling">
<span class="header-section-number">3.0.1</span> A note about “window juggling”</h3>
<p>When learning another software skill like containers, it sometimes means you’ll have to keep track of more than one window. We call this “Window Juggling”. It’s an overlooked skill but something you’ll become more comfortable with.</p>
<p><strong>IMPORTANT</strong>: Use the checkboxes to follow along with each step in the activities! This is to help you keep track because steps have to be done in order!</p>
<p><strong>IMPORTANT</strong>: Use the checkboxes to follow along with each step in the activities! This is to help you keep track because the steps have to be done in order!</p>
</section><section id="activity-instructions" class="level2 panelset" data-number="3.1"><h2 class="panelset anchored" data-number="3.1" data-anchor-id="activity-instructions">
<span class="header-section-number">3.1</span> Activity Instructions</h2>
<section id="docker" class="level3" data-number="3.1.1"><h3 data-number="3.1.1" class="anchored" data-anchor-id="docker">
<span class="header-section-number">3.1.1</span> Docker</h3>
<section id="set-up" class="level4" data-number="3.1.1.1"><h4 data-number="3.1.1.1" class="anchored" data-anchor-id="set-up">
<span class="header-section-number">3.1.1.1</span> Set up</h4>
<p><input type="checkbox"> Go here to <a href="https://www.docker.com/get-started">install Docker</a>, following the instructions for your particular operating system.<br><input type="checkbox"> If you don’t have a Docker account create an account when prompted, or <a href="https://hub.docker.com/">go here</a>.<br><input type="checkbox"> After you install Docker, start up Docker desktop by double clicking on the app. It may take some time to start up.<br></p>
<p><input type="checkbox"> If not already installed, go here to <a href="https://www.docker.com/get-started">install Docker</a>, following the instructions for your particular operating system.<br><input type="checkbox"> If you don’t have a Docker account create an account when prompted, or <a href="https://hub.docker.com/">go here</a>.<br><input type="checkbox"> Start up Docker desktop by double clicking on the app. It may take some time to start up.<br></p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -257,7 +263,7 @@ <h1 class="title d-none d-lg-block">
<p><em>ADD: Kate to add a brief description of the files that are here</em></p>
</section><section id="activity-1-pull-and-run-a-docker-image" class="level4" data-number="3.1.1.3"><h4 data-number="3.1.1.3" class="anchored" data-anchor-id="activity-1-pull-and-run-a-docker-image">
<span class="header-section-number">3.1.1.3</span> Activity 1: Pull and run a Docker image</h4>
<p><strong>This activity is built so that you will encounter errors that this guide will work you through!</strong> Most common container stumbling block is understanding the idea that containers are isolated from your computer</p>
<p><strong>This activity is built so that you will encounter errors that this guide will work you through!</strong> One of the most common container stumbling blocks is understanding the idea that containers are isolated from your computer.</p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -275,10 +281,10 @@ <h1 class="title d-none d-lg-block">
</div>
</div>
</div>
<p>We will encounter both an error of when we don’t have a file we need AND an error of when we don’t have a software package we need. We will guide you through what to do when these expected errors occur.</p>
<p>We will encounter both an error when we don’t have a file we need AND an error when we don’t have a software package we need. We will guide you through what to do when these expected errors occur.</p>
</section><section id="step-1-docker-pull" class="level4" data-number="3.1.1.4"><h4 data-number="3.1.1.4" class="anchored" data-anchor-id="step-1-docker-pull">
<span class="header-section-number">3.1.1.4</span> Step 1: Docker pull</h4>
<p>We need to get the Docker <strong>image</strong> we want to use. We do this by “pulling” it. Pulling is a term used in GitHub terminology too. It just means we’re taking something from the internet and getting a copy locally (on our computer).</p>
<p>We need to get the Docker <strong>image</strong> we want to use. We do this by “pulling” it. Pulling is a term used in GitHub terminology too. It just means we’re taking something from the internet and getting a copy locally (on our computer). Pulling is basically like downloading.</p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -299,7 +305,7 @@ <h1 class="title d-none d-lg-block">
</div>
<section id="step-2-check-what-images-you-have" class="level5" data-number="3.1.1.4.1"><h5 data-number="3.1.1.4.1" class="anchored" data-anchor-id="step-2-check-what-images-you-have">
<span class="header-section-number">3.1.1.4.1</span> Step 2: Check what images you have</h5>
<p><input type="checkbox"> To see what images we have we can run <code>docker image ls</code>.<br><input type="checkbox"> We should see <code>cansav09/practice-image:1</code> show up in the output.<br></p>
<p><input type="checkbox"> To see what images we have we can run <code>docker image ls</code>.<br><input type="checkbox"> Alternatively, you can visit the Images tab of the docker desktop app.<br><input type="checkbox"> We should see <code>cansav09/practice-image:1</code> show up in the output.<br></p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -308,9 +314,9 @@ <h1 class="title d-none d-lg-block">
</div>
</div>
</div>
</section><section id="step-3-run-the-docker-image-to-start-a-container" class="level5" data-number="3.1.1.4.2"><h5 data-number="3.1.1.4.2" class="anchored" data-anchor-id="step-3-run-the-docker-image-to-start-a-container">
<span class="header-section-number">3.1.1.4.2</span> Step 3: Run the docker image to start a container!</h5>
<p>Remember images can be shared easily but to actually use the stuff we need to turn our image into a container! To do that we will do <code>docker run</code></p>
</section><section id="step-3-use-the-run-command-to-start-a-container-from-the-image" class="level5" data-number="3.1.1.4.2"><h5 data-number="3.1.1.4.2" class="anchored" data-anchor-id="step-3-use-the-run-command-to-start-a-container-from-the-image">
<span class="header-section-number">3.1.1.4.2</span> Step 3: Use the Run command to start a container from the image!</h5>
<p>Remember images can be shared easily but to actually use the stuff we need to turn our image into a container! To do that we will use the <code>docker run</code> command</p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -321,8 +327,10 @@ <h1 class="title d-none d-lg-block">
</div>
<p><input type="checkbox"> To launch the image for use, we can use <code>docker run</code> to turn it into a <strong>container</strong>.</p>
<pre><code>docker run cansav09/practice-image:1</code></pre>
<p><input type="checkbox"> To see what containers we have running we have we can run:</p>
<p><input type="checkbox"> Alternatively, we can press the play button for the image in images tab of the desktop app.</p>
<p><input type="checkbox"> To see what containers we have running we have we can run (in a new terminal session):</p>
<pre><code>docker ps</code></pre>
<p><input type="checkbox"> Alternatively, you can visit the Containers tab of the Docker Desktop app.</p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand Down Expand Up @@ -361,7 +369,8 @@ <h1 class="title d-none d-lg-block">
</div>
</div>
</div>
<p>If you run this you should see your terminal/command prompt now have the initial part change to something like:</p>
<p>You can find the <code>CONTAINER ID</code> in the containers tab of the desktop app or by using the <code>docker container ls</code> command in the terminal. Note that whereas the <code>docker run</code> command creates a new container from a docker image, the <code>docker exec</code> command executes a command inside an already running container. The <code>-it</code> option tells docker to execute the command interactively. In this case the actual command being specified is <code>bash</code>. Altogether the result is an interactive Bash shell inside the already running container.</p>
<p>If you run the above command you should see your terminal/command prompt now have the initial part change to something like:</p>
<pre><code>root@e7b19cfb4461:/</code></pre>
<p>Where you’ll noticed the <code>CONTAINER ID</code> is now shown there.</p>
<p>You are now using command line inside of your container. Trying running any bash command like <code>ls</code> to see what files are here for example.</p>
Expand All @@ -376,8 +385,9 @@ <h1 class="title d-none d-lg-block">
<p><input type="checkbox"> When you are ready to leave your container type <code>exit</code> and press Enter.</p>
</section><section id="step-5-try-calling-a-script" class="level5" data-number="3.1.1.4.4"><h5 data-number="3.1.1.4.4" class="anchored" data-anchor-id="step-5-try-calling-a-script">
<span class="header-section-number">3.1.1.4.4</span> Step 5: Try calling a script</h5>
<p><input type="checkbox"> To run a script using the docker container we could just add reference to a script at the end:</p>
<pre><code>docker exec -it &lt;PUT_CONTAINER_ID_HERE&gt; bash run_analysis.sh</code></pre>
<p><input type="checkbox"> Make sure you are in the unzipped workshop directory. <input type="checkbox"> To run a script using the docker container we could just add reference to a script at the end.</p>
<pre><code>cd containers-for-scientists-sandbox-main
docker exec -it &lt;PUT_CONTAINER_ID_HERE&gt; bash run_analysis.sh</code></pre>
<div class="cell">
<div class="cell-output-display">
<div>
Expand Down
22 changes: 14 additions & 8 deletions docs/04-using-volumes.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,12 @@ <h1 class="quarto-secondary-nav-title">
<a href="./References.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">12</span>&nbsp; <span class="chapter-title">References</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./About.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">About the Authors</span></a>
</div>
</li>
</ul>
</div>
Expand Down Expand Up @@ -226,17 +232,17 @@ <h1 class="title d-none d-lg-block">
<p>So how do we get files we need onto a container we are using?</p>
<p>There are a few options:</p>
<ul>
<li>We could run our container and within that we could download the files we need from online! For example we could <code>git clone</code> files from a repository or otherwise <code>wget</code> or <code>curl</code> files that are stored.<br>
<li>We could run our container and within that we could download the files we need from online! For example we could <code>git clone</code> files from a repository or otherwise <code>wget</code> or <code>curl</code> files that are stored online somewhere.<br>
</li>
<li>We could <code>COPY</code> a file on to the docker image when we are building it (more on this next chapter). But this strategy we want to be careful with for two reasons:
<li>We could <code>COPY</code> a file on to the docker image when we are building it (more on this next chapter). But we want to be careful with this strategy for two reasons:
<ul>
<li>We don’t want our image to be too big. so this strategy can be fine if the file is small and something we know will always be needed for any use of the container.<br>
<li>We don’t want our image to be too big. So, this strategy can be fine if the file is small and something we know will always be needed for any use of the container.<br>
</li>
<li>We DEFINITELY need to avoid ever having protected data on images that are shared. NEVER put protected data on images that we are sharing – more on this later too.<br>
</li>
</ul>
</li>
<li>Lastly we can add a <code>volume</code> of files that are local to our computer. We’ll dive into this strategy in this chapter. This will probably be a common way you’ll use to get access to files on your container.</li>
<li>Lastly we can add a <code>volume</code> of files that are local to our computer. We’ll dive into this strategy in this chapter. This will probably be the most common way you’ll use to get access to files on your container.</li>
</ul>
<p>What is a volume? A volume is a folder, likely from your computer, that can be accessed by your container.</p>
<div class="cell">
Expand All @@ -258,11 +264,11 @@ <h1 class="title d-none d-lg-block">
<span class="header-section-number">4.1</span> Activity Instructions</h2>
<section id="docker" class="level3" data-number="4.1.1"><h3 data-number="4.1.1" class="anchored" data-anchor-id="docker">
<span class="header-section-number">4.1.1</span> Docker</h3>
<p>Our container is separate from our computer so if we want to use a file we have to attach it using a “volume”.</p>
<p>Our container is separate from our computer so if we want to use a file from our computer we have to attach it using a “volume”.</p>
<section id="step-1-lets-add-our-containers-for-scientists-sandbox-files" class="level5" data-number="4.1.1.0.1"><h5 data-number="4.1.1.0.1" class="anchored" data-anchor-id="step-1-lets-add-our-containers-for-scientists-sandbox-files">
<span class="header-section-number">4.1.1.0.1</span> Step 1: Let’s add our containers-for-scientists-sandbox files</h5>
<p>Let’s point a volume to our workshop files so we have them on our container.</p>
<p>We can specify a particular file path on our computer or give it <code>$PWD</code> Then optionally we can give a <code>:</code> and a file path we’d like this to be stored on on the container. Otherwise it will be stored at the absolute top of the container.</p>
<p>We can specify a particular file path on our computer or give it <code>$PWD</code>. Then optionally we can give a <code>:</code> and a file path where we’d like it to be stored on the container. Otherwise it will be stored at the absolute top of the container. Note that <code>$PWD</code> is a special environment variable that stores the absolute path of the current working directory. You will need to be in the <code>containers-for-scientists-sandbox-main</code> for this to work.</p>
<div class="cell">
<div class="cell-output-display">
<div>
Expand All @@ -272,7 +278,7 @@ <h1 class="title d-none d-lg-block">
</div>
</div>
<p><input type="checkbox"> Now we can run:</p>
<pre><code>docker run -v $pwd:/home cansav09/practice-image:1</code></pre>
<pre><code>docker run -v $PWD:/home cansav09/practice-image:1</code></pre>
<p>If you have a windows machine you may have to run this variant instead. This version has a different <code>${}</code> around the <code>pwd</code> part.</p>
<pre><code>docker run -v ${pwd}:/home cansav09/practice-image:1</code></pre>
<p>In Docker desktop you can specify a portal like this:</p>
Expand All @@ -286,7 +292,7 @@ <h1 class="title d-none d-lg-block">
</div>
</section><section id="step-2-retry-calling-the-script" class="level4" data-number="4.1.1.1"><h4 data-number="4.1.1.1" class="anchored" data-anchor-id="step-2-retry-calling-the-script">
<span class="header-section-number">4.1.1.1</span> Step 2: Retry calling the script</h4>
<p><input type="checkbox"> Now we can run the following command but we will have to run <code>docker ps</code> and get the container ID we need to put here.</p>
<p><input type="checkbox"> Now we can run the following command but we will have to run <code>docker ps</code> or <code>docker container ls</code> and get the container ID we need to put here.</p>
<pre><code>docker exec -it &lt;REPLACE_WITH_CONTAINER_ID&gt; bash /home/run_analysis.sh</code></pre>
<div class="cell">
<div class="cell-output-display">
Expand Down
Loading

0 comments on commit 32a6d71

Please sign in to comment.