diff options
Diffstat (limited to 'docs/tutorials/podman_tutorial.md')
| -rw-r--r-- | docs/tutorials/podman_tutorial.md | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md new file mode 100644 index 000000000..619e83c35 --- /dev/null +++ b/docs/tutorials/podman_tutorial.md @@ -0,0 +1,156 @@ + + +# 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. |