diff --git a/21-Server Reference/AI-UPDATE-INSTRUCTIONS.md b/21-Server Reference/AI-UPDATE-INSTRUCTIONS.md new file mode 100644 index 0000000..265cc4e --- /dev/null +++ b/21-Server Reference/AI-UPDATE-INSTRUCTIONS.md @@ -0,0 +1,159 @@ +# 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. diff --git a/21-Server Reference/README.md b/21-Server Reference/README.md index e42402a..8b41b40 100644 --- a/21-Server Reference/README.md +++ b/21-Server Reference/README.md @@ -31,26 +31,14 @@ The sidecar shares the main container's network namespace, so Tailscale sees the ## Credentials & Tokens -> These are stored here for admin reference. Do not share. +All credentials are stored in an encrypted file: `credentials.gpg` (AES256, GPG symmetric). -### Mealie -| Key | Value | -|---|---| -| Auth Token | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb25nX3Rva2VuIjp0cnVlLCJpZCI6IjNkZjZkZmM0LTkyZDgtNDIyNy1iMjBjLTA4ZjA2Njc2MGcă0IsIm5hbWUiOiJMTE0gIiwiaW50ZWdyYXRpb25faWQiOiJnZW5lcmljIiwiZXhwIjoxOTE5OTEwNDUwfQ.Ts5XbrF6Nr-0gvhKkt_01OPeAEoWQe_ndn0hGTtPOQc` | +To decrypt: +```bash +gpg -d "credentials.gpg" +``` -### Discord Bots -| Bot | Token | -|---|---| -| Isomer | `NjY0MjMyOTYxMjM4ODkyNTc0.XhUFJg.ivnkBPtnEPGGcAwaXP50rOIPZsI` | -| Star-15 | `ODQ2MTUxMDMxMjA1MDAzMjc0.GYFbRW.JeFITOZbBH_lqCuF-bS7edC0P30H6uqFKwz7is` | - -### AI -| Service | Key | -|---|---| -| Gemini API | `AIzaSyD0uj33T_SH4Fvw2sWWW9akXF6ej9sqhlI` | - -### Server Passwords -Shared password used across most Docker services (DB passwords, NextAuth secrets, etc.): see compose files at `/home/artanis/DockerFiles/` on the homelab. +Requires GPG — available on Linux/macOS natively, or [GPG4Win](https://gpg4win.org) on Windows. Works fully offline. --- @@ -59,7 +47,8 @@ Shared password used across most Docker services (DB passwords, NextAuth secrets ``` 21-Server Reference/ ├── README.md ← You are here -├── Server Info.md ← Legacy notes (superseded by this file) +├── AI-UPDATE-INSTRUCTIONS.md ← How to pull live data and update these docs +├── credentials.gpg ← Encrypted credentials (GPG AES256) ├── homelab/ │ ├── README.md — Homelab overview & stack index │ ├── hardware.md — CPU, RAM, storage diff --git a/21-Server Reference/Server Info.md b/21-Server Reference/Server Info.md deleted file mode 100644 index 9cb76f8..0000000 --- a/21-Server Reference/Server Info.md +++ /dev/null @@ -1,27 +0,0 @@ -# Docker Hosting - -## Tailscale Sidecar Setup -The process is dead simple. -- create a service, and the tailscale sidecar -- On the side car, put ``` - network_mode: "service:[[service name]]"``` -- Connect to the sidecar via ssh or via the admin console on tailscale and run ```tailscale funnel --bg [[port]]``` - -# Mealie -## Auth -Auth Token: -eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb25nX3Rva2VuIjp0cnVlLCJpZCI6IjNkZjZkZmM0LTkyZDgtNDIyNy1iMjBjLTA4ZjA2Njc2MGcă0IsIm5hbWUiOiJMTE0gIiwiaW50ZWdyYXRpb25faWQiOiJnZW5lcmljIiwiZXhwIjoxOTE5OTEwNDUwfQ.Ts5XbrF6Nr-0gvhKkt_01OPeAEoWQe_ndn0hGTtPOQc - -# Gitea - -# Discord -## Isomer -Bot Token: NjY0MjMyOTYxMjM4ODkyNTc0.XhUFJg.ivnkBPtnEPGGcAwaXP50rOIPZsI - -## Star-15 -Bot Token: ODQ2MTUxMDMxMjA1MDAzMjc0.GYFbRW.JeFITOZbBH_lqCuF-bS7edC0P30H6uqFKwz7is - -# AI - -## Gemini -API Key: AIzaSyD0uj33T_SH4Fvw2sWWW9akXF6ej9sqhlI \ No newline at end of file diff --git a/21-Server Reference/SpecSheet.md b/21-Server Reference/SpecSheet.md deleted file mode 100644 index 11c5420..0000000 --- a/21-Server Reference/SpecSheet.md +++ /dev/null @@ -1,9 +0,0 @@ -# Objective -Create a living documentation of a server, including configuration, docker containers, changes, and any other relevant information. The end goal should be if a sever admin who had never touched this server before were to read this documentation, they would be an expert and understand everything that they need to about the server. - -It does not need to live in a single file, and should be divided between different folders and files. - -Whenever any changes need to be made, the relevant parts of this documentation need to be read, compared to current status, and updated accordingly - -## Side Objective -Do the same thing for a much smaller server, running on a raspi that supports the larger server in various ways. \ No newline at end of file