Podman section for documentation

doc/md/Podman.md

@@ -0,0 +1,127 @@
+# Podman
+
+[Podman](https://docs.podman.io/en/latest/) is a daemonless container engine for developing, managing, and running OCI Containers on your Linux System. Containers can either be run as root or in rootless mode.
+
+## Install Podman
+
+[Install Podman](https://podman.io/getting-started/installation), by following the instructions relevant to your OS / distribution. For example on Debian:
+
+~~~
+sudo apt-get -y install podman
+~~~
+
+*The podman package is available in the Debian 11 (Bullseye) repositories and later.*
+
+## Setup Podman
+
+The following two tutorials show you how to set up Podman and perform some basic commands with the utility:
+
+ * [Basic Setup and Use of Podman](https://github.com/containers/podman/blob/main/docs/tutorials/podman_tutorial.md)
+ * [Basic Setup and Use of Podman in a Rootless environment](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
+
+## Get and run a Shaarli image
+
+Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`:
+
+- `latest`: master (development) branch
+- `vX.Y.Z`: shaarli [releases](https://github.com/shaarli/Shaarli/releases)
+- `release`: always points to the last release **Note:** Currently broken. See issue [#1875](https://github.com/shaarli/Shaarli/issues/1875). Use `stable` instead.
+- `stable` and `master`: **deprecated**. These tags are no longer maintained and may be removed without notice
+
+These images are built automatically on DockerHub and rely on:
+
+- [Alpine Linux](https://www.alpinelinux.org/)
+- [PHP7-FPM](http://php-fpm.org/)
+- [Nginx](http://nginx.org/)
+
+Here is an example of how to run Shaarli latest image using Podman:
+
+```bash
+# download the image from dockerhub
+podman pull docker.io/shaarli/shaarli:release
+
+# create persistent data volumes/directories on the host
+podman volume create shaarli-data
+podman volume create shaarli-cache
+
+# Since the NGINX process in the container is running with UID 100 and GID 101 the
+# UID and GID for the volumes just created have to adjusted in the user namespace.
+# For detailed information see podman-unshare(1).
+podman unshare chown 100:101 -R \
+            .local/share/containers/storage/volumes/shaarli-{cache,data}
+
+# create a new container using the Shaarli image
+# --detach: run the container in background
+# --name: name of the created container/instance
+# --publish: map the host's :8000 port to the container's :80 port
+# --rm: automatically remove the container when it exits
+# --volume: mount persistent volumes in the container ($volume_name:$volume_mountpoint)
+podman run --detach \
+           --name myshaarli \
+           --publish 8000:80 \
+           --rm \
+           --volume shaarli-data:/var/www/shaarli/data \
+           --volume shaarli-cache:/var/www/shaarli/cache \
+           docker.io/shaarli/shaarli:release
+
+# verify that the container is running
+podman ps | grep myshaarli
+
+# to completely remove the container
+podman stop myshaarli # stop the running container
+podman ps | grep myshaarli # verify the container is no longer running
+podman ps -a | grep myshaarli # verify the container is stopped
+podman rm myshaarli # destroy the container
+podman ps -a | grep myshaarli # verify th container has been destroyed
+```
+
+After running `podman run` command, your Shaarli instance should be available on the host machine at [localhost:8000](http://localhost:8000/). In order to access your instance through a reverse proxy, see [reverse proxy](https://shaarli.readthedocs.io/en/master/Reverse-proxy/).
+
+In case you are running a rootless podman setup, you have to make sure that the process (PID) inside the container has write access to your podman volumes.
+
+## Generating systemd service units for containerized Shaarli
+
+Podman is able to create a systemd unit file that can be used to control a container or pod (see podman-generate-systemd(1). Example:
+
+~~~
+$ podman generate systemd --new -n -f my-shaarli
+~~~
+
+The command creates the following systemd unit file:
+
+~~~
+# container-my-shaarli.service
+# autogenerated by Podman 3.0.1
+# Tue Aug 23 22:39:30 CEST 2022
+
+[Unit]
+Description=Podman container-my-shaarli.service
+Documentation=man:podman-generate-systemd(1)
+Wants=network.target
+After=network-online.target
+
+[Service]
+Environment=PODMAN_SYSTEMD_UNIT=%n
+Restart=on-failure
+TimeoutStopSec=70
+ExecStartPre=/bin/rm -f %t/container-my-shaarli.pid %t/container-my-shaarli.ctr-id
+ExecStart=/usr/bin/podman run --conmon-pidfile %t/container-my-shaarli.pid --cidfile %t/container-my-shaarli.ctr-id --cgroups=no-conmon --replace --detach --name my-shaarli --publish 127.0.0.1:8001:80 --rm --volume shaarli-data:/var/www/shaarli/data:rw,nodev,noexec --volume shaarli-cache:/var/www/shaarli/cache:rw,nodev,noexec shaarli/shaarli:stable
+ExecStop=/usr/bin/podman stop --ignore --cidfile %t/container-my-shaarli.ctr-id -t 10
+ExecStopPost=/usr/bin/podman rm --ignore -f --cidfile %t/container-my-shaarli.ctr-id
+PIDFile=%t/container-my-shaarli.pid
+Type=forking
+
+[Install]
+WantedBy=multi-user.target default.target
+~~~
+
+This unit could be installed by copying it to an appropriate location and reloading your daemons, e.g.:
+
+~~~
+$ mv container-my-shaarli.service ~/.config/systemd/user.control/
+$ systemctl --user daemon-reload
+$ podman stop my-shaarli
+$ systemctl --user start container-my-shaarli.service
+~~~
+
+Now, you are able to control your Shaarli container like any other systemd service.