Updating readme, documentation, and a localhost warning - formalizing changes made for remote runsHEADmain

3 files changed, 105 insertions, 15 deletions

diff --git a/README.md b/README.md
index 9d71dcc..99b6178 100644
--- a/README.md
+++ b/README.md
@@ -8,35 +8,52 @@ This repo contains two roles, `host` and `containers`, that automate the deploym
 Quadlet files and some understanding of quadlet and/or systemd is required to use this tool.
 
 ## Usage
+    git clone https://github.com/spmfox/PodPlaybook.git && cd PodPlaybook
+    ansible-galaxy install -r collections/requirements.yml
     ansible-playbook host.yml
+
     sudo machinectl shell containers@
-    ansible-playbook -i docs/sample-environment/wordpress/wordpress.yml containers.yml
+    git clone https://github.com/spmfox/PodPlaybook.git && cd PodPlaybook
+    ansible-playbook -i docs/sample-environment/wordpress/wordpress.yml containers-local.yml
 
 ## Features
 - Designed for rootless Podman
 - Easily deploy/remove quadlet files and stop/start quadlet services
 - Define your application's quadlet files so they are treated as one entity with Ansible
+- Optionally configure your host with common settings like firewall, timezone, mounts, etc
 
 ## Sample Environment
 A fully working pod with Wordpress and a MariaDB database are in the `docs/sample-environment/wordpress` directory.
 The environment variables are in `wordpress.yml`, you'll also find the containerfiles and the quadlet files.
 
+## Example Inventory
+A example inventory is included in `docs/example-inventory.yml` showing all of the common host configuration variables as well as multiple quadlets.
+
 ## Requirements
 - Ansible
 - Podman
 - User with `sudo` rights (to create unprivileged user)
 
 ## Operation
-- **Note:** `host.yml` and `containers.yml` will default to execute on localhost if a host isn't provided
-    - This means you can either create a full inventory with a host and variables or just variables that will be run against localhost
-- `host.yml` - installs the needed packages and creates the `containers` unprivileged user - use with a privileged account
-- `containers.yml` - will copy the quadlet files and start the quadlet - use with the unprivileged account
+- `host.yml` - configures the host - can be run remotely or locally
+  - Default operation is to install podman and create+configure the containers user
+  - Can be used for configuring:
+    - hostname
+    - timezone
+    - mounts
+    - additional packages
+    - unprivileged users port access
+    - automatic patching
+    - ssh hardening
+    - firewall
+- `containers-local.yml` - automates Quadlet file deployment and systemd Quadlet service start/stop
+  - Used on localhost only
+  - Designed to be run as the unprivileged containers user, but can be run as any user
+- `containers-remote.yml` - same functionality as the local, except its designed to be run remotely
+  - Because `machinectl` has to be used to manage the Quadlet systemd services, you are forced to use the root user for ssh
 
 ## Tags
-- `host.yml`:
-    - `unprivileged-port` - configures host to allow unprivileged accounts to use privileged ports, defaults to `80`
-    - `cpanel-dnsonly` - changes only needed when running on a dnsonly cPanel instance, check `roles/host/tasks/cpanel-dnsonly.yml` for details
-- `containers.yml`:
+- `containers-local.yml` & `containers-remote.yml`:
     - `create` - create quadlet files
     - `remove` - remove quadlet files
     - `start` - start quadlet services
diff --git a/docs/example-inventory.yml b/docs/example-inventory.yml
new file mode 100644
index 0000000..9a24fe6
--- /dev/null
+++ b/docs/example-inventory.yml
@@ -0,0 +1,68 @@
+all:
+  hosts:
+    HOSTNAME:
+      host_patching: true
+      host_patching_reboot: "when-needed"
+
+      host_hostname: "containers-testing"
+
+      host_ssh_harden: true
+
+      host_timezone: "America/New_York"
+
+      host_firewall:
+        services:
+          - service: "http"
+            state: "enabled"
+
+          - service: "https"
+            state: "enabled"
+
+      host_packages:
+        - name: "git"
+          state: "present"
+
+        - name: "fish"
+          state: "present"
+
+        - name: "restic"
+          state: "present"
+
+      host_containers_user_shell: "/usr/bin/fish"
+
+      host_unprivileged_port_start: "80"
+
+      host_mounts:
+        - path: "/home/containers"
+          src: "/dev/disk/by-id/scsi-0Linode_Volume_containers-test"
+          fstype: "ext4"
+          opts: "defaults,noatime,nofail"
+          state: "mounted"
+
+      quadlet_proxy_root: "/home/containers/proxy/quadlet"
+      quadlet_wiki_root: "/home/containers/wiki/quadlet"
+
+      containers_quadlets:
+        - name: "proxy-app-build"
+          path: "{{ quadlet_proxy_root }}"
+          file: "proxy-app.build"
+
+        - name: "proxy-app"
+          path: "{{ quadlet_proxy_root }}"
+          file: "proxy-app.container"
+
+        - name: "wiki-pod"
+          path: "{{ quadlet_wiki_root }}"
+          file: "wiki.pod"
+
+        - name: "wiki-db"
+          path: "{{ quadlet_wiki_root }}"
+          file: "wiki-db.container"
+
+        - name: "wiki-app-build"
+          path: "{{ quadlet_wiki_root }}"
+          file: "wiki-app.build"
+
+        - name: "wiki-app"
+          path: "{{ quadlet_wiki_root }}"
+          file: "wiki-app.container"
diff --git a/host.yml b/host.yml
index af0d4a8..f859cd3 100644
--- a/host.yml
+++ b/host.yml
@@ -1,13 +1,18 @@
 - hosts: localhost
   gather_facts: false
+  vars:
+
   tasks:
-    - name: Add localhost to all group if no hosts are defined
-      ansible.builtin.add_host:
-        name: "localhost"
-        ansible_connection: "local"
+    - name: Block for localhost run
+      block:
+        - ansible.builtin.pause:
+            prompt: "Warning - no hosts were given, this will run on localhost - hit enter to continue or ctrl-c to cancel"
+
+        - name: Add localhost to all group if no hosts are defined
+          ansible.builtin.add_host:
+            name: "localhost"
+            ansible_connection: "local"
       when: groups['all'] | length == 0
-      tags:
-        - always
 
 
 - hosts: all