dev/podman/README.md

0001 # Scripts to Run KBibTeX in a Podman Container
0002
0003 *Podman* is a Linux container solution (operating system-level virtualization) that is an alternative to Docker, but is daemonless by design and allows rootless containers.
0004 It is well supported on Linux distributions like Fedora or Arch.
0005 For further information, please visit Podman's webpage at [podman.io](https://podman.io/).
0006
0007 Before proceeding with this README, please ensure that you have a working Podman installation and that you as a non-priviledged user can pull images from Docker's hub and run container instances.
0008 Please refer to your Linux distribution's manual and Podman's official documentation.
0009
0010 There are two scripts that prepare images for KBibTeX and allow running KBibTeX or any of its automated tests.
0011 The first script prepares a container image that contains all necessary tools and development libraries to compile KBibTeX.
0012 This container image only needs to be rebuilt once in a while (e.g. on a weekly or monthly base).
0013 The second script prepares a container image that contains KBibTeX's sources and compiles KBibTeX for its execution.
0014 This image needs to be rebuilt whenever a new revision of the source code needs to be tested.
0015
0016 ## Preparing a Developer Image
0017
0018 The first script is called `create-development-image.sh` which creates a developer image.
0019 Several distributions' base systems are available to choose from.
0020 Simply pass one of the pre-configured distributions are an argument to this script.
0021 Available alternatives are `debian10`, `debian11`, `ubuntu`, `fedora`, `archlinux`, `kdeneon`.
0022
0023 Example invocation:
0024
0025 ```
0026 ./create-development-image.sh kdeneon
0027 ```
0028
0029 Creating such developer instances may download several GiB of data, both for the base image itself and additional packages to be installed in the image under creation.
0030
0031 ## Creating Image with KBibTeX and Run Graphical Program
0032
0033 The second script, `compile-and-run-in-container.sh` will prepare a container image where it compiles the current source code.
0034 The generated image contains the graphical KBibTeX program and all automated tests.
0035 By default, first all tests are run and then the graphical client is launched.
0036 Making use of X-forwarding, the graphical client will almost look like a locally installed program (with difference due to different icons, themes, and fonts).
0037
0038 Like the first script, this second script takes one argument: the distribution-specific image created by the first script.
0039
0040 Example invocation:
0041
0042 ```
0043 ./compile-and-run-in-container.sh kdeneon
0044 ```
0045
0046 ## Cleaning and Removing Images and Container Instances
0047
0048 Both scripts support a special argument `--cleanup` instead of a distribution name.
0049 Invoking the scripts with this argument will not actually clean up (i.e. remove) anything, but will print out instructions how to remove container images and instances.
0050
0051 To understand what those `podman` and `buildah` invocations do, please have a look at the commands' man pages and other documentation.