Merge pull request #85 from hsf-training/feature/81-podman-commands

Podman commands in chapters 2 to 6

_episodes/02-pulling-images.md

@@ -10,8 +10,8 @@ objectives:
 - "List local images"
 - "Introduce image tags"
 keypoints:
-- "Pull images with `docker pull <image-id>`"
-- "List all images on the computer and other information with `docker images`"
+- "Pull images with `podman pull <image-id>`"
+- "List all images on the computer and other information with `podman images`"
 - "Image tags distinguish releases or version and are appended to the image name with a colon"
 ---
 <iframe width="427" height="251" src="https://www.youtube.com/embed/JihkukeoNVs?list=PLKZ9c4ONm-VnqD5oN2_8tXO0Yb1H_s0sj" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
@@ -22,35 +22,51 @@ Much like how GitHub allows for web hosting and searching for code, the [Docker
 image registry allows the same for Docker images.
 Hosting images is [free for public repositories][docker-hub-billing] and
 allows for downloading images as they are needed.
-Additionally, you can configure your GitLab or GitHub CI pipelines to automatically build and push docker images to Docker Hub.
+
+Additionally, through integrations with GitHub and Bitbucket, Docker Hub repositories can
+be linked against Git repositories so that
+[automated builds of Dockerfiles on Docker Hub][docker-hub-builds] will be triggered by
+pushes to repositories. However, at this moment enabling such a feature requires a Pro (paid) account
+or joining the [Docker-Sponsored Open Source Program](https://www.docker.com/community/open-source/application/).
+There are other ways of doing this, such as using GitLab/GitHub CI/CD, but that's beyond the scope of this training module.
+
+> ## Docker Hub and Podman
+>
+> Both Docker and Podman use OCI (Open Container Initiative) compliant images, so you can use the same images with both tools.
+> It means Podman can pull and run images from Docker Hub.
+>
+> By default, `podman pull` pulls an image from Docker Hub if a registry is not specified in the command line argument.
+{: .callout}
 
 # Pulling Images
 
-To begin with we're going to [pull][docker-docs-pull] down the Docker image we're going
-to be working in for the tutorial (note: if you did all the docker pulls in the setup instructions, this image will already be on your machine, in which case docker should notice it's there and not attempt to re-pull it unless it's changed in the meantime):
+To begin with we're going to [pull][podman-docs-pull] down the image we're going
+to be working in for the tutorial (note: if you did all the docker pulls in the setup instructions, this image will already be on your machine, in which case podman should notice it's there and not attempt to re-pull it unless it's changed in the meantime):
 
 ~~~bash
-docker pull matthewfeickert/intro-to-docker
+podman pull matthewfeickert/intro-to-docker
 ~~~
 {: .source}
 
-> ## Permission errors
-> If you run into a permission error, use `sudo docker run ...` as a quick fix.
-> To fix this for the future (**recommended**), see [the docker docs](https://docs.docker.com/install/linux/linux-postinstall/).
+> ## Connection errors
+> If using Podman or Docker in a non-Linux machine you run into an error like `Error: unable to connect to Podman`,
+> make sure that the Podman or Docker desktop application is running.
+>
+> Remember that in such environments, Podman or Docker use a virtual machine to run the containers.
 {: .callout}
 
-and then [list the images][docker-docs-images] that we have available to us locally
+and then [list the images][podman-docs-images] that we have available to us locally
 
 ~~~bash
-docker images
+podman images
 ~~~
 {: .source}
 
 If you have many images and want to get information on a particular one you can apply a
 filter, such as the repository name
 
 ~~~bash
-docker images matthewfeickert/intro-to-docker
+podman images matthewfeickert/intro-to-docker
 ~~~
 {: .source}
 
@@ -63,7 +79,7 @@ matthewfeickert/intro-to-docker   latest              cf6508749ee0        3 mont
 or more explicitly
 
 ~~~bash
-docker images --filter=reference="matthewfeickert/intro-to-docker"
+podman images --filter=reference="matthewfeickert/intro-to-docker"
 ~~~
 {: .source}
 
@@ -77,11 +93,11 @@ You can see here that there is the `TAG` field associated with the
 `matthewfeickert/intro-to-docker` image.
 Tags are a way of further specifying different versions of the same image.
 As an example, let's pull the buster release tag of the
-[Debian image](https://hub.docker.com/_/debian) (again, if it was already pulled during setup, docker won't attempt to re-pull it unless it's changed since last pulled).
+[Debian image](https://hub.docker.com/_/debian) (again, if it was already pulled during setup, podman won't attempt to re-pull it unless it's changed since last pulled).
 
 ~~~bash
-docker pull debian:buster
-docker images debian
+podman pull debian:buster
+podman images debian
 ~~~
 {: .source}
 
@@ -97,32 +113,39 @@ debian              buster              00bf7fdd8baf        5 weeks ago
 ~~~
 {: .output}
 
+Check the documentation on [pull][podman-docs-pull] and [images][podman-docs-images] for more information on these commands.
+
 > ## Pulling Python
 >
-> Pull the image python3.7-slim for Python 3.7 and then list all `python` images along with
-> the `matthewfeickert/intro-to-docker` image
+> Pull the image python:3.9-slim for Python 3.9 and then list all `python` images on your computer.
+>
+> Browse [the official Python images][docker-hub-python] to find available tags and
+> read about image variants. What does `-slim` mean?
 >
 > > ## Solution
 > >
 > > ~~~bash
-> > docker pull python:3.7-slim
-> > docker images --filter=reference="matthewfeickert/intro-to-docker" --filter=reference="python"
+> > podman pull python:3.9-slim
+> > podman images --filter=reference="python"
 > > ~~~
 > > {: .source}
 > >
 > > ~~~
 > > REPOSITORY                        TAG                 IMAGE ID            CREATED             SIZE
-> > python                            3.7                 e440e2151380        23 hours ago        918MB
-> > matthewfeickert/intro-to-docker   latest              cf6508749ee0        3 months ago        1.49GB
+> > docker.io/library/python          3.9-slim            e440e2151380        2 weeks ago        131 MB
 > > ~~~
+> >
+> >* `python:<version>-slim`: This image does not contain the common packages contained in the default
+> >tag and only contains the minimal packages needed to run python
 > > {: .output}
 > {: .solution}
 {: .challenge}
 
 [docker-hub]: https://hub.docker.com/
 [docker-hub-billing]: https://www.docker.com/pricing/
+[docker-hub-python]: https://hub.docker.com/_/python
 [docker-hub-builds]: https://docs.docker.com/docker-hub/builds/
-[docker-docs-pull]: https://docs.docker.com/engine/reference/commandline/pull/
-[docker-docs-images]: https://docs.docker.com/engine/reference/commandline/images/
+[podman-docs-pull]: https://docs.podman.io/en/latest/markdown/podman-pull.1.html
+[podman-docs-images]: https://docs.podman.io/en/stable/markdown/podman-images.1.html
 
 {% include links.md %}

_episodes/03-running-containers.md

@@ -12,21 +12,21 @@ objectives:
 - "Understand container state"
 - "Stop and restart containers"
 keypoints:
-- "Run containers with `docker run <image-id>`"
-- "Monitor containers with `docker ps`"
+- "Run containers with `podman run <image-id>`"
+- "Monitor containers with `podman ps`"
 - "Exit interactive sessions using the `exit` command"
-- "Restart stopped containers with `docker start`"
+- "Restart stopped containers with `podman start`"
 ---
 <iframe width="427" height="251" src="https://www.youtube.com/embed/UejGBfppmZY?list=PLKZ9c4ONm-VnqD5oN2_8tXO0Yb1H_s0sj" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-To use a Docker image as a particular instance on a host machine you [run][docker-docs-run]
+To use an image as a particular instance on a host machine, you [run][podman-docs-run]
 it as a container.
-You can run in either a [detached or foreground][docker-docs-run-detached] (interactive) mode.
+You can run in either a detached or foreground (interactive) mode.
 
 Run the image we pulled as a container with an interactive bash terminal:
 
 ~~~bash
-docker run -it matthewfeickert/intro-to-docker:latest /bin/bash
+podman run -it matthewfeickert/intro-to-docker:latest /bin/bash
 ~~~
 {: .source}
 
@@ -77,13 +77,23 @@ BUG_REPORT_URL="https://bugs.debian.org/"
 ~~~
 {: .output}
 
+> ## Working directory
+>
+>You may be wondering why you are at `/home/docker/data` inside the container.
+>This is the working directory that was set for the image.
+>
+> In the next chapters we will see how to build your own images
+> and set parameters such as the working directory.
+>{: .source}
+{: .callout}
+
 ## Monitoring Containers
 
 Open up a new terminal tab on the host machine and
-[list the containers that are currently running][docker-docs-ps]
+[list the containers that are currently running][podman-docs-ps]:
 
 ~~~bash
-docker ps
+podman ps
 ~~~
 {: .source}
 
@@ -94,17 +104,17 @@ CONTAINER ID        IMAGE         COMMAND             CREATED             STATUS
 {: .output}
 
 Notice that the name of your container is some randomly generated name.
-To make the name more helpful, [rename][docker-docs-rename] the running container
+To make the name more helpful, [rename][podman-docs-rename] the running container
 
 ~~~bash
-docker rename <CONTAINER ID> my-example
+podman rename <CONTAINER ID> my-example
 ~~~
 {: .source}
 
 and then verify it has been renamed
 
 ~~~bash
-docker ps
+podman ps
 ~~~
 {: .source}
 
@@ -119,15 +129,15 @@ CONTAINER ID        IMAGE         COMMAND             CREATED             STATUS
 >You can also identify containers to rename by their current name
 >
 >~~~bash
->docker rename <NAME> my-example
+>podman rename <NAME> my-example
 >~~~
 >{: .source}
 {: .callout}
 
 Alternatively, you can also give the container a name at creation, using the `--name ` option:
 
 ~~~bash
-docker run -it --name my-fancy-name matthewfeickert/intro-to-docker:latest /bin/bash
+podman run -it --name my-fancy-name matthewfeickert/intro-to-docker:latest /bin/bash
 ~~~
 {: .source}
 
@@ -154,7 +164,7 @@ You are returned to your shell.
 If you list the containers you will notice that none are running
 
 ~~~bash
-docker ps
+podman ps
 ~~~
 {: .source}
 
@@ -166,7 +176,7 @@ CONTAINER ID        IMAGE               COMMAND             CREATED
 but you can see all containers that have been run and not removed with
 
 ~~~bash
-docker ps -a
+podman ps -a
 ~~~
 {: .source}
 
@@ -176,24 +186,24 @@ CONTAINER ID        IMAGE         COMMAND             CREATED            STATUS
 ~~~
 {: .output}
 
-To restart your exited Docker container [start][docker-docs-start] it again and then
-[attach][docker-docs-attach] it interactively to your shell
+To restart your exited container [start][podman-docs-start] it again and then
+[attach][podman-docs-attach] it interactively to your shell
 
 ~~~bash
-docker start <CONTAINER ID>
-docker attach <CONTAINER ID>
+podman start <CONTAINER ID>
+podman attach <CONTAINER ID>
 ~~~
 {: .source}
 
 > ## `exec` command
-> The [attach][docker-docs-attach] command used here is a handy shortcut to interactively access a running container with the same start command (in this case `/bin/bash`) that it was originally run with.
+> The [attach][podman-docs-attach] command used here is a handy shortcut to interactively access a running container with the same start command (in this case `/bin/bash`) that it was originally run with.
 >
-> In case you'd like some more flexibility, the [exec][docker-docs-exec] command lets you run any command in the container, with options similar to the run command to enable an interactive (`-i`) session, etc.
+> In case you'd like some more flexibility, the [exec][podman-docs-exec] command lets you run any command in the container, with options similar to the run command to enable an interactive (`-i`) session, etc.
 >
 > For example, the `exec` equivalent to `attach`ing in our case would look like:
 > ~~~bash
-> docker start <CONTAINER ID>
-> docker exec -it <CONTAINER ID> /bin/bash
+> podman start <CONTAINER ID>
+> podman exec -it <CONTAINER ID> /bin/bash
 > ~~~
 {: .callout}
 
@@ -202,8 +212,8 @@ docker attach <CONTAINER ID>
 >You can also start and attach containers by their name
 >
 >~~~bash
->docker start <NAME>
->docker attach <NAME>
+>podman start <NAME>
+>podman attach <NAME>
 >~~~
 >{: .source}
 {: .callout}
@@ -222,28 +232,27 @@ test.txt
 ~~~
 {: .output}
 
-So this shows us that we can exit Docker containers for arbitrary lengths of time and then
+So this shows us that we can exit containers for arbitrary lengths of time and then
 return to our working environment inside of them as desired.
 
 >## Clean up a container
 >
->If you want a container to be [cleaned up][docker-docs-run-clean-up] &mdash; that is
+>If you want a container to be [cleaned up][podman-docs-run-clean-up] &mdash; that is,
 >deleted &mdash; after you exit it then run with the `--rm` option flag
 >
 >~~~bash
->docker run --rm -it <IMAGE> /bin/bash
+>podman run --rm -it <IMAGE> /bin/bash
 >~~~
 >{: .source}
 {: .callout}
 
-[docker-docs-run]: https://docs.docker.com/engine/reference/run/
-[docker-docs-run-detached]: https://docs.docker.com/engine/reference/run/#detached-vs-foreground
-[docker-docs-run-clean-up]: https://docs.docker.com/engine/reference/run/#clean-up---rm
+[podman-docs-run]: https://docs.podman.io/en/stable/markdown/podman-run.1.html
 [docker-hub-python]: https://github.com/docker-library/python
-[docker-docs-ps]: https://docs.docker.com/engine/reference/commandline/ps/
-[docker-docs-rename]: https://docs.docker.com/engine/reference/commandline/rename/
-[docker-docs-start]: https://docs.docker.com/engine/reference/commandline/start/
-[docker-docs-attach]: https://docs.docker.com/engine/reference/commandline/attach/
-[docker-docs-exec]: https://docs.docker.com/engine/reference/commandline/exec/
+[podman-docs-ps]: https://docs.podman.io/en/stable/markdown/podman-ps.1.html
+[podman-docs-rename]: https://docs.docker.com/engine/reference/commandline/rename/
+[podman-docs-start]: https://docs.docker.com/engine/reference/commandline/start/
+[podman-docs-attach]: https://docs.docker.com/engine/reference/commandline/attach/
+[podman-docs-exec]: https://docs.docker.com/engine/reference/commandline/exec/
+[podman-docs-run-clean-up]: https://docs.podman.io/en/stable/markdown/podman-run.1.html#rm
 
 {% include links.md %}