doc: lint & enhancements

README.md

@@ -6,6 +6,33 @@ This project is designed for personal/familial scale maintenance, if you find th
 
 This is a good playground to learn and I encourage you to adapt these roles to your needs. While they might not be production-ready for all environments, I'm open to adapting them for [Ansible Galaxy](<(https://galaxy.ansible.com)>) if there's community interest!
 
+## Architecture Overview
+
+**Platform Support:** Arch Linux, Debian/Ubuntu
+
+**Core Design:**
+
+- A unique system administrator (`{{ ansible_user }}`)
+- Security hardened sshd
+- Shared services pattern: Single PostgreSQL and Valkey (Redis) instances serve all services
+- Rootless Podman: Containers run as `{{ ansible_user }}` (daemonless, `sudo podman ps` shows nothing)
+- User systemd services: `systemctl --user status <service>` with lingering enabled
+- Nginx reverse proxy for web services
+
+**Available Services:**
+
+| Service     | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| dns         | Unbound caching DNS + Pi-hole ad blocking + VPN resolver |
+| nfs         | Network file system server                               |
+| zfs         | ZFS installation and management                          |
+| uptime-kuma | Uptime monitoring                                        |
+| ntfy        | Notification server                                      |
+| gitea       | Git server                                               |
+| immich      | Photo management                                         |
+| static-web  | Static website hosting                                   |
+| vpn         | WireGuard server                                         |
+
 ## Requirements
 
 Base tools:
@@ -36,7 +63,7 @@ ansible-playbook -i inventory/hosts.yml playbook.yml \
 --ask-become-pass
 ```
 
-You can also unlock your key system wide to simplify your calls:
+You can also call you ssh agent to unlock your key prior to simplify your calls:
 
 ```sh
 ssh-add ~/.ssh/my_key
@@ -45,7 +72,7 @@ ansible-playbook -i inventory/hosts.yml playbook.yml \
 --ask-become-pass
 ```
 
-## Target devices configuration
+## Target configuration
 
 Requirements:
 

roles/ntp-chrony/README.md

@@ -20,10 +20,10 @@ Sync time from public NTP pools, don't serve time to others:
 # host_vars/example.yml
 ntp_timezone: "Europe/Paris"
 ntp_pools:
-  - "0.fr.pool.ntp.org"
+    - "0.fr.pool.ntp.org"
-  - "1.fr.pool.ntp.org"
+    - "1.fr.pool.ntp.org"
-  - "2.fr.pool.ntp.org"
+    - "2.fr.pool.ntp.org"
-  - "3.fr.pool.ntp.org"
+    - "3.fr.pool.ntp.org"
 ```
 
 ### Server mode
@@ -35,20 +35,20 @@ Serve time to local network:
 ntp_timezone: "UTC"
 ntp_server_enabled: true
 ntp_allowed_networks:
-  - 192.168.1.0/24  # Configures both chrony and firewall
+    - 192.168.1.0/24 # Configures both chrony and firewall
-  - 192.168.27.0/27
+    - 192.168.27.0/27
 ```
 
 ### Client syncing from local server
 
 ```yaml
 # host_vars/client.yml
-ntp_pools: []  # Don't use public pools
+ntp_pools: [] # Don't use public pools
 ntp_servers:
-  - server: ntp.local.lan
+    - server: ntp.local.lan
-    options: iburst prefer
+      options: iburst prefer
-  - server: 192.168.1.1
+    - server: 192.168.1.1
-    options: iburst
+      options: iburst
 ```
 
 ## Logging

roles/static-web/README.md

@@ -2,20 +2,6 @@
 
 Deploy static websites from Git repositories with Nginx.
 
-## Features
-
-- Clone static sites from Git repositories
-- Automatic Nginx vhost configuration
-- HTTPS enabled by default with Let's Encrypt
-- Support for build commands (npm, hugo, jekyll, etc.)
-- Subdirectory serving (for built assets)
-- Static file caching
-- Security headers (including HSTS for HTTPS)
-
-## Dependencies
-
-- nginx role (automatically included via meta/main.yml)
-
 ## Variables
 
 See [defaults/main.yml](defaults/main.yml)
@@ -24,82 +10,17 @@ See [defaults/main.yml](defaults/main.yml)
 
 ```yaml
 static_web_sites:
-  "portfolio.example.fr":
+    "portfolio.example.fr":
-    git_repo: "https://github.com/example/portfolio.git"
+        git_repo: "https://github.com/example/portfolio.git"
-    git_branch: "main"  # Optional, defaults to main
+        git_branch: "main" # Optional, defaults to main
-    git_depth: 1  # Optional, shallow clone
+        git_depth: 1 # Optional, shallow clone
-    build_command: "npm install && npm run build"  # Optional
+        build_command: "npm install && npm run build" # Optional
-    root_dir: "dist"  # Optional, serve subdirectory
+        root_dir: "dist" # Optional, serve subdirectory
-    ssl_enabled: true  # Optional, defaults to true (HTTPS)
+        ssl_enabled: true # Optional, defaults to true (HTTPS)
 
-  "blog.example.com":
+    "blog.example.com":
-    git_repo: "https://github.com/example/blog.git"
+        git_repo: "https://github.com/example/blog.git"
-    # ssl_enabled defaults to true, set to false for HTTP only
+        # ssl_enabled defaults to true, set to false for HTTP only
-```
-
-## Usage
-
-**Inventory (host_vars or group_vars):**
-
-```yaml
-static_web_sites:
-  "portfolio.example.fr":
-    git_repo: "https://github.com/username/portfolio.git"
-  
-  "docs.example.com":
-    git_repo: "https://github.com/company/documentation.git"
-    git_branch: "gh-pages"
-    root_dir: "_site"
-```
-
-**Playbook:**
-
-```yaml
-- hosts: webservers
-  roles:
-    - static-web
-```
-
-## File Structure
-
-Sites are deployed to `/var/www/static/<hostname>/`
-
-Example:
-```
-/var/www/static/
-├── portfolio.example.fr/
-│   └── index.html
-└── blog.example.com/
-    ├── _site/          # Built assets (if root_dir specified)
-    └── ...
-```
-
-## Advanced Examples
-
-**Hugo site:**
-```yaml
-static_web_sites:
-  "blog.example.com":
-    git_repo: "https://github.com/example/hugo-blog.git"
-    build_command: "hugo --minify"
-    root_dir: "public"
-```
-
-**React app:**
-```yaml
-static_web_sites:
-  "app.example.com":
-    git_repo: "https://github.com/example/react-app.git"
-    build_command: "npm ci && npm run build"
-    root_dir: "build"
-```
-
-## Updating Sites
-
-Re-run the playbook to pull latest changes:
-
-```bash
-ansible-playbook -i inventory playbook.yml --tags static-web
 ```
 
 ## Notes

roles/zfs/tasks/pools.yml

@@ -17,7 +17,8 @@
   when: zfs_pools is defined
 
 - name: Creating basic zpool(s)
-  ansible.builtin.command: "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
+  ansible.builtin.command:
+    "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
     item.devices|join (' ') }}"
   with_items: "{{ zfs_pools }}"
   when:
@@ -28,7 +29,8 @@
     - item.devices[0] not in zpool_devices.stdout
 
 - name: Creating mirror/zraid zpool(s)
-  ansible.builtin.command: "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
+  ansible.builtin.command:
+    "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
     item.type }} {{ item.devices|join (' ') }}"
   with_items: "{{ zfs_pools }}"
   when:

roles/zsh/tasks/plugins.yml

@@ -24,9 +24,18 @@
     update: true
     version: master
   loop:
-    - { repo: https://github.com/zsh-users/zsh-syntax-highlighting.git, dest: "{{ zsh_plugins_path }}/zsh-syntax-highlighting" }
+    - {
-    - { repo: https://github.com/zsh-users/zsh-autosuggestions.git, dest: "{{ zsh_plugins_path }}/zsh-autosuggestions" }
+        repo: https://github.com/zsh-users/zsh-syntax-highlighting.git,
-    - { repo: https://github.com/romkatv/powerlevel10k.git, dest: "{{ zsh_plugins_path }}/powerlevel10k" }
+        dest: "{{ zsh_plugins_path }}/zsh-syntax-highlighting",
+      }
+    - {
+        repo: https://github.com/zsh-users/zsh-autosuggestions.git,
+        dest: "{{ zsh_plugins_path }}/zsh-autosuggestions",
+      }
+    - {
+        repo: https://github.com/romkatv/powerlevel10k.git,
+        dest: "{{ zsh_plugins_path }}/powerlevel10k",
+      }
 
 - name: Assert plugins are available for any user
   ansible.builtin.file: