Inanis_Vault/21-Server Reference/AI-UPDATE-INSTRUCTIONS.md

AI Update Instructions

This document explains how to pull live data from the servers and update this documentation. Follow these steps whenever asked to update or check for changes.

---

Overview

There are two servers:

• Homelab (primary) — documented in homelab/
• Pihole / Raspberry Pi (secondary) — documented in pihole/

All Docker infrastructure is managed via Dockhand, a web-based Docker management UI accessible at:

https://dockhand.bunny-wyvern.ts.net

Dockhand exposes a REST API that should be the first method for gathering data. SSH to homelab is the fallback for host-level information Docker doesn't expose.

---

Dockhand API

No authentication header is required. All endpoints are prefixed with /api/.

Environments

Dockhand manages two environments selected via the ?env= query parameter:

env	Server
?env=1	Homelab (primary server)
?env=2	Pihole / Raspberry Pi

Core Endpoints

# All containers (with status, ports, mounts, networks)
curl -s "https://dockhand.bunny-wyvern.ts.net/api/containers?env=1"

# All stacks (with container details and status)
curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=1"

# Compose file for a specific stack
curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks/[stack-name]/compose?env=1"

# All volumes
curl -s "https://dockhand.bunny-wyvern.ts.net/api/volumes?env=1"

# All networks
curl -s "https://dockhand.bunny-wyvern.ts.net/api/networks?env=1"

# Both environment configs (connection status, IPs, settings)
curl -s "https://dockhand.bunny-wyvern.ts.net/api/environments"

Replace ?env=1 with ?env=2 for the Pihole.

Known Stack Names

Homelab (env=1): dockhand, minecraft_server, mealie, linkwarden, gitea, matrix, homepage, n8n, calibre, gluetun-qbittorent, open-project, docker (melodix)

Pihole (env=2): home_assistant, ts_kh_bridge, portainer_agent

Note: ts_kh_bridge and portainer_agent on the Pihole return needsFileLocation: true from the compose endpoint — their compose files are not registered in Dockhand. Use container labels for path info.

API Gotchas

• GET /api/stacks/[name] returns 405 — only DELETE is allowed on that route. Use /api/stacks/[name]/compose?env=1 to inspect a stack.
• Long-running POST operations (start, stop, deploy) return { "jobId": "..." } by default. Add -H "Accept: application/json" to get a synchronous response instead.

---

SSH Fallback

For host-level information not available through Docker, SSH directly:

ssh homelab "command"

Useful commands:

# OS and kernel
uname -a && cat /etc/os-release

# CPU
lscpu | grep -E 'Model name|CPU\(s\)|Thread|Core|MHz'

# Memory and swap
free -h

# Disk layout
df -h && lsblk

# Network interfaces and IPs
ip addr show

# Listening ports
ss -tlnp | grep LISTEN

---

Update Checklist

When asked to update the documentation, follow this process:

Step 1 — Read before comparing

Always read the relevant existing doc files before pulling live data. The goal is to diff what's documented against what's actually running.

Step 2 — Check stacks

curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=1"
curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=2"

Look for:

• New stacks not yet documented
• Stacks that have been removed
• Status changes (e.g. a stack that was running is now stopped, or vice versa)

Step 3 — Check compose files for changed stacks

For any stack that looks different, pull its compose file and compare against the compose block in its .md file:

curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks/[name]/compose?env=1"

Step 4 — Check for new/removed containers

curl -s "https://dockhand.bunny-wyvern.ts.net/api/containers?env=1"

Step 5 — Check volumes and networks for orphans

curl -s "https://dockhand.bunny-wyvern.ts.net/api/volumes?env=1"
curl -s "https://dockhand.bunny-wyvern.ts.net/api/networks?env=1"

Flag any volumes or networks not attached to a running container.

Step 6 — Check Pihole connection status

curl -s "https://dockhand.bunny-wyvern.ts.net/api/environments"

Check hawserLastSeen for env=2. If null or significantly stale, the Hawser agent on the Pi may be down.

Step 7 — Update the docs

Update only the files relevant to what changed. Always update the compose block, status tables, port lists, and any notes that are affected. Do not rewrite sections that haven't changed.

---

Credentials

Credentials are stored in credentials.gpg (AES256 GPG symmetric encryption) in the root of this documentation directory. To decrypt:

gpg -d credentials.gpg

Requires GPG — available natively on Linux/macOS, or via GPG4Win on Windows. Works fully offline.