vault backup: 2026-03-11 21:15:14

05-troubleshooting/majwiki-setup-and-pipeline.md

@@ -0,0 +1,121 @@
+---
+title: "MajorWiki Setup & Publishing Pipeline"
+domain: troubleshooting
+tags: [mkdocs, obsidian, gitea, docker, self-hosting]
+date: 2026-03-11
+---
+
+# MajorWiki Setup & Publishing Pipeline
+
+A walkthrough of how MajorWiki is built, configured, and kept in sync — from writing in Obsidian to publishing via MkDocs.
+
+## Architecture Overview
+
+| Component | Role |
+|-----------|------|
+| Obsidian | Writing and editing markdown notes |
+| Gitea | Self-hosted git remote at `git.majorshouse.com` |
+| Webhook | Flask app on port 9091, triggers on push |
+| MkDocs Material | Builds and serves the wiki at `notes.majorshouse.com` |
+| Docker | Runs the MkDocs container (`majwiki`) |
+
+## File Layout
+
+```
+/opt/majwiki/           # Git repo (content)
+  01-linux/
+  02-selfhosting/
+  04-streaming/
+  05-troubleshooting/
+  index.md
+
+/opt/majwiki-config/    # Config files (outside git)
+  mkdocs.yml            # docs_dir: docs
+  compose.yml           # Docker Compose
+  webhook.py            # Gitea webhook handler
+```
+
+## Publishing Flow
+
+1. Write or edit a note in Obsidian
+2. Obsidian syncs the vault to Gitea via git (using Obsidian Git plugin)
+3. Gitea fires a POST to the webhook at port 9091
+4. Webhook verifies the HMAC signature, runs `git pull` on `/opt/majwiki`
+5. Webhook restarts the `majwiki` Docker container
+6. MkDocs rebuilds the site and serves the updated content
+
+## Key Configuration
+
+### mkdocs.yml (in /opt/majwiki-config/)
+
+The critical setting is `docs_dir: docs` — this tells MkDocs to look for
+markdown files in the `docs/` subdirectory of its working directory, which
+maps to `/opt/majwiki/` via the Docker volume mount.
+
+### compose.yml volume mounts
+
+```yaml
+volumes:
+  - /opt/majwiki-config/mkdocs.yml:/docs/mkdocs.yml
+  - /opt/majwiki:/docs/docs
+```
+
+### Nav tabs require index.md files
+
+Each section needs an `index.md` to make the top nav tabs clickable.
+Without it, MkDocs renders the tab as a non-linked dropdown header.
+These index files must live in the git repo root, not in any Obsidian
+sync subfolder.
+
+## Problems Encountered & Solutions
+
+### index.md files not found by MkDocs
+The git repo at `/opt/majwiki/` contains a `docs/` subdirectory used by
+Obsidian sync. MkDocs was seeing index files at `docs/01-linux/index.md`
+instead of `01-linux/index.md`. Fix: removed the stale copies from
+`/opt/majwiki/docs/` and kept the authoritative ones in the repo root.
+
+### mkdocs.yml wiped by git reset
+Running `git reset --hard origin/main` on `/opt/majwiki/` deleted
+`mkdocs.yml`, `compose.yml`, and `webhook.py` since they weren't tracked
+in the repo. Fix: moved all config files to `/opt/majwiki-config/` outside
+the git repo.
+
+### docs_dir: . not allowed
+MkDocs refuses `docs_dir: .` when `mkdocs.yml` is in the same directory.
+Fix: mount `mkdocs.yml` separately at `/docs/mkdocs.yml` and the content
+at `/docs/docs/` via Docker volumes, then set `docs_dir: docs`.
+
+### Home page wikilinks not clickable
+The original `index.md` used Obsidian-style `[[wikilinks]]` which MkDocs
+renders as plain text. Fix: rewrote `index.md` using standard Markdown
+links.
+
+## Managing the Services
+
+```bash
+# Restart the wiki
+cd /opt/majwiki-config && docker compose restart wiki
+
+# Check webhook status
+systemctl status majwiki-webhook
+
+# View live logs
+docker logs majwiki -f
+
+# Force a manual pull
+git -C /opt/majwiki pull --ff-only
+```
+
+## Webhook Service
+
+The webhook runs as a systemd service so it survives reboots:
+
+```
+/etc/systemd/system/majwiki-webhook.service
+```
+
+```bash
+systemctl status majwiki-webhook
+systemctl restart majwiki-webhook
+```