Podman tutorial

How to build, install, and use podman on Fedora.  The ubuntu instructions
are currently commented out due to issue #166.

Signed-off-by: baude <bbaude@redhat.com>

Closes: #170
Approved by: baude

2 files changed, 167 insertions, 11 deletions

diff --git a/README.md b/README.md
index b42bd4fe1..5b445033b 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ libpod is currently in active development.
 | Command                                                  | Description                                                               | Demo|
 | :------------------------------------------------------- | :------------------------------------------------------------------------ | :----|
 | [podman(1)](/docs/podman.1.md)                           | Simple management tool for pods and images                                ||
-| [podman-attach(1)](/docs/podman-attach.1.md)             | Attach to a running container                                             ||
+| [podman-attach(1)](/docs/podman-attach.1.md)             | Attach to a running container                                             |[![...](/docs/play.png)](https://asciinema.org/a/XDlocUrHVETFECg4zlO9nBbLf)|
 | [podman-build(1)](/docs/podman-build.1.md)               | Build an image using instructions from Dockerfiles                                             ||
 | [podman-commit(1)](/docs/podman-commit.1.md)             | Create new image based on the changed container                           ||
 | [podman-cp(1)](/docs/podman-cp.1.md)                     | Instead of providing a `podman cp` command, the man page `podman-cp` describes how to use the `podman mount` command to have even more flexibility and functionality||
@@ -45,14 +45,14 @@ libpod is currently in active development.
 | [podman-history(1)](/docs/podman-history.1.md)           | Shows the history of an image                                             |[![...](/docs/play.png)](https://asciinema.org/a/bCvUQJ6DkxInMELZdc5DinNSx)|
 | [podman-images(1)](/docs/podman-images.1.md)             | List images in local storage                                              |[![...](/docs/play.png)](https://asciinema.org/a/133649)|
 | [podman-import(1)](/docs/podman-import.1.md)             | Import a tarball and save it as a filesystem image                        ||
-| [podman-info(1)](/docs/podman-info.1.md)                 | Display system information                                                ||
+| [podman-info(1)](/docs/podman-info.1.md)                 | Display system information                                                |[![...](/docs/play.png)](https://asciinema.org/a/yKbi5fQ89y5TJ8e1RfJd4ivTD)|
 | [podman-inspect(1)](/docs/podman-inspect.1.md)           | Display the configuration of a container or image                         |[![...](/docs/play.png)](https://asciinema.org/a/133418)|
 | [podman-kill(1)](/docs/podman-kill.1.md)                 | Kill the main process in one or more running containers                   |[![...](/docs/play.png)](https://asciinema.org/a/3jNos0A5yzO4hChu7ddKkUPw7)|
 | [podman-load(1)](/docs/podman-load.1.md)                 | Load an image from docker archive or oci                                  |[![...](/docs/play.png)](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)|
 | [podman-login(1)](/docs/podman-login.1.md)               | Login to a container registry						   |[![...](/docs/play.png)](https://asciinema.org/a/oNiPgmfo1FjV2YdesiLpvihtV)|
 | [podman-logout(1)](/docs/podman-logout.1.md)             | Logout of a container registry                                            |[![...](/docs/play.png)](https://asciinema.org/a/oNiPgmfo1FjV2YdesiLpvihtV)|
-| [podman-logs(1)](/docs/podman-logs.1.md)                 | Display the logs of a container                                           ||
-| [podman-mount(1)](/docs/podman-mount.1.md)               | Mount a working container's root filesystem                               ||
+| [podman-logs(1)](/docs/podman-logs.1.md)                 | Display the logs of a container                                           |[![...](/docs/play.png)](https://asciinema.org/a/MZPTWD5CVs3dMREkBxQBY9C5z)|
+| [podman-mount(1)](/docs/podman-mount.1.md)               | Mount a working container's root filesystem                               |[![...](/docs/play.png)](https://asciinema.org/a/YSP6hNvZo0RGeMHDA97PhPAf3)|
 | [podman-pause(1)](/docs/podman-pause.1.md)               | Pause one or more running containers                                      |[![...](/docs/play.png)](https://asciinema.org/a/141292)|
 | [podman-ps(1)](/docs/podman-ps.1.md)                     | Prints out information about containers                                   |[![...](/docs/play.png)](https://asciinema.org/a/bbT41kac6CwZ5giESmZLIaTLR)|
 | [podman-pull(1)](/docs/podman-pull.1.md)                 | Pull an image from a registry                                             |[![...](/docs/play.png)](https://asciinema.org/a/lr4zfoynHJOUNu1KaXa1dwG2X)|
@@ -61,14 +61,14 @@ libpod is currently in active development.
 | [podman-rmi(1)](/docs/podman-rmi.1.md)                   | Removes one or more images                                                |[![...](/docs/play.png)](https://asciinema.org/a/133799)|
 | [podman-save(1)](/docs/podman-save.1.md)                 | Saves an image to an archive                                              |[![...](/docs/play.png)](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)|
 | [podman-start(1)](/docs/podman-start.1.md)               | Starts one or more containers
-| [podman-stats(1)](/docs/podman-stats.1.md)               | Display a live stream of one or more containers' resource usage statistics||
-| [podman-stop(1)](/docs/podman-stop.1.md)                 | Stops one or more running containers                                      ||
+| [podman-stats(1)](/docs/podman-stats.1.md)               | Display a live stream of one or more containers' resource usage statistics|[![...](/docs/play.png)](https://asciinema.org/a/vfUPbAA5tsNWhsfB9p25T6xdr)|
+| [podman-stop(1)](/docs/podman-stop.1.md)                 | Stops one or more running containers                                      |[![...](/docs/play.png)](https://asciinema.org/a/KNRF9xVXeaeNTNjBQVogvZBcp)|
 | [podman-tag(1)](/docs/podman-tag.1.md)                   | Add an additional name to a local image                                   |[![...](/docs/play.png)](https://asciinema.org/a/133803)|
-| [podman-top(1)](/docs/podman-top.1.md)                   | Display the running processes of a container
-| [podman-umount(1)](/docs/podman-umount.1.md)             | Unmount a working container's root filesystem                             ||
+| [podman-top(1)](/docs/podman-top.1.md)                   | Display the running processes of a container              |[![...](/docs/play.png)](https://asciinema.org/a/5WCCi1LXwSuRbvaO9cBUYf3fk)|
+| [podman-umount(1)](/docs/podman-umount.1.md)             | Unmount a working container's root filesystem                             |[![...](/docs/play.png)](https://asciinema.org/a/MZPTWD5CVs3dMREkBxQBY9C5z)|
 | [podman-unpause(1)](/docs/podman-unpause.1.md)           | Unpause one or more running containers                                    |[![...](/docs/play.png)](https://asciinema.org/a/141292)|
 | [podman-version(1)](/docs/podman-version.1.md)           | Display the version information                                           |[![...](/docs/play.png)](https://asciinema.org/a/mfrn61pjZT9Fc8L4NbfdSqfgu)|
-| [podman-wait(1)](/docs/podman-wait.1.md)                 | Wait on one or more containers to stop and print their exit codes||
+| [podman-wait(1)](/docs/podman-wait.1.md)                 | Wait on one or more containers to stop and print their exit codes  |[![...](/docs/play.png)](https://asciinema.org/a/QNPGKdjWuPgI96GcfkycQtah0)|
 
 ## OCI Hooks Support
 
@@ -84,8 +84,8 @@ For async communication and long running discussions please use issues and pull
 
 For sync communication we have an IRC channel #PODMAN, on chat.freenode.net, that everyone is welcome to join and chat about development.
 
-## [Installation Instructions](install.md)
-
+## [Podman tutorial](podman_tutorial.md)
+For more information on how to build, install, and use podman, check out the [podman tutorial](podman_tutorial.md).
 
 ### Current Roadmap
 
diff --git a/podman_tutorial.md b/podman_tutorial.md
new file mode 100644
index 000000000..619e83c35
--- /dev/null
+++ b/podman_tutorial.md
@@ -0,0 +1,156 @@
+![PODMAN logo](https://cdn.rawgit.com/kubernetes-incubator/cri-o/master/logo/crio-logo.svg)
+
+# Basic Setup and Use of Podman
+Podman is a utility provided as part of the libpod library.  It can be used to create and maintain
+containers. The following tutorial will teach you how to set up Podman and perform some basic
+commands with Podman.
+
+## Install Podman on Fedora
+Many of the basic components to run Podman are readily available from the Fedora RPM repositories; the only
+exception is Podman itself.  In this section, we will help you install all the runtime and build dependencies
+for Podman until an RPM becomes available.
+
+### Installing build and runtime dependencies
+```
+# sudo dnf install -y git runc libassuan-devel golang golang-github-cpuguy83-go-md2man glibc-static \
+                                    gpgme-devel glib2-devel device-mapper-devel libseccomp-devel \
+                                    atomic-registries iptables skopeo-containers containernetworking-cni
+```
+### Building and installing podman
+```
+# git clone https://github.com/projectatomic/libpod/ ~/src/github.com/projectatomic/libpod
+# cd !$
+# make
+# sudo make install PREFIX=/usr
+```
+
+<!-- (
+## Install podman on Ubuntu
+
+The default Ubuntu cloud image size will not allow for the following exercise to be done without increasing its
+capacity.  Be sure to add at least 5GB to the image. Instructions to do this are outside the scope of this
+tutorial.
+
+```
+# sudo apt-get update
+# sudo apt-get install libdevmapper-dev libglib2.0-dev libgpgme11-dev golang libseccomp-dev \
+                        go-md2man libprotobuf-dev libprotobuf-c0-dev libseccomp-dev
+# mkdir -p ~/src/github.com/projectatomic/
+# cd ~/src/github.com/projectatomic/
+# git clone https://github.com/projectatomic/libpod/
+#
+# cd libpod
+# make
+# sudo make install PREFIX=/usr
+# sudo mkdir -p /etc/containers
+# sudo bash -c 'cat <<EOF > /etc/containers/registries.conf
+registries.search
+registries = ['docker.io', 'registry.fedoraproject.org']
+EOF
+'
+# sudo bash -c 'cat <<EOF > /etc/containers/policy.json
+ {
+     "default": [
+         {
+             "type": "insecureAcceptAnything"
+         }
+     ],
+     "transports":
+         {
+             "docker-daemon":
+                 {
+                     "": [{"type":"insecureAcceptAnything"}]
+                 }
+         }
+ }
+ EOF
+'
+# git clone https://github.com/containernetworking/plugins.git ~/src/github.com/containernetworking/plugins
+# cd ~/src/github.com/containernetworking/plugins
+# ./build
+# sudo mkdir -p /usr/libexec/cni
+# sudo cp bin/* /usr/libexec/cni
+# git clone https://github.com/opencontainers/runc.git ~/src/github.com/opencontainers/runc
+# GOPATH=~/ make static BUILDTAGS="seccomp selinux"
+# sudo cp runc /usr/bin/runc
+# sudo mkdir -p /usr/local/libexec
+# sudo ln -s /usr/libexec/crio /usr/local/libexec/
+```
+
+) -->
+## Familiarizing yourself with Podman
+
+### Running a sample container
+This sample container will run a very basic httpd server that serves only its index
+page.
+```
+# sudo podman run -dt -e HTTPD_VAR_RUN=/var/run/httpd -e HTTPD_MAIN_CONF_D_PATH=/etc/httpd/conf.d \
+                    -e HTTPD_MAIN_CONF_PATH=/etc/httpd/conf \
+                    -e HTTPD_CONTAINER_SCRIPTS_PATH=/usr/share/container-scripts/httpd/ \
+                    registry.fedoraproject.org/f26/httpd /usr/bin/run-httpd
+```
+Because the container is being run in detached mode, represented by the *-d* in the podman run command, podman
+will print the container ID after it has run.
+
+### Listing running containers
+The Podman *ps* command is used to list creating and running containers.
+```
+# sudo podman ps
+```
+
+Note: If you add *-a* to the *ps* command, Podman will show all containers.
+
+### Executing a command in a running container
+You can use the *exec* subcommand to execute a command in a running container.  Eventually you will be able to
+obtain the IP address of the container through inspection, but that is not enabled yet.  Therefore, we will
+install *iproute* in the container.  Notice here that we use the switch **--latest** as a shortcut for the latest
+created container.  You could also use the container's ID listed during *podman ps* in the previous step or
+when you ran the container.
+```
+# sudo podman exec --latest -t dnf -y install iproute
+# sudo podman exec --latest -t ip a
+```
+
+Note the IP address of the *ethernet* device.
+
+### Testing the httpd server
+Now that we have the IP address of the container, we can test the network communication between the host
+operating system and the container using curl. The following command should display the index page of our
+containerized httpd server.
+```
+# curl http://<IP_address>:8080
+```
+
+### Viewing the container's logs
+You can view the container's logs with Podman as well:
+```
+# sudo podman logs --latest
+```
+
+<!-- (
+### Viewing the container's pids
+And you can observe the httpd pid in the container with *top*.
+```
+# sudo podman top <container_id>
+``` ) -->
+### Stopping the container
+To stop the httpd container:
+```
+# sudo podman stop --latest
+```
+You can also check the status of one or more containers using the *ps* subcommand. In this case, we should
+use the *-a* argument to list all containers.
+```
+# sudo podman ps -a
+```
+
+### Removing the container
+To remove the httpd container:
+```
+# sudo podman rm --latest
+```
+You can verify the deletion of the container by running *podman ps -a*.
+## More information
+
+For more information on Podman and its subcommands, checkout the asciiart demos on the [README](https://github.com/projectatomic/libpod#commands)
+page.