diff --git a/PROJECT_INSTRUCTIONS.md b/PROJECT_INSTRUCTIONS.md index a7df4cd..11f325c 100644 --- a/PROJECT_INSTRUCTIONS.md +++ b/PROJECT_INSTRUCTIONS.md @@ -35,12 +35,30 @@ You have **persistent context** through two Gitea repositories and a master inde Always check the following before answering infrastructure questions: 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 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 +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 | |---|---| | 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 | | Text editor | `nano` — always install it as a mandatory step in new containers | | Service manager | systemd | | Reverse proxy | nginx in CT 101 | | 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 | ### 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. > 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 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 -- `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 @@ -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: -1. **WebSupport DNS** — add A record pointing to public IP `178.41.205.8` (both management pages) -2. **DDNS updater (CT 108)** — add the subdomain to the DDNS script so it stays updated when the public IP changes +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)** — 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 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 -> ⚠️ Forgetting the DDNS updater means the subdomain will stop resolving after the next IP change. Always add it. - --- ## 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. | | **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. | -| **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. | -| **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. | +| **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** | 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. | +| **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. | | **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). |