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

title, domain, tags, date

title	domain	tags	date
MajorWiki Setup & Publishing Pipeline	troubleshooting	mkdocs obsidian gitea docker self-hosting	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

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

# 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

systemctl status majwiki-webhook
systemctl restart majwiki-webhook

---

Updated 2026-03-13: Obsidian Git plugin dropped. See canonical workflow below.

Canonical Publishing Workflow

The Obsidian Git plugin was evaluated but dropped — too convoluted for a simple push. Manual git from the terminal is the canonical workflow.

cd ~/Documents/MajorVault
git add 20-Projects/MajorTwin/08-Wiki/
git commit -m "wiki: describe your changes"
git push

From there: Gitea receives the push → fires webhook → majorlab pulls → MkDocs rebuilds → notes.majorshouse.com updates.