160 lines
4.8 KiB
Markdown
160 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
ssh homelab "command"
|
|
```
|
|
|
|
Useful commands:
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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:
|
|
```bash
|
|
curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks/[name]/compose?env=1"
|
|
```
|
|
|
|
### Step 4 — Check for new/removed containers
|
|
```bash
|
|
curl -s "https://dockhand.bunny-wyvern.ts.net/api/containers?env=1"
|
|
```
|
|
|
|
### Step 5 — Check volumes and networks for orphans
|
|
```bash
|
|
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
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
gpg -d credentials.gpg
|
|
```
|
|
|
|
Requires GPG — available natively on Linux/macOS, or via [GPG4Win](https://gpg4win.org) on Windows. Works fully offline.
|