opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-07-02 08:47:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

[CI:DOCS] Docs revamp.

Browse Source 
* Rewrote the Home and Introduction pages.
* Created a dedicated Search page
* Rewrote the Tutorials page to have native links in RTD/Shpinx
* Added iframe to Reference page to display API reference docs inline

Signed-off-by: Scott McCarty <scott.mccarty@gmail.com>
This commit is contained in:
Scott McCarty
2020-05-20 16:30:32 -04:00
parent 6a75dfa8a8
commit 176f38c25b
8 changed files with 171 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/Commands.rst
View File

@ -1,3 +1,5 @@
.. include:: includes.rst
Commands
========

106
docs/source/Introduction.rst
View File

@ -1,2 +1,106 @@
.. include:: includes.rst
Introduction
============
==================================
Containers_ simplify the consumption of applications with all of their dependencies and default configuration files. Users test drive or deploy a new application with one or two commands instead of following pages of installation instructions. Here's how to find your first `Container Image`_::
podman search busybox
Output::
INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED
docker.io docker.io/library/busybox Busybox base image. 1882 [OK]
docker.io docker.io/radial/busyboxplus Full-chain, Internet enabled, busybox made f... 30 [OK]
docker.io docker.io/yauritux/busybox-curl Busybox with CURL 8
...
The previous command returned a list of publicly available container images on DockerHub. These container images are easy to consume, but of differing levels of quality and maintenance. Let’s use the first one listed because it seems to be well maintained.
To run the busybox container image, it’s just a single command::
podman run -it docker.io/library/busybox
Output::
/ #
You can poke around in the busybox container for a while, but you’ll quickly find that running small container with a few Linux utilities in it provides limited value, so exit out::
exit
There’s an old saying that “nobody runs an operating system just to run an operating system” and the same is true with containers. It’s the workload running on top of an operating system or in a container that’s interesting and valuable.
Sometimes we can find a publicly available container image for the exact workload we’re looking for and it will already be packaged exactly how we want. But, more often than not, there’s something that we want to add, remove, or customize. It could be as simple as a configuration setting for security or performance, or as complex as adding a complex workload. Either way, containers make it fairly easy to make the changes we need.
Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build the new and can easily be shared with others publicly using tools like GitHub.
Here's an example of how to build an Nginx web server on top of a Debian base image using the Dockerfile maintained by Nginx and published in GitHub::
podman build -t nginx https://git.io/Jf8ol
Once, the image build completes, it’s easy to run the new image from our local cache::
podman run -d -p 8080:80 nginx
curl localhost:8080
Output::
...
<p><em>Thank you for using nginx.</em></p>
...
Building new images is great, but sharing our work with others let’s them review our work, critique how we built them, and offer improved versions. Our newly built Nginx image could be published at quay.io or docker.io to share it with the world. Everything needed to run the Nginx application is provided in the container image. Others could easily pull it down and use it, or make improvements to it.
Standardizing on container images and `Container Registries`_ enable a new level of collaboration through simple consumption. This simple consumption model is possible because every major Container Engine and Registry Server uses the Open Containers Initiative (OCI_) format. This allows users to find, run, build, share and deploy containers anywhere they want. Podman and other `Container Engines`_ like CRI-O, Docker, or containerd can create and consume container images from docker.io, quay.io, an on premise registry or even one provided by a cloud provider. The OCI image format facilitates this ecosystem through a single standard.
For example, if we wanted to share our newly built Nginx container image on quay.io it’s easy. First log in to quay::
podman login quay.io
Input::
Username: USERNAME
Password: ********
Login Succeeded!
Nex, tag the image so that we can push it into our user account::
podman tag localhost/nginx quay.io/USERNAME/nginx
Finally, push the image::
podman push quay.io/USERNAME/nginx
Output::
Getting image source signatures
Copying blob 38c40d6c2c85 done
Copying blob fee76a531659 done
Copying blob c2adabaecedb done
Copying config 7f3589c0b8 done
Writing manifest to image destination
Copying config 7f3589c0b8 done
Writing manifest to image destination
Storing signatures
Notice that we pushed four layers to our registry and now it’s available for others to share. Take a quick look::
podman inspect quay.io/USERNAME/nginx
Output::
[
{
"Id": "7f3589c0b8849a9e1ff52ceb0fcea2390e2731db9d1a7358c2f5fad216a48263",
"Digest": "sha256:7822b5ba4c2eaabdd0ff3812277cfafa8a25527d1e234be028ed381a43ad5498",
"RepoTags": [
"quay.io/USERNAME/nginx:latest",
...
To summarize, Podman makes it easy to find, run, build and share containers.
* Find: whether finding a container on dockerhub.io or quay.io, an internal registry server, or directly from a vendor, a couple of `podman search`_, and `podman pull`_ commands make it easy
* Run: it's easy to consume pre-built images with everything needed to run an entire application, or start from a Linux distribution base image with the `podman run`_ command
* Build: creating new layers with small tweaks, or major overhauls is easy with `podman build`
* Share: Podman let’s you push your newly built containers anywhere you want with a single `podman push`_ command
For more instructions on use cases, take a look at our :doc:`Tutorials` page.

8
docs/source/Reference.rst
View File

@ -1,4 +1,10 @@
.. include:: includes.rst
Reference
=========
Check out our new in-development `API documentation <_static/api.html>`_
To see full screen version please visit: `API documentation <https://docs.podman.io/en/latest/_static/api.html>`_
.. raw:: html
<iframe src="_static/api.html" allowfullscreen="true" height="600px" width="120%"></iframe>

18
docs/source/Search.rst Normal file
View File

@ -0,0 +1,18 @@
.. include:: includes.rst
Search
==================================
.. raw:: html
<p>
From here you can search these documents. Enter your search
words into the box below and click "search". Note that the search
function will automatically search for all of the words. Pages
containing fewer words won't appear in the result list.
</p>
<form action="/en/latest/search.html" method="get" _lpchecked="1">
<input type="text" name="q" value="">
<input type="submit" value="search">
<span id="search-progress" style="padding-left: 10px"></span>
</form>

10
docs/source/Tutorials.rst
View File

@ -1,4 +1,12 @@
.. include:: includes.rst
Tutorials
=========
Here are a number of useful tutorials to get you up and running with Podman. If you are familiar with the Docker `Container Engine`_ the command in Podman_ should be quite familiar. If are brand new to containers, take a look at our `Introduction`.
`Podman Tutorials on GitHub <https://github.com/containers/libpod/tree/master/docs/tutorials>`_
* `Basic Setup and Use of Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility.
* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated.
* `Podman Mac Client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md>`_: Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented.
* `How to sign and distribute container images using Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman.
* `Podman remote-client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client.
* `How to use libpod for custom/derivative projects <https://github.com/containers/libpod/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project.

2
docs/source/_static/api.html
View File

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<title>Reference</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">

19
docs/source/includes.rst Normal file
View File

@ -0,0 +1,19 @@
.. highlight:: bash
.. _Podman: http://podman.io
.. _OCI: https://www.opencontainers.org/
.. _Container Engine: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l
.. _Container Engines: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l
.. _Container Runtime: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo55
.. _Container: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e
.. _Containers: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e
.. _Container Image: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw
.. _Container Images: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw
.. _Container Registry: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq
.. _Container Registries: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq
.. _libpod: https://github.com/containers/libpod
.. _podman search: http://docs.podman.io/en/latest/markdown/podman-search.1.html
.. _podman pull: http://docs.podman.io/en/latest/markdown/podman-pull.1.html
.. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html
.. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html
.. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html
.. image:: https://github.com/containers/libpod/blob/master/logo/podman-logo.png?raw=true

25
docs/source/index.rst
View File

@ -1,10 +1,14 @@
.. Podman documentation master file, created by
sphinx-quickstart on Tue Oct 22 15:20:30 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. include:: includes.rst
Welcome to Podman's documentation!
What is Podman?
==================================
Podman_ is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI_) Containers_ and `Container Images`_. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker `Container Engine`_. Most users can simply alias Docker to Podman (`alias docker=podman`) without any problems. Similiar other common `Container Engines`_ (Docker, CRI-O, containerd), Podman relies on an OCI compliant `Container Runtime`_ (runc, crun, runv, etc) to interface with the operating system and create the running containers.This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine.
Containers under the control of Podman can either be run by root or by a non-privileged user. Podman manages the entire container ecosystem which includes pods, containers, container images, and container volumes using the libpod_ library. Podman specializes in all of the commands and functions that help you to maintain and modify OCI container images, such as pulling and tagging. It allows you to create, run, and maintain those containers and container images in a production environment.
The Podman service runs only on Linux platforms, however a REST API and clients are currently under development which will allow Mac and Windows platforms to call the service. There is currently a Varlink based remote client which runs on Mac or Windows platforms that allows the remote client to talk to the Podman server on a Linux platform. In addition to those clients, there is also a Mac client. NOTE: the Varlink remote client will be deprecated after the REST API is completed.
If you are completely new to containers, we recommend that you check out the :doc:`Introduction`. For power users or those comming from Docker, check out our :doc:`Tutorials`. For advanced users and contributors, you can get very detailed information about the Podman CLI by looking our :doc:`Commands` page. Finally, for Developers looking at how to interact with the Podman API, please see our API documentation :doc:`Reference`.
.. toctree::
:maxdepth: 2
@ -14,13 +18,4 @@ Welcome to Podman's documentation!
Commands
Reference
Tutorials
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Search