Feature/prometheus npm quadlet (#15)

* Stage Prometheus NPM Quadlet with backup-safe cutover

* Complete Prometheus NPM Quadlet cutover

ansible/inventory/group_vars/server.yml

@@ -6,6 +6,8 @@ effective_username: "{{ server_username }}"
 effective_user_group: "{{ server_user_group }}"
 effective_user_home: "{{ server_user_home }}"
 server_container_stack_dir: /opt/docker/server
+server_npm_quadlet_stage: false
+server_npm_quadlet_cutover: false
 ai_agents: {}
 vim_plugins_enabled: false
 
@@ -100,8 +102,11 @@ server_backup_export_paths: >-
   {{ ['opt/npm/data', 'opt/npm/letsencrypt']
      + ([] if server_gitea_on_atlas | bool else ['opt/gitea/data', 'home/git/.ssh'])
      + ['opt/docker/server/docker-compose.yml',
-        'etc/systemd/system/podman-compose-server.service',
-        'etc/ssh/sshd_config', 'etc/ssh/sshd_config.d',
+        'etc/systemd/system/podman-compose-server.service']
+     + (['etc/containers/systemd/prometheus-npm.container',
+         'etc/containers/systemd/server-web.network']
+        if server_npm_quadlet_stage | bool else [])
+     + ['etc/ssh/sshd_config', 'etc/ssh/sshd_config.d',
         'etc/firewalld', 'etc/wireguard/wg0.conf'] }}
 server_backup_export_excludes: >-
   {{ ['opt/npm/data/logs']

ansible/inventory/host_vars/prometheus.yml

@@ -6,6 +6,10 @@ ansible_port: 22
 ansible_ssh_private_key_file: /home/fscotto/.ssh/id_ed25519
 
 server_username: rocky
+server_npm_quadlet_stage: true
+server_npm_quadlet_image: docker.io/jc21/nginx-proxy-manager@sha256:52b2c59994f3d36acfcf70a1626f29734df0ed8c71bacc0269f78b6f939858bb
+# The stopped-source export and live Quadlet cutover passed on 2026-10-03.
+server_npm_quadlet_cutover: true
 server_backup_export_enabled: true
 server_backup_export_start_timer: true
 # Install the final-copy helper only; it is never run by a normal playbook invocation.

ansible/roles/profile_server/tasks/backup_export_job.yml

@@ -44,7 +44,7 @@
   when: server_backup_export_enabled | bool
 
 - name: Install Prometheus backup export helper
-  tags: [services, backup, prometheus_backup, gitea_cutover]
+  tags: [services, backup, prometheus_backup, gitea_cutover, npm_quadlet_backup]
   ansible.builtin.template:
     src: prometheus-backup-export.sh.j2
     dest: /usr/local/sbin/prometheus-backup-export

ansible/roles/profile_server/tasks/main.yml

@@ -53,6 +53,9 @@
   tags: [services, podman]
   ansible.builtin.include_tasks: podman-compose.yml
 
+- name: Import staged NPM Quadlet tasks
+  ansible.builtin.import_tasks: npm_quadlet.yml
+
 - name: Import Prometheus backup export identity tasks
   ansible.builtin.import_tasks: backup_export_identity.yml
 

ansible/roles/profile_server/tasks/npm_quadlet.yml

@@ -0,0 +1,71 @@
+---
+- name: Require staged NPM Quadlet for an active cutover
+  tags: [services, npm_quadlet]
+  ansible.builtin.assert:
+    that:
+      - not server_npm_quadlet_cutover | bool or server_npm_quadlet_stage | bool
+    fail_msg: The NPM Quadlet cutover requires the staged container and network.
+
+- name: Validate staged NPM Quadlet inputs
+  tags: [services, npm_quadlet]
+  ansible.builtin.assert:
+    that:
+      - server_npm_quadlet_image is defined
+      - server_npm_quadlet_image is match('^docker\.io/jc21/nginx-proxy-manager@sha256:[a-f0-9]{64}$')
+      - server_gitea_on_atlas | bool
+    fail_msg: Stage the exact running NPM image only after Gitea has left Compose.
+  when: server_npm_quadlet_stage | bool
+
+- name: Ensure rootful Quadlet directory exists for NPM
+  tags: [services, npm_quadlet]
+  ansible.builtin.file:
+    path: /etc/containers/systemd
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  when: server_npm_quadlet_stage | bool
+
+- name: Render staged NPM container and network Quadlets
+  tags: [services, npm_quadlet]
+  ansible.builtin.template:
+    src: "{{ item }}.j2"
+    dest: "/etc/containers/systemd/{{ item }}"
+    owner: root
+    group: root
+    mode: "0644"
+  loop:
+    - prometheus-npm.container
+    - server-web.network
+  loop_control:
+    label: "{{ item }}"
+  register: server_npm_quadlet_units
+  when: server_npm_quadlet_stage | bool
+
+- name: Reload systemd after staging NPM Quadlets
+  tags: [services, npm_quadlet]
+  ansible.builtin.systemd:
+    daemon_reload: true
+  when:
+    - server_npm_quadlet_stage | bool
+    - server_npm_quadlet_units is changed
+    - not ansible_check_mode
+
+- name: Verify the staged NPM Quadlet was generated
+  tags: [services, npm_quadlet]
+  ansible.builtin.command:
+    argv: [systemctl, show, prometheus-npm.service, --property=LoadState, --value]
+  register: server_npm_quadlet_load_state
+  changed_when: false
+  when:
+    - server_npm_quadlet_stage | bool
+    - not ansible_check_mode
+
+- name: Reject an invalid staged NPM Quadlet
+  tags: [services, npm_quadlet]
+  ansible.builtin.assert:
+    that: server_npm_quadlet_load_state.stdout == 'loaded'
+    fail_msg: Quadlet generator did not produce prometheus-npm.service.
+  when:
+    - server_npm_quadlet_stage | bool
+    - not ansible_check_mode

ansible/roles/profile_server/templates/prometheus-backup-export.sh.j2

@@ -4,7 +4,20 @@ umask 077
 
 export_root={{ server_backup_export_root | quote }}
 versions="$export_root/versions"
-stack_unit=podman-compose-server.service
+stack_unit=''
+compose_active=false
+quadlet_active=false
+systemctl is-active --quiet podman-compose-server.service && compose_active=true
+systemctl is-active --quiet prometheus-npm.service && quadlet_active=true
+if [[ "$compose_active" == "$quadlet_active" ]]; then
+  echo 'Expected exactly one active NPM service (Compose or Quadlet)' >&2
+  exit 1
+fi
+if "$quadlet_active"; then
+  stack_unit=prometheus-npm.service
+else
+  stack_unit=podman-compose-server.service
+fi
 stamp=$(date -u +%Y%m%dT%H%M%SZ)
 stage=''
 stack_stopped=false
@@ -33,7 +46,7 @@ trap 'exit 130' INT
 trap 'exit 143' TERM
 
 systemctl is-active --quiet "$stack_unit" || {
-  echo 'The managed Compose stack must be active before preparing a backup' >&2
+  echo "The managed NPM unit $stack_unit must be active before preparing a backup" >&2
   exit 1
 }
 
@@ -70,6 +83,15 @@ for container in nginx-proxy-manager{% if not server_gitea_on_atlas | bool %} gi
   done
   "$running" || { echo "Container did not restart: $container" >&2; exit 1; }
 done
+ready=false
+for _ in {1..60}; do
+  if curl -fsS --connect-timeout 2 --max-time 3 -o /dev/null http://127.0.0.1:81/; then
+    ready=true
+    break
+  fi
+  sleep 2
+done
+"$ready" || { echo 'NPM administration did not become ready after backup' >&2; exit 1; }
 stack_stopped=false
 
 tar -tf "$stage/payload.tar" >/dev/null

ansible/roles/profile_server/templates/prometheus-npm.container.j2

@@ -0,0 +1,26 @@
+[Unit]
+Description=Nginx Proxy Manager on Prometheus
+RequiresMountsFor=/opt/npm/data /opt/npm/letsencrypt
+
+[Container]
+Image={{ server_npm_quadlet_image }}
+ContainerName=nginx-proxy-manager
+Network=server-web.network
+NetworkAlias=nginx-proxy-manager
+AddHost=host.containers.internal:host-gateway
+PublishPort=80:80
+PublishPort=443:443
+PublishPort=127.0.0.1:81:81
+Volume=/opt/npm/data:/data
+Volume=/opt/npm/letsencrypt:/etc/letsencrypt
+Pull=missing
+
+[Service]
+Restart=always
+TimeoutStartSec=180
+TimeoutStopSec=120
+
+{% if server_npm_quadlet_cutover | bool %}
+[Install]
+WantedBy=multi-user.target
+{% endif %}

ansible/roles/profile_server/templates/server-web.network.j2

@@ -0,0 +1,5 @@
+[Network]
+NetworkName=server_web
+Driver=bridge
+Subnet=10.89.0.0/24
+Gateway=10.89.0.1

ansible/templates/server/docker-compose.yml.j2

@@ -4,7 +4,7 @@ name: server
 
 services:
   nginx-proxy-manager:
-    image: docker.io/jc21/nginx-proxy-manager:latest
+    image: {{ server_npm_quadlet_image if server_npm_quadlet_stage | bool else 'docker.io/jc21/nginx-proxy-manager:latest' }}
     container_name: nginx-proxy-manager
     restart: unless-stopped
     ports: