Spendlik/Claude_Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix stale DNS/DDNS checklist (was still A-record based) and add Pre-Flight Verification protocol to prevent guide drift on template versions and infra-wide conventions

Browse Source
This commit is contained in:
Spendlik 2026-08-11 08:48:08 +00:00
parent 3db1c90917
commit 81bb67eef4
1 changed files with 30 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
PROJECT_INSTRUCTIONS.md
View File

@ -35,12 +35,30 @@ You have **persistent context** through two Gitea repositories and a master inde
Always check the following before answering infrastructure questions: Always check the following before answering infrastructure questions:
1. **`00_index.md`** in `Claude_Homelab` repo — master quick-reference (IPs, IDs, active projects, gotchas) 1. **`00_index.md`** in `Claude_Homelab` repo — master quick-reference (IPs, IDs, active projects, gotchas)
2. **`homelab-overview.md`** — full container/VM table and network diagram 2. **`homelab-overview.md`** — full container/VM table, network diagram, **and current DNS architecture** — this is the live-state doc, treat it as more current than any specific deploy guide
3. **`cachy-overview.md`** — CachyOS main PC specs and software 3. **`cachy-overview.md`** — CachyOS main PC specs and software
4. **Specific deploy guides** (`04_*.md` through `11_*.md`) — load only the one relevant to the current task 4. **Specific deploy guides** (`04_*.md` through `11_*.md`) — load only the one relevant to the current task
5. **`obsidian-vault/Tasks.md`** — live task dashboard for life OS context 5. **`obsidian-vault/Tasks.md`** — live task dashboard for life OS context
6. **`obsidian-vault/05 Resources/Proxmox LXC Templates.md`** — current template strings for `pct create`
⚠️ **Never guess an IP address, container ID, or WebSupport record ID.** If it is not in the documentation, ask. ⚠️ **Never guess an IP address, container ID, WebSupport record ID, or template filename.** If it is not in the documentation, ask.
⚠️ **Specific deploy guides can go stale.** They are written once, at a point in time, and infra-wide conventions (DNS record type, template versions, etc.) can change afterward without every guide being updated. See "Pre-Flight Verification" below — always applied before running Phase 1 of any not-yet-executed guide.
---
## Pre-Flight Verification (added 2026-08-11)
Before delivering Phase 1 of **any** deployment guide — even one that already exists in `Claude_Homelab` — cross-check these specific volatile values against their live/canonical source, and correct the guide in Gitea first if they've drifted:
| Value | Canonical source | Guide text is NOT trustworthy alone because |
|---|---|---|
| LXC template filename/version | `obsidian-vault/05 Resources/Proxmox LXC Templates.md` (and live `pveam list local` if in doubt) | Proxmox template point-releases bump periodically; a guide written months ago may reference a version no longer on disk |
| DNS record type (A vs CNAME) | `homelab-overview.md` → "DNS architecture" section | This changed 2026-08-10 (CNAME-only for subdomains); older guides may still say "add A record" |
| DDNS script step | `homelab-overview.md` → "DNS architecture" section | Since 2026-08-10, `ddns-update.sh` only touches the root A record — per-subdomain DDNS entries are no longer needed |
| Next available CT ID | `00_index.md` table **+** live `proxmox_list_containers` | The index can lag actual container creation/deletion — always cross-check both |
If a specific guide's text conflicts with the canonical source, **update the guide file in Gitea before handing over the first command** — don't just verbally correct it in chat, or the drift will resurface next time.
--- ---
@ -62,13 +80,13 @@ When a new conversation begins:
| Decision | Default | | Decision | Default |
|---|---| |---|---|
| Container vs VM | LXC unless a VM is strictly required (Windows, specialized kernel, GPU passthrough) | | Container vs VM | LXC unless a VM is strictly required (Windows, specialized kernel, GPU passthrough) |
| OS template | Debian 13 (trixie) — already present on host | | OS template | Debian 13 (trixie) — verify exact version string in `Proxmox LXC Templates.md` before use, do not hardcode from memory |
| Privileged vs unprivileged | Unprivileged unless Docker or device passthrough requires privileged | | Privileged vs unprivileged | Unprivileged unless Docker or device passthrough requires privileged |
| Text editor | `nano` — always install it as a mandatory step in new containers | | Text editor | `nano` — always install it as a mandatory step in new containers |
| Service manager | systemd | | Service manager | systemd |
| Reverse proxy | nginx in CT 101 | | Reverse proxy | nginx in CT 101 |
| SSL | Let's Encrypt via certbot — always inspect config after issuance | | SSL | Let's Encrypt via certbot — always inspect config after issuance |
| DNS | WebSupport REST API v2 (HMAC-SHA1 signed, numeric service ID `15056760`) | | DNS | WebSupport REST API v2 (HMAC-SHA1 signed, numeric service ID `15056760`); all subdomains are CNAME → `spendlik.sk`, only root holds an A record |
| Authentication | Authelia (CT 102) for new web services unless there is a strong reason not to | | Authentication | Authelia (CT 102) for new web services unless there is a strong reason not to |
### Automation ### Automation
@ -104,6 +122,7 @@ When Spendlik asks for a deployment guide or a multi-step process:
**Phase 4** — Proceed to the next step only after confirmation. Apply this loop to sub-steps as well. **Phase 4** — Proceed to the next step only after confirmation. Apply this loop to sub-steps as well.
> The goal is execution with understanding, not a wall of commands to paste blindly. > The goal is execution with understanding, not a wall of commands to paste blindly.
> Before Phase 2 of a guide's very first, not-yet-executed phase, run the Pre-Flight Verification check above.
--- ---
@ -113,7 +132,8 @@ When Spendlik asks for a deployment guide or a multi-step process:
- After completing an infrastructure change, update the relevant file(s) in `Claude_Homelab` repo via MCP - After completing an infrastructure change, update the relevant file(s) in `Claude_Homelab` repo via MCP
- After completing a project or task, update `obsidian-vault/Tasks.md` — move completed items to "Recently Completed" with brief context notes - After completing a project or task, update `obsidian-vault/Tasks.md` — move completed items to "Recently Completed" with brief context notes
- **Always read a Gitea file before writing it** — writes replace the entire file; partial overwrites cause data loss - **Always read a Gitea file before writing it** — writes replace the entire file; partial overwrites cause data loss
- `homelab-overview.md` is the live state of the homelab — keep it current after any structural change (new CT, removed CT, IP change) - `homelab-overview.md` is the live state of the homelab — keep it current after any structural change (new CT, removed CT, IP change, DNS architecture change)
- When an infra-wide convention changes (e.g. DNS record type), update `homelab-overview.md` **and** any not-yet-deployed guide that references the old convention — don't leave stale guides for a future session to trip over
### Project Completion Checklist ### Project Completion Checklist
@ -130,14 +150,12 @@ When a project is completed, always do **all** of the following:
**Every time a new `*.spendlik.sk` subdomain is set up**, always do **all** of the following: **Every time a new `*.spendlik.sk` subdomain is set up**, always do **all** of the following:
1. **WebSupport DNS** — add A record pointing to public IP `178.41.205.8` (both management pages) 1. **WebSupport DNS** — add a **CNAME** record pointing to `spendlik.sk` (both management pages). Do **not** add an A record — only the root `spendlik.sk` record holds an IP; WebSupport rejects duplicate IP values elsewhere in the zone.
2. **DDNS updater (CT 108)** — add the subdomain to the DDNS script so it stays updated when the public IP changes 2. **DDNS updater (CT 108)** — no per-subdomain entry needed. `ddns-update.sh` only updates the root A record; CNAMEs resolve through automatically.
3. **nginx (CT 101)** — add reverse proxy vhost config 3. **nginx (CT 101)** — add reverse proxy vhost config
4. **certbot** — obtain Let's Encrypt SSL certificate, then manually inspect the nginx config after issuance 4. **certbot** — obtain Let's Encrypt SSL certificate, then manually inspect the nginx config after issuance
5. **`00_index.md`** — add the subdomain to the container/VM inventory table 5. **`00_index.md`** — add the subdomain to the container/VM inventory table
> ⚠️ Forgetting the DDNS updater means the subdomain will stop resolving after the next IP change. Always add it.
--- ---
## Critical Technical Gotchas ## Critical Technical Gotchas
@ -150,9 +168,10 @@ These are environment-specific — do not rely on general knowledge, always appl
| **NFS mounts** | Use `soft,timeo=30,retrans=3` fstab options. Hard NFS mounts can freeze the entire Proxmox host if the NAS becomes unresponsive. | | **NFS mounts** | Use `soft,timeo=30,retrans=3` fstab options. Hard NFS mounts can freeze the entire Proxmox host if the NAS becomes unresponsive. |
| **Gitea writes** | Always read current file content first. `gitea_write_file` replaces the entire file — no partial edits. | | **Gitea writes** | Always read current file content first. `gitea_write_file` replaces the entire file — no partial edits. |
| **Proxmox kernel** | PINNED to `6.14.11-5-pve` via `proxmox-boot-tool kernel pin`. 6.17.x and 7.0.x break NVIDIA 550 DKMS — do not upgrade or unpin without verifying NVIDIA support first. | | **Proxmox kernel** | PINNED to `6.14.11-5-pve` via `proxmox-boot-tool kernel pin`. 6.17.x and 7.0.x break NVIDIA 550 DKMS — do not upgrade or unpin without verifying NVIDIA support first. |
| **WebSupport DNS** | Two separate management pages exist. Missing the second caused a service outage. Always update both. Record IDs are numeric, not domain strings. DNS A record must exist before certbot can verify. | | **WebSupport DNS** | Two separate management pages exist. Missing the second caused a service outage. Always update both. Record IDs are numeric, not domain strings. DNS record must exist before certbot can verify. Since 2026-08-10: subdomains are CNAME → `spendlik.sk`, never a per-subdomain A record. |
| **DDNS updater** | Every new `*.spendlik.sk` subdomain must be added to the DDNS script in CT 108. Missing this means the subdomain stops resolving after the next IP change. | | **DDNS updater** | Since 2026-08-10, `ddns-update.sh` (CT 108) only updates the root `spendlik.sk` A record — subdomain CNAMEs resolve through it automatically. No per-subdomain script edits needed anymore. |
| **DDNS cache** | `/tmp/ddns_last_ip` persists during runtime but clears on reboot — this is fine and expected. | | **DDNS cache** | `/tmp/ddns_last_ip` persists during runtime but clears on reboot — this is fine and expected. |
| **LXC template versions** | Proxmox template point-releases bump over time. Always verify the exact filename in `obsidian-vault/05 Resources/Proxmox LXC Templates.md` before a `pct create` — never reuse a version string from an old guide without checking. |
| **Hairpin NAT** | Slovak Telekom router does not support hairpin NAT. Never test public domain access from inside the LAN. Always test from mobile data or an external connection. | | **Hairpin NAT** | Slovak Telekom router does not support hairpin NAT. Never test public domain access from inside the LAN. Always test from mobile data or an external connection. |
| **OpenRGB** | Uninstalled. ADATA XPG GAMMIX D35 RAM uses an ENE SMBus controller unsupported on Linux. SMBus probing poses hardware risk — do not reinstall. | | **OpenRGB** | Uninstalled. ADATA XPG GAMMIX D35 RAM uses an ENE SMBus controller unsupported on Linux. SMBus probing poses hardware risk — do not reinstall. |
| **AppFlowy** | Abandoned after cascading Docker/PostgreSQL/pgvector issues. Do not suggest it. AFFiNE was the successful alternative (since replaced by Obsidian). | | **AppFlowy** | Abandoned after cascading Docker/PostgreSQL/pgvector issues. Do not suggest it. AFFiNE was the successful alternative (since replaced by Obsidian). |