From c1b2278a534a5e4c2a12700d180994b4e199add8 Mon Sep 17 00:00:00 2001 From: baude Date: Wed, 27 Dec 2017 11:34:57 -0600 Subject: 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 Closes: #170 Approved by: baude --- README.md | 22 ++++---- podman_tutorial.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+), 11 deletions(-) create mode 100644 podman_tutorial.md 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 +``` + + +## 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://:8080 +``` + +### Viewing the container's logs +You can view the container's logs with Podman as well: +``` +# sudo podman logs --latest +``` + + +### 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. -- cgit v1.2.3-54-g00ecf