containers
/
podman
mirror of https://github.com/containers/podman.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #24263 from edsantiago/packaging-doc 

Document packaging process
This commit is contained in:
openshift-merge-bot[bot] 2024-10-23 20:55:41 +00:00 committed by GitHub
parent beea471498 a92958eb0c
commit 70d581029b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 83 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
DISTRO_PACKAGE.md
View File

@ -1,101 +1,111 @@
# Podman Packaging # Podman Packaging
This document is currently written with Fedora as a reference, intended for use This document is intended for Podman *packagers*: those very few individuals
by packagers of other distros as well as package users. responsible for building and shipping Podman on Linux distributions.
## Fedora Users Document verified accurate as of Podman 5.2, 2024-10-16.
Podman v4 is available as an official Fedora package on Fedora 36 and rawhide.
This version of Podman brings with it a new container stack called
Netavark which serves as a replacement for CNI plugins
(containernetworking-plugins on Fedora), as well as Aardvark-dns, the
authoritative DNS server for container records.
Both Netavark and Aardvark-dns are available as official Fedora packages on ## Building Podman
Fedora 35 and newer versions and form the default network stack for new
installations of Podman 4.0.
On Fedora 36 and newer, fresh installations of Podman v4 will This document assumes you are able to build executables up to and
automatically install Aardvark-dns along with Netavark. including `make install`.
See [Building from Source](https://podman.io/docs/installation#building-from-source)
on podman.io for possibly-outdated instructions.
To install Podman v4: ## Package contents
```console Everything installed by `make install`, obviously.
$ sudo dnf install podman
Upstream splits Podman into multiple subpackages and we encourage you
to consider doing likewise: some users may not want `podman-remote`
or `-machine` or the test suite.
The best starting point is the
[RPM spec file](https://github.com/containers/podman/blob/main/rpm/podman.spec).
This illustrates the subpackage breakdown as well as top-level dependencies.
## Dependencies
Podman requires a *runtime*, a *runtime monitor*, a *pause process*,
and *networking tools*. In Fedora, some of these requirements are indirectly
specified via [containers-common](https://github.com/containers/common);
the nested tree looks like this:
```
Podman
├── Requires: catatonit
├── Requires: conmon
└── Requires: containers-common-extra
├── Requires: crun
├── Requires: netavark
└── Requires: passt
``` ```
To update Podman from an older version to v4: ### Runtime: crun
```console The only runtime supported upstream is [crun](https://github.com/containers/crun),
$ sudo dnf update podman but different distros may wish to offer other options to their users. Your package
``` must, directly or indirectly, list a runtime prerequisite.
**NOTE:** Fedora 35 users will not be able to install Podman v4 using the default yum Heads up: you may end up being responsible for packaging this runtime, or at the
repositories and are recommended to use the COPR repo below: very least working closely with the package maintainer. The best starting point
for crun is its
[RPM spec file](https://github.com/containers/crun/blob/main/rpm/crun.spec).
```console
$ sudo dnf copr enable rhcontainerbot/podman4
# install or update per your needs ### Pause process: catatonit
$ sudo dnf install podman
```
After installation, if you would like to migrate all your containers to use The pause process serves as a container `init`, reaping PIDs and handling signals.
Netavark, you will need to set `network_backend = "netavark"` under
the `[network]` section in your containers.conf, typically located at:
`/usr/share/containers/containers.conf`
### Testing the latest development version` As of this writing, Podman uses an external tool,
[catatonit](https://github.com/openSUSE/catatonit). This may be subject
to change in future Podman versions.
If you would like to test the latest unreleased upstream code, try the If you need to package catatonit, a good starting point might be its
podman-next COPR [Fedora specfile](https://src.fedoraproject.org/rpms/catatonit/blob/rawhide/f/catatonit.spec).
```console
$ sudo dnf copr enable rhcontainerbot/podman-next
$ sudo dnf install podman ### Runtime Monitor: conmon
```
**CAUTION:** The podman-next COPR provides the latest unreleased sources of Podman, The only working monitor is [conmon](https://github.com/containers/conmon).
Netavark and Aardvark-dns as rpms which would override the versions provided by There is a Rust implementation in the works,
the official packages. [conmon-rs](https://github.com/containers/conmon-rs), but efforts
to make it work with Podman have stalled for years.
## Distro Packagers Heads up: you may end up being responsible for packaging conmon.
The best starting point is its
[RPM spec file](https://github.com/containers/conmon/blob/main/rpm/conmon.spec).
The Fedora packaging sources for Podman are available at the [Podman
dist-git](https://src.fedoraproject.org/rpms/podman).
The main `podman` package no longer explicitly depends on ### Networking Tools: netavark, aardvark-dns, passt
containernetworking-plugins. The network stack dependencies are now handled in
the [containers-common](https://src.fedoraproject.org/rpms/containers-common)
package which allows for a single point of dependency maintenance for Podman
and Buildah.
- containers-common Networking differs between *root* and *rootless*: [passt](https://passt.top/)
``` (also referred to as "pasta") is only needed for rootless.
Requires: container-network-stack [netavark](https://github.com/containers/netavark/) and
Recommends: netavark [aardvark-dns](https://github.com/containers/aardvark-dns/)
``` are needed for both root and rootless podman.
- netavark Heads up: you will probably end up being responsible for packaging
``` at least some of these. The best starting points are their respective
Provides: container-network-stack = 2 RPM spec files:
``` [netavark](https://github.com/containers/netavark/blob/main/rpm/netavark.spec),
[aardvark-dns](https://github.com/containers/aardvark-dns/blob/main/rpm/aardvark-dns.spec).
- containernetworking-plugins Netavark and aardvark-dns must be packaged in lockstep down
``` to the major-minor level: version `X.Y` of either is only
Provides: container-network-stack = 1 guaranteed to work with `X.Y` of the other. If you are responsible
``` for packaging these, make sure you set up interpackage dependencies
appropriately to prevent version mismatches between them.
This configuration ensures: ## Metapackage: containers-common
- New installations of Podman will always install netavark by default.
- The containernetworking-plugins package will not conflict with netavark and
users can install them together.
## Listing bundled dependencies This package provides config files, man pages, and (at the
If you need to list the bundled dependencies in your packaging sources, you can packaging level) dependencies. There are good reasons for
process the `go.mod` file in the upstream source. keeping this as a separate package, the most important one
For example, Fedora's packaging source uses: being that `buildah` and `skopeo` rely on this same content.
Also important is the ability for individual distros to
fine-tune config settings and dependencies.
``` You will probably be responsible for packaging this.
$ awk '{print "Provides: bundled(golang("$1")) = "$2}' go.mod | sort | uniq | sed -e 's/-/_/g' -e '/bundled(golang())/d' -e '/bundled(golang(go\|module\|replace\|require))/d' The best starting point is its
``` [RPM spec file](https://github.com/containers/common/blob/main/rpm/containers-common.spec).