OneByJorah · OneByJorah · Jul 5, 2026
@@ -282,7 +282,7 @@ async def apply_setup(request: Request):
             (REPO_ROOT / "setup-complete.json").write_text(json.dumps(payload, indent=2))
 
             if mode in ("cloudflare", "all") and cf_host and cf_tunnel:
-                cf_content = f"""tunnel: {cf_tunnel}\ncredentials-file: /home/j1admin/.cloudflared/{cf_tunnel}.json\ningress:\n  - hostname: {cf_host}\n    path: /honcho/*\n    service: http://100.66.142.21:8000\n  - hostname: {cf_host}\n    path: /qdrant/*\n    service: http://100.66.142.21:6333\n  - hostname: {cf_host}\n    path: /search/*\n    service: http://100.66.142.21:8080\n  - hostname: {cf_host}\n    path: /obsidian/*\n    service: http://100.66.142.21:8083\n  - hostname: {cf_host}\n    path: /costforge/*\n    service: http://100.66.142.21:8090\n  - hostname: {cf_host}\n    path: /noc/*\n    service: http://100.66.142.21:9500\n  - service: http_status:404\n"""
+                cf_content = f"""tunnel: {cf_tunnel}\ncredentials-file: /home/j1admin/.cloudflared/{cf_tunnel}.json\ningress:\n  - hostname: {cf_host}\n    path: /honcho/*\n    service: http://<tailscale-ip>:8000\n  - hostname: {cf_host}\n    path: /qdrant/*\n    service: http://<tailscale-ip>:6333\n  - hostname: {cf_host}\n    path: /search/*\n    service: http://<tailscale-ip>:8080\n  - hostname: {cf_host}\n    path: /obsidian/*\n    service: http://<tailscale-ip>:8083\n  - hostname: {cf_host}\n    path: /costforge/*\n    service: http://<tailscale-ip>:8090\n  - hostname: {cf_host}\n    path: /noc/*\n    service: http://<tailscale-ip>:9500\n  - service: http_status:404\n"""
                 CF_DIR.mkdir(parents=True, exist_ok=True)
                 (CF_DIR / "config.yml").write_text(cf_content)
 

@@ -38,22 +38,22 @@ credentials-file: /home/j1admin/.cloudflared/${cf_tunnel}.json
 ingress:
   - hostname: ${cf_host}
     path: /honcho/*
-    service: http://100.66.142.21:8000
+    service: http://<tailscale-ip>:8000
   - hostname: ${cf_host}
     path: /qdrant/*
-    service: http://100.66.142.21:6333
+    service: http://<tailscale-ip>:6333
   - hostname: ${cf_host}
     path: /search/*
-    service: http://100.66.142.21:8080
+    service: http://<tailscale-ip>:8080
   - hostname: ${cf_host}
     path: /obsidian/*
-    service: http://100.66.142.21:8083
+    service: http://<tailscale-ip>:8083
   - hostname: ${cf_host}
     path: /costforge/*
-    service: http://100.66.142.21:8090
+    service: http://<tailscale-ip>:8090
   - hostname: ${cf_host}
     path: /noc/*
-    service: http://100.66.142.21:9500
+    service: http://<tailscale-ip>:9500
   - service: http_status:404
 EOF
     echo "Wrote Cloudflare tunnel config to $cf_config"

@@ -59,22 +59,22 @@ credentials-file: /home/j1admin/.cloudflared/${CF_TUNNEL}.json
 ingress:
   - hostname: ${CF_HOSTNAME}
     path: /honcho/*
-    service: http://100.66.142.21:8000
+    service: http://<tailscale-ip>:8000
   - hostname: ${CF_HOSTNAME}
     path: /qdrant/*
-    service: http://100.66.142.21:6333
+    service: http://<tailscale-ip>:6333
   - hostname: ${CF_HOSTNAME}
     path: /search/*
-    service: http://100.66.142.21:8080
+    service: http://<tailscale-ip>:8080
   - hostname: ${CF_HOSTNAME}
     path: /obsidian/*
-    service: http://100.66.142.21:8083
+    service: http://<tailscale-ip>:8083
   - hostname: ${CF_HOSTNAME}
     path: /costforge/*
-    service: http://100.66.142.21:8090
+    service: http://<tailscale-ip>:8090
   - hostname: ${CF_HOSTNAME}
     path: /noc/*
-    service: http://100.66.142.21:9500
+    service: http://<tailscale-ip>:9500
   - service: http_status:404
 EOF
   sudo systemctl enable --now cloudflared || true

@@ -0,0 +1,51 @@
+---
+name: arah-health-validation
+description: Validates arah services with health checks. Use after deploy, restart, config change, or tunnel update. Use when verifying mode switches or troubleshooting.
+---
+
+# arah Health Validation
+
+## Overview
+Every change to arah must be followed by validation. Use `scripts/healthcheck.sh` and curl checks for each service.
+
+## When to Use
+- After `docker compose up -d`
+- After `.env` or profile changes
+- After tunnel config changes
+- When NOC dashboard shows services down
+
+## Process
+
+1. **Run the project healthcheck**
+   ```bash
+   bash scripts/healthcheck.sh
+   ```
+
+2. **Validate by access mode**
+   - `local`:
+     - `curl -sf http://localhost:8000/healthz` (Honcho)
+     - `curl -sf http://localhost:6333/readyz` (Qdrant)
+     - `curl -sf http://localhost:8080/search?q=healthcheck&format=json` (SearXNG)
+     - `curl -sf http://localhost:8083/` (Obsidian)
+   - `tailscale`:
+     - `curl -sf http://<tailscale-ip>:<port>/...`
+   - `cloudflare` / `all`:
+     - `curl -k https://arah.<domain>/honcho/healthz`
+     - `curl -k https://arah.<domain>/qdrant/readyz`
+     - verify tunnel: `systemctl status cloudflared`
+
+3. **NOC dashboard status API**
+   ```bash
+   curl -sf http://localhost:9500/api/status | jq '.services'
+   ```
+
+4. **Failure checklist**
+   - Service image pull failure → disk space / network
+   - Port conflict → `ss -tlnp | grep <port>`
+   - Tunnel 404 → path mismatch in `~/.cloudflared/config.yml`
+   - DB connection failure → PostgreSQL health / credentials
+
+## Success Criteria
+- `scripts/healthcheck.sh` exits 0
+- All `http` services return `< 500`
+- NOC dashboard shows green or graceful warning
@@ -0,0 +1,52 @@
+---
+name: arah-launch
+description: Launches arah after setup. Use when the stack is configured and ready to start. Use after setup wizard or manual `.env` edits.
+---
+
+# arah Launch
+
+## Overview
+Bring the stack online in the correct order, verify access from the intended path, and confirm the dashboard is reachable.
+
+## When to Use
+- After applying a profile
+- After tunnel DNS changes
+- After adding new services
+- First deployment to a host
+
+## Process
+
+1. **Preflight**
+   - Confirm `.env` exists and `STACK_MODE` is set
+   - Confirm Docker is running
+   - Confirm ports are free: `ss -tlnp | grep -E '8000|6333|8080|8083|8090|9500'`
+
+2. **Launch**
+   - Local/tailscale:
+     ```bash
+     sudo docker compose up -d
+     ```
+   - Cloudflare/all:
+     ```bash
+     sudo systemctl enable --now cloudflared || sudo systemctl restart cloudflared
+     sudo docker compose up -d
+     ```
+
+3. **Verify access**
+   - Local: `http://localhost:<port>`
+   - Tailscale: `http://<tailscale-ip>:<port>`
+   - Cloudflare: `https://arah.<domain>/<path>`
+
+4. **Confirm dashboard**
+   - Open NOC UI at the appropriate base URL
+   - Confirm services show green
+
+## Rollback
+```bash
+sudo docker compose down
+```
+
+## Boundaries
+- Always run `scripts/healthcheck.sh` after launch
+- Ask before publishing tunnel DNS to users
+- Never launch with `.env` missing or placeholder values