From d04945b5429f18b82657ce8c69e99aa06a8e787d Mon Sep 17 00:00:00 2001
From: Joerg Kastning <3941069+Tronde@users.noreply.github.com>
Date: Thu, 18 Aug 2022 22:24:05 +0200
Subject: [PATCH 1/5] Create Podman.md

It's work in progress. Following issues exist:

- There is no `release` tag in the docker image. See [#1875](https://github.com/shaarli/Shaarli/issues/1875)
- Example NGINX reverse proxy config is missing
- Example of generating systemd unit files and install them is missing
---
 doc/md/Podman.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 doc/md/Podman.md

diff --git a/doc/md/Podman.md b/doc/md/Podman.md
new file mode 100644
index 000000000..0ef1d6232
--- /dev/null
+++ b/doc/md/Podman.md
@@ -0,0 +1,76 @@
+# 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
+- `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 shaarli/shaarli
+
+# create persistent data volumes/directories on the host
+podman volume create shaarli-data
+podman volume create shaarli-cache
+
+# 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 \
+           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/).
+
+## 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.

From 274bfdc3ed740468ced5403f35566080a050e2f7 Mon Sep 17 00:00:00 2001
From: Joerg Kastning <3941069+Tronde@users.noreply.github.com>
Date: Mon, 29 Aug 2022 14:30:00 +0200
Subject: [PATCH 2/5] Update Podman.md

* Make a note regarding the broken `release` tag
* Add systemd section
---
 doc/md/Podman.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/doc/md/Podman.md b/doc/md/Podman.md
index 0ef1d6232..46f08fa1d 100644
--- a/doc/md/Podman.md
+++ b/doc/md/Podman.md
@@ -25,7 +25,7 @@ Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/sha
 
 - `latest`: master (development) branch
 - `vX.Y.Z`: shaarli [releases](https://github.com/shaarli/Shaarli/releases)
-- `release`: always points to the last release
+- `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:
@@ -71,6 +71,51 @@ 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.
+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.

From f8ba780a3b9c29e5968679bb15003c5500f3c7b9 Mon Sep 17 00:00:00 2001
From: Joerg Kastning <3941069+Tronde@users.noreply.github.com>
Date: Tue, 13 Dec 2022 20:20:04 +0100
Subject: [PATCH 3/5] Use full qualified path with release tag

Co-authored-by: nodiscc <nodiscc@gmail.com>
---
 doc/md/Podman.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/md/Podman.md b/doc/md/Podman.md
index 46f08fa1d..847bda161 100644
--- a/doc/md/Podman.md
+++ b/doc/md/Podman.md
@@ -38,7 +38,7 @@ Here is an example of how to run Shaarli latest image using Podman:
 
 ```bash
 # download the image from dockerhub
-podman pull shaarli/shaarli
+podman pull docker.io/shaarli/shaarli:release
 
 # create persistent data volumes/directories on the host
 podman volume create shaarli-data

From 407e40e534c8d81300c1f74bcc9d338540a83373 Mon Sep 17 00:00:00 2001
From: Joerg Kastning <3941069+Tronde@users.noreply.github.com>
Date: Tue, 13 Dec 2022 20:20:33 +0100
Subject: [PATCH 4/5] Use full qualified path with release tag

Co-authored-by: nodiscc <nodiscc@gmail.com>
---
 doc/md/Podman.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/md/Podman.md b/doc/md/Podman.md
index 847bda161..186515022 100644
--- a/doc/md/Podman.md
+++ b/doc/md/Podman.md
@@ -56,7 +56,7 @@ podman run --detach \
            --rm \
            --volume shaarli-data:/var/www/shaarli/data \
            --volume shaarli-cache:/var/www/shaarli/cache \
-           shaarli/shaarli:release
+           docker.io/shaarli/shaarli:release
            
 # verify that the container is running
 podman ps | grep myshaarli

From 4a59c9123de885a62c35ec8ea862b7a7bae894fe Mon Sep 17 00:00:00 2001
From: Joerg Kastning <3941069+Tronde@users.noreply.github.com>
Date: Sun, 18 Dec 2022 11:42:00 +0100
Subject: [PATCH 5/5] Set correct file ownership for podman volumes

Since the NGINX process in the container is running with UID 100 and GID 101 the file ownership for the podman volumes have to be adjusted in the user namespace of the container/pod.

This is done with the `podman unshare` command in line 50.
---
 doc/md/Podman.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/md/Podman.md b/doc/md/Podman.md
index 186515022..51967351a 100644
--- a/doc/md/Podman.md
+++ b/doc/md/Podman.md
@@ -44,6 +44,12 @@ podman pull docker.io/shaarli/shaarli:release
 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