Define NOMAD live services under /opt

docs/operations/STACK_STANDARDS.md

@@ -1,7 +1,9 @@
 # Homelab Stack Standards
 
 ## Repository Root
-`/mnt/docker-ssd/docker/compose`
+PD live compose root: `/mnt/docker-ssd/docker/compose`
+
+NOMAD exception: standalone live deployments belong under `/opt/<service>` rather than a shared `/mnt/docker-ssd/docker/compose` tree.
 
 Remotes:
 - GitHub: `git@github.com:Paccoco/truenas-stacks.git`
@@ -19,15 +21,23 @@ Each stack contains:
 - `.env.example` — committed with placeholder values
 - optional init scripts (e.g. `initdb/`, `initdb-mariadb/`)
 
-## Host-Run Services
+## NOMAD Live Services
-If something on NOMAD is not deployed as a Docker compose stack, its live runtime belongs under `/opt/<service>`.
+On NOMAD, live service roots belong under `/opt/<service>`.
+
+This includes:
+- host-run services
+- standalone Docker Compose stacks
+- small service-local runtimes that should stay self-contained
 
 Examples:
 - `/opt/project-nomad`
 - `/opt/newt`
 - `/opt/doris-dashboard`
+- `/opt/pihole-nomad`
 
-Use the repo for source/staging, but do not run production host services from an agent workspace or random checkout under `/home/fizzlepoof/.openclaw/workspace`.
+Default rule on NOMAD: keep runtime data with the service under `/opt/<service>/data` unless a service has a documented reason to use another storage tier.
+
+Use the repo for source/staging, but do not run production services from an agent workspace or random checkout under `/home/fizzlepoof/.openclaw/workspace`.
 
 ## Deployment Order
 1. `databases/` — must be up before anything else
@@ -38,8 +48,13 @@ Use the repo for source/staging, but do not run production host services from an
 
 Validate before deploying:
 ```bash
+# PD-style shared compose root
 cd /mnt/docker-ssd/docker/compose/<stack>
 docker compose --env-file .env config
+
+# NOMAD-style service root
+cd /opt/<service>
+docker compose --env-file .env config
 ```
 
 Deploy:

docs/planning/DEPLOY_PIHOLE.md

@@ -229,7 +229,8 @@ sudo docker logs unbound-pihole-primary --tail 20
 
 N.O.M.A.D. runs Ubuntu bare metal. Deploy via Docker Compose on the host.
 
-**Appdata:** `/mnt/docker-ssd/docker/appdata/`  
+**Live service root:** `/opt/pihole-nomad`  
+**Service-local data root:** `/opt/pihole-nomad/data/`  
 **Web UI port:** `8954`
 
 ### docker-compose.yaml
@@ -244,7 +245,7 @@ services:
     network_mode: host
     restart: unless-stopped
     volumes:
-      - /mnt/docker-ssd/docker/appdata/unbound-nomad:/opt/unbound/etc/unbound/
+      - /opt/pihole-nomad/data/unbound:/opt/unbound/etc/unbound/
     healthcheck:
       test: ["CMD-SHELL", "drill @127.0.0.1 -p 5335 cloudflare.com || exit 1"]
       interval: 30s
@@ -269,7 +270,7 @@ services:
       FTLCONF_ntp_ipv6_active: "false"
       FTLCONF_ntp_sync_active: "false"
     volumes:
-      - /mnt/docker-ssd/docker/appdata/pihole-nomad/etc-pihole:/etc/pihole
+      - /opt/pihole-nomad/data/pihole/etc-pihole:/etc/pihole
     cap_add:
       - SYS_NICE
 
@@ -517,7 +518,7 @@ Enable Pangolin auth — Pi-hole admin should not be publicly accessible.
 |------|------|------|--------|
 | PD | `/mnt/tank/docker/appdata/pihole-primary` | tank | Low write frequency |
 | PD | `/mnt/tank/docker/appdata/unbound-primary` | tank | Config + root hints only |
-| N.O.M.A.D. | `/mnt/docker-ssd/docker/appdata/pihole-nomad` | Local SSD | Docker-managed local appdata |
+| N.O.M.A.D. | `/opt/pihole-nomad/data` | Local service root | Self-contained NOMAD service data |
 | RPi4 | `~/pihole/` | SD card / SSD | Dedicated Pi, no other concerns |
 
 ---

docs/servers/NOMAD.md

@@ -199,9 +199,11 @@ These are expected to be managed by Wings/Pelican rather than a local compose fi
   - Topic thumbs write back to `doris-digest/data/feedback.json`.
   - Paperless acknowledge/dismiss state writes to `/opt/doris-dashboard/data/paperless_review_state.json` on the live host.
 
-### Host-run service path rule
+### Live deployment path rule
-- Docker/compose-managed stacks live under `/mnt/docker-ssd/docker/compose`.
+- On NOMAD, live service roots belong under `/opt/<service>`.
-- Host-run services that are not compose stacks live under `/opt/<service>`.
+- That includes host-run services **and** standalone Docker Compose deployments that are not part of the core Project N.O.M.A.D. stack.
+- Keep service-local runtime data with the service under `/opt/<service>/data` unless there is a clear reason to place heavy state elsewhere.
+- Examples: `/opt/newt`, `/opt/doris-dashboard`, `/opt/pihole-nomad`.
 - Do not run production services from any agent workspace or ad-hoc checkout under `/home/fizzlepoof/.openclaw/workspace`.
 
 ### Safe to remove / how to restore

pihole/nomad/.env.example

@@ -1,6 +1,6 @@
 TZ=America/Chicago
-APPDATA_PIHOLE_ROOT=/mnt/docker-ssd/docker/appdata/pihole-nomad
+APPDATA_PIHOLE_ROOT=/opt/pihole-nomad/data/pihole
-APPDATA_UNBOUND_ROOT=/mnt/docker-ssd/docker/appdata/unbound-nomad
+APPDATA_UNBOUND_ROOT=/opt/pihole-nomad/data/unbound
 PIHOLE_WEB_PORT=8954
 NOMAD_PIHOLE_WEB_PORT=8954
 PIHOLE_PASSWORD=CHANGE_ME

pihole/nomad/README.md

@@ -1,7 +1,7 @@
 # NOMAD Pi-hole / Unbound / Keepalived Replica
 
 - **Repo stack path:** `/home/fizzlepoof/repos/truenas-stacks/pihole/nomad`
-- **Suggested live stack path:** `/mnt/docker-ssd/docker/compose/pihole-nomad`
+- **Suggested live stack path:** `/opt/pihole-nomad`
 - **Node role:** NOMAD backup / BACKUP1
 - **VIP target:** `10.5.1.53/24`
 - **LAN interface:** `enp5s0`
@@ -10,7 +10,7 @@
 Bring-up:
 
 ```bash
-cd /mnt/docker-ssd/docker/compose/pihole-nomad
+cd /opt/pihole-nomad
 cp .env.example .env
 bash bin/prepare_nomad.sh --up
 ```