diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/podman-cp.1.md | 2 | ||||
| -rw-r--r-- | docs/podman-derivative-api.md | 44 | ||||
| -rw-r--r-- | docs/tutorials/README.md | 10 | ||||
| -rw-r--r-- | docs/tutorials/podman_tutorial.md | 2 |
4 files changed, 51 insertions, 7 deletions
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md index 736bdb12a..0f54b2e8b 100644 --- a/docs/podman-cp.1.md +++ b/docs/podman-cp.1.md @@ -29,7 +29,7 @@ Assuming a path separator of /, a first argument of **src_path** and second argu - **dest_path** does not exist - the file is saved to a file created at **dest_path** - **dest_path** does not exist and ends with / - - **dest_path** is created as a directory and the file is copied into this directory using the basename from **src_path** + - Error condition: the destination directory must exist. - **dest_path** exists and is a file - the destination is overwritten with the source file's contents - **dest_path** exists and is a directory diff --git a/docs/podman-derivative-api.md b/docs/podman-derivative-api.md new file mode 100644 index 000000000..0342bb740 --- /dev/null +++ b/docs/podman-derivative-api.md @@ -0,0 +1,44 @@ +# How to use libpod for custom/derivative projects + +libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. + +Running as a subprocess +--- + +Advantages: + + - Many commands output JSON + - Works with languages other than Golang + - Easy to get started + +Disadvantages: + + - Error handling is harder + - May be slower + - Can't hook into or control low-level things like how images are pulled + +Vendoring into a Go project +--- + +Advantages: + + - Significant power and control + +Disadvantages: + + - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate) + - Binary size + - Potential skew between multiple libpod versions operating on the same storage can cause problems + +Varlink +--- + +Some code exists for this; splits the difference. Future uncertain. + +Making the choice +--- + +A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? +If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally +different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, +that may drive you towards vendoring.
\ No newline at end of file diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index c340d683f..2cf9613b6 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -4,18 +4,18 @@ ## Links to a number of useful tutorials for the Podman utility. -**[Introduction Tutorial](https://github.com/containers/libpod/tree/master/docs/tutorials/podman_tutorial.md)** +**[Introduction Tutorial](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).** +**[Basic Setup and Use of Podman in a Rootless environment](rootless_tutorial.md)** The steps required to setup rootless Podman are enumerated. -**[Setup on OS X](https://github.com/containers/libpod/blob/master/doc/tutorials/mac_client.md)** +**[Setup on OS X](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 +Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented. -**[Remote Client](https://github.com/containers/libpod/blob/master/doc/tutorials/remote_client.md)** +**[Remote Client](remote_client.md)** A brief how-to on using the Podman remote-client. diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md index 559d25d6a..169cefc0e 100644 --- a/docs/tutorials/podman_tutorial.md +++ b/docs/tutorials/podman_tutorial.md @@ -5,7 +5,7 @@ Podman is a utility provided as part of the libpod library. It can be used to c containers. The following tutorial will teach you how to set up Podman and perform some basic commands with Podman. -If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/libpod/blob/master/mac_client.md) +If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md) to set up the remote Podman client. **NOTE**: the code samples are intended to be run as a non-root user, and use `sudo` where |