From 546507e71c24fc683b3f1c23c8655b58487e81bd Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Fri, 15 May 2026 15:49:15 +0000 Subject: [PATCH] Define NOMAD live services under /opt --- docs/operations/STACK_STANDARDS.md | 23 +++++++++++++++++++---- docs/planning/DEPLOY_PIHOLE.md | 9 +++++---- docs/servers/NOMAD.md | 8 +++++--- pihole/nomad/.env.example | 4 ++-- pihole/nomad/README.md | 4 ++-- 5 files changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/operations/STACK_STANDARDS.md b/docs/operations/STACK_STANDARDS.md index 15bfc76..7ff38ae 100644 --- a/docs/operations/STACK_STANDARDS.md +++ b/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/` 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 -If something on NOMAD is not deployed as a Docker compose stack, its live runtime belongs under `/opt/`. +## NOMAD Live Services +On NOMAD, live service roots belong under `/opt/`. + +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//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/ docker compose --env-file .env config + +# NOMAD-style service root +cd /opt/ +docker compose --env-file .env config ``` Deploy: diff --git a/docs/planning/DEPLOY_PIHOLE.md b/docs/planning/DEPLOY_PIHOLE.md index 662731d..ca62c21 100644 --- a/docs/planning/DEPLOY_PIHOLE.md +++ b/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 | --- diff --git a/docs/servers/NOMAD.md b/docs/servers/NOMAD.md index a579c65..e75d6fd 100644 --- a/docs/servers/NOMAD.md +++ b/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 -- Docker/compose-managed stacks live under `/mnt/docker-ssd/docker/compose`. -- Host-run services that are not compose stacks live under `/opt/`. +### Live deployment path rule +- On NOMAD, live service roots belong under `/opt/`. +- 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//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 diff --git a/pihole/nomad/.env.example b/pihole/nomad/.env.example index 11d216a..139476b 100644 --- a/pihole/nomad/.env.example +++ b/pihole/nomad/.env.example @@ -1,6 +1,6 @@ TZ=America/Chicago -APPDATA_PIHOLE_ROOT=/mnt/docker-ssd/docker/appdata/pihole-nomad -APPDATA_UNBOUND_ROOT=/mnt/docker-ssd/docker/appdata/unbound-nomad +APPDATA_PIHOLE_ROOT=/opt/pihole-nomad/data/pihole +APPDATA_UNBOUND_ROOT=/opt/pihole-nomad/data/unbound PIHOLE_WEB_PORT=8954 NOMAD_PIHOLE_WEB_PORT=8954 PIHOLE_PASSWORD=CHANGE_ME diff --git a/pihole/nomad/README.md b/pihole/nomad/README.md index e92ced0..d4ea5c8 100644 --- a/pihole/nomad/README.md +++ b/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 ```