Lessons — Knowledge Wiki

Lessons — Knowledge Wiki

What Broke

Git dubious ownership error on NFS mount
git init on /Volumes/knowledge failed with “detected dubious ownership” because the NFS mount is owned by a different UID than the Mac user. Fix:

git config --global --add safe.directory /Volumes/knowledge

Run this before any git operation on an NFS-mounted share.

Git initialized as master, not main
git push -u origin main failed because the branch was named master. Fix:

git branch -m master main

Do this immediately after git init before any commits.

macOS resource fork files committed to git
NFS shares on Synology get ._* files (AppleDouble resource forks) and a #recycle/ directory written to them by macOS. These got committed in the initial push. Fix: create .gitignore before the first commit:

._*
.DS_Store
#recycle/
@eaDir/

Then git rm -r --cached to remove already-tracked junk files.

Gitea repo must be created manually before first push
git push to a non-existent Gitea repo returns a 403 “Push to create is not enabled for users” error. You must create the repo in the Gitea UI first (unchecked “Initialize repository”), then push.

Shell comments in terminal instructions
Inline # comments in multi-line shell instructions are interpreted by zsh as commands and produce “command not found: #” errors. Harmless but confusing. When running Claude’s commands, strip the comment lines first or paste commands one at a time.

NFS mount kills mkdocs live-reload
mkdocs serve uses inotify to watch for file changes. NFS mounts on Linux do not reliably deliver inotify events, so the container never detects new or changed files. WATCHDOG_USE_POLLING=true was attempted but did not resolve it. The working fix: restart the knowledge stack in Komodo after every commit. The container does a full fresh read of the NFS mount on startup.

Explicit nav in mkdocs.yml doesn’t auto-discover subdirectories
Setting nav: - Projects: projects/ shows only the section landing page — it does not recursively discover sub-pages in nested directories. Fix: remove the nav: block entirely. MkDocs auto-discovers the full directory tree and builds the nav from the folder structure. Section names come from directory names (title-cased automatically).

What Worked Well

• Keeping the content repo (knowledge) separate from the infra repo (homelab-containers) means wiki content commits don’t pollute the container changelog and vice versa
• NFS writable from SpaceDock confirmed before deploying the container — test this early on any new NFS-backed container
• No nav: block in mkdocs.yml means no manual config updates when adding new projects or sections

The Add-Content Workflow

# 1. Write files to /Volumes/knowledge/docs/...
# 2. Commit and push
kcommit "added: description of what you added"
# 3. Restart the container so MkDocs re-reads the NFS mount
#    Komodo → Stacks → knowledge → Restart

What to Do Differently Next Time

• Run git config --global --add safe.directory <mount> and create .gitignore before git init on any NFS share
• Create the Gitea repo before running git remote add + git push
• Rename branch to main immediately after git init
• Do not use a nav: block — let MkDocs auto-discover