overhauls of most service docs

templates/podman/foobar.md

@@ -0,0 +1,131 @@
+# Podman foobar
+
+- [Podman foobar](#podman-foobar)
+  - [Setup foobar Project](#setup-foobar-project)
+  - [Install foobar](#install-foobar)
+    - [Create the foobar user](#create-the-foobar-user)
+    - [Write the foobar compose spec](#write-the-foobar-compose-spec)
+    - [Convert foobar compose spec to quadlets](#convert-foobar-compose-spec-to-quadlets)
+    - [Expose foobar](#expose-foobar)
+      - [firewalld](#firewalld)
+  - [Backup foobar](#backup-foobar)
+  - [Upgrade foobar](#upgrade-foobar)
+    - [Upgrade Quadlets](#upgrade-quadlets)
+  - [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
+
+## Install foobar
+
+### Create the foobar user
+
+```bash
+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
+```
+
+### Write the foobar compose spec
+
+Edit the compose.yaml at active/foobar/compose/compose.yaml
+
+### Convert foobar compose spec to quadlets
+
+On your local machine:
+
+```bash
+# Generate the systemd service
+podman run \
+--security-opt label=disable \
+--rm \
+-v $(pwd)/active/foobar/:/compose \
+-v $(pwd)/active/foobar/quadlets:/quadlets \
+quay.io/k9withabone/podlet \
+-f /quadlets \
+-i \
+--overwrite \
+compose /compose/compose.yaml
+
+# Copy the files to the server
+scp -r active/foobar/quadlets/. foobar:~/.config/containers/systemd/
+```
+
+```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
+```
+
+### Expose foobar
+
+1. If you need a domain, follow the [DDNS instructions](/active/podman_ddns/ddns.md#install-a-new-ddns-service)
+2. For a web service, follow the [Caddy instructions](/active/podman_caddy/caddy.md#adding-a-new-caddy-record)
+3. Finally, follow your OS's guide for opening ports via its firewall service.
+
+#### firewalld
+
+```bash
+# command to get current active zone and default zone
+firewall-cmd --get-active-zones
+firewall-cmd --get-default-zone
+
+# command to open 443 on tcp
+firewall-cmd --permanent --zone=<zone> --add-port=443/tcp
+
+# command to open 80 and 443 on tcp and udp
+firewall-cmd --permanent --zone=<zone> --add-port={80,443}/{tcp,udp}
+
+# command to list available services and then open http and https
+firewall-cmd --get-services
+firewall-cmd --permanent --zone=<zone> --add-service={http,https}
+```
+
+## Backup foobar
+
+Follow the [Borg Backup instructions](/active/systemd_borg/borg.md#set-up-a-client-for-backup)
+
+## Upgrade foobar
+
+### Upgrade Quadlets
+
+Upgrades should be a repeat of [writing the compose spec](#convert-compose-to-quadlet) and [installing the quadlets](#convert-compose-to-quadlet)
+
+```bash
+scp -r quadlets/. foobar:~/.config/containers/systemd/
+ssh foobar systemctl --user daemon-reload
+ssh foobar systemctl --user restart foobar
+```
+
+## Notes
+
+### SELinux
+
+<https://blog.christophersmart.com/2021/01/31/podman-volumes-and-selinux/>
+
+:z allows a container to share a mounted volume with all other containers.
+
+:Z allows a container to reserve a mounted volume and prevents any other container from accessing.