From 23d39494216776fcaa2d386eb0d3161ec1e484de Mon Sep 17 00:00:00 2001
From: ducoterra <git@ducoterra.net>
Date: Tue, 14 Oct 2025 12:38:42 -0400
Subject: [PATCH] improve podman template with checkboxes and better
 descriptions

---
 templates/podman/foobar.md | 102 +++++++++++++++++++++++++------------
 1 file changed, 69 insertions(+), 33 deletions(-)

diff --git a/templates/podman/foobar.md b/templates/podman/foobar.md
index 24a2ce9..c1440aa 100644
--- a/templates/podman/foobar.md
+++ b/templates/podman/foobar.md
@@ -5,64 +5,62 @@
   - [Install foobar](#install-foobar)
     - [Create the foobar user](#create-the-foobar-user)
     - [Write the foobar compose spec](#write-the-foobar-compose-spec)
+      - [A Note on Volumes](#a-note-on-volumes)
     - [Convert foobar compose spec to quadlets](#convert-foobar-compose-spec-to-quadlets)
+    - [Create any container-mounted directories](#create-any-container-mounted-directories)
+    - [Start and enable your systemd quadlet](#start-and-enable-your-systemd-quadlet)
     - [Expose foobar](#expose-foobar)
       - [firewalld](#firewalld)
   - [Backup foobar](#backup-foobar)
   - [Upgrade foobar](#upgrade-foobar)
     - [Upgrade Quadlets](#upgrade-quadlets)
+  - [Uninstall](#uninstall)
   - [Notes](#notes)
     - [SELinux](#selinux)
 
 ## Setup foobar Project
 
-1. Copy and rename this folder to active/podman_foobar
-2. Find and replace foobar with the name of the service.
-3. Create the rootless user to run the podman containers
-4. Write the compose.yaml spec for your service
-5. Convert the compose.yaml spec to a quadlet
-6. Install the quadlet on the podman server
-7. Expose the quadlet service
-8. Install a backup service and timer
+- [ ] Copy and rename this folder to active/podman_foobar
+- [ ] Find and replace foobar with the name of the service.
+- [ ] Create the rootless user to run the podman containers
+- [ ] Write the compose.yaml spec for your service
+- [ ] Convert the compose.yaml spec to a quadlet
+- [ ] Install the quadlet on the podman server
+- [ ] Expose the quadlet service
+- [ ] Install a backup service and timer
 
 ## Install foobar
 
 ### Create the foobar user
 
 ```bash
+# SSH into your podman server as root
 useradd foobar
-
-su - foobar
-ssh-keygen
-exit
-cp ~/.ssh/authorized_keys /home/foobar/.ssh/authorized_keys
-chown foobar:foobar /home/foobar/.ssh/authorized_keys
 loginctl enable-linger $(id -u foobar)
-```
-
-SSH into the server as foobar
-
-```bash
-systemctl --user enable podman-restart
-systemctl --user enable --now podman.socket
-mkdir -p ~/.config/containers/systemd
+systemctl --user --machine=foobar@.host enable podman-restart
+systemctl --user --machine=foobar@.host enable --now podman.socket
+mkdir -p /home/foobar/.config/containers/systemd
 ```
 
 ### Write the foobar compose spec
 
-Edit the compose.yaml at active/foobar/compose/compose.yaml
+Edit the compose.yaml at active/podman_foobar/compose/compose.yaml
+
+#### A Note on Volumes
+
+Named volumes are stored at `/home/foobar/.local/share/containers/storage/volumes/`.
 
 ### Convert foobar compose spec to quadlets
 
-On your local machine:
+Run the following to convert a compose.yaml into the various `.container` files for systemd:
 
 ```bash
 # Generate the systemd service
 podman run \
 --security-opt label=disable \
 --rm \
--v $(pwd)/active/foobar/:/compose \
--v $(pwd)/active/foobar/quadlets:/quadlets \
+-v $(pwd)/active/podman_foobar/:/compose \
+-v $(pwd)/active/podman_foobar/quadlets:/quadlets \
 quay.io/k9withabone/podlet \
 -f /quadlets \
 -i \
@@ -70,14 +68,35 @@ quay.io/k9withabone/podlet \
 compose /compose/compose.yaml
 
 # Copy the files to the server
-scp -r active/foobar/quadlets/. foobar:~/.config/containers/systemd/
+export PODMAN_SERVER=
+scp -r active/podman_foobar/quadlets/. $PODMAN_SERVER:/home/foobar/.config/containers/systemd/
+ssh $PODMAN_SERVER chown -R foobar:foobar /home/foobar/.config/containers/systemd/
 ```
 
+### Create any container-mounted directories
+
+SSH into your podman server as root:
+
 ```bash
-ssh foobar systemctl --user daemon-reload
-ssh foobar systemctl --user restart foobar
-# Enables auto-update service which will pull new container images automatically every day
-ssh foobar systemctl --user enable --now podman-auto-update.timer
+machinectl shell foobar@
+podman unshare
+mkdir some_volume
+# Chown to the namespaced user with UID 1000
+# This will be some really obscure UID outside the namespace
+# This will also solve most permission denied errors
+chown -R 1000:1000 some_volume
+```
+
+### Start and enable your systemd quadlet
+
+SSH into your podman server as root:
+
+```bash
+machinectl shell foobar@
+systemctl --user daemon-reload
+systemctl --user restart foobar
+# Enable auto-update service which will pull new container images automatically every day
+systemctl --user enable --now podman-auto-update.timer
 ```
 
 ### Expose foobar
@@ -112,14 +131,31 @@ Follow the [Borg Backup instructions](/active/systemd_borg/borg.md#set-up-a-clie
 
 ### Upgrade Quadlets
 
-Upgrades should be a repeat of [writing the compose spec](#convert-compose-to-quadlet) and [installing the quadlets](#convert-compose-to-quadlet)
+Upgrades should be a repeat of [writing the compose spec](#convert-foobar-compose-spec-to-quadlets) and [installing the quadlets](#start-and-enable-your-systemd-quadlet)
 
 ```bash
-scp -r quadlets/. foobar:~/.config/containers/systemd/
+export PODMAN_SERVER=
+scp -r quadlets/. $PODMAN_SERVER$:/home/foobar/.config/containers/systemd/
 ssh foobar systemctl --user daemon-reload
 ssh foobar systemctl --user restart foobar
 ```
 
+## Uninstall
+
+```bash
+# Stop the user's services
+systemctl --user disable podman-restart
+podman container stop --all
+systemctl --user disable --now podman.socket
+systemctl --user disable --now podman-auto-update.timer
+
+# Delete the user (this won't delete their home directory)
+# userdel might spit out an error like:
+# userdel: user foobar is currently used by process 591255
+# kill those processes and try again
+userdel foobar
+```
+
 ## Notes
 
 ### SELinux