Linuxknowledge-base

Stand up a Git + Markdown knowledge vault

Create a bare Git vault on an always-on host and mount it from your laptop over SSHFS, so your editor works on the one canonical copy with no sync step.

Distrosdebian, ubuntu, opensuse
Shellbash
Updated
Script
bash
# ─────────────────────────────────────────────────────────────
# PART A — On the always-on host (e.g. an LXC container)
# ─────────────────────────────────────────────────────────────

# 1. Create a dedicated, unprivileged user to own the vault
sudo useradd -m -s /bin/bash vaultwriter

# 2. Create the vault directory and initialise a Git repo
sudo -u vaultwriter mkdir -p /wiki-data/git
cd /wiki-data/git
sudo -u vaultwriter git init
sudo -u vaultwriter git config user.name  "vaultwriter"
sudo -u vaultwriter git config user.email "vault@homelab.lan"

# 3. Seed a home page and a .gitignore
sudo -u vaultwriter tee /wiki-data/git/home.md > /dev/null <<'EOF'
---
title: "Home"
type: index
status: active
---
# Knowledge Base Home

Single source of truth for the homelab. Every durable fact has one page here.
EOF

sudo -u vaultwriter tee /wiki-data/git/.gitignore > /dev/null <<'EOF'
.obsidian/workspace.json
.obsidian/graph.json
.trash/
EOF

sudo -u vaultwriter git -C /wiki-data/git add home.md .gitignore
sudo -u vaultwriter git -C /wiki-data/git commit -m "Initialise vault"

# ─────────────────────────────────────────────────────────────
# PART B — On your laptop
# ─────────────────────────────────────────────────────────────

# 4. Install SSHFS
sudo zypper install sshfs        # openSUSE
# sudo apt-get install -y sshfs  # Debian/Ubuntu

# 5. Set up key-based SSH so the mount never prompts for a password
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""   # skip if you have a key
ssh-copy-id vaultwriter@10.0.0.76                   # use YOUR host IP

# 6. Create a mountpoint and mount the vault
mkdir -p ~/wiki
sshfs vaultwriter@10.0.0.76:/wiki-data/git ~/wiki \
  -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3

# 7. Verify: you should see home.md
ls -la ~/wiki

# 8. Auto-mount on shell start — append to ~/.bashrc
cat >> ~/.bashrc <<'EOF'

# Mount the canonical vault if it isn't already
if ! mountpoint -q "$HOME/wiki"; then
  sshfs vaultwriter@10.0.0.76:/wiki-data/git "$HOME/wiki" \
    -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 2>/dev/null
fi
EOF

# 9. To unmount cleanly (e.g. before a reboot)
fusermount -u ~/wiki

What this does

Stands up a single authoritative Git + Markdown vault on an always-on host and mounts it from your laptop over SSHFS. Because the laptop edits the mounted files directly, there is exactly one canonical copy and no sync step to forget. Point Obsidian (or any editor) at ~/wiki and you are editing the real repository in place.

Why this approach

The most common mistake when building a personal knowledge base is setting up two or more writable copies and trying to sync between them. It feels like redundancy — two copies is safer than one, right? In practice, it’s the opposite. Every sync is a write operation that can go wrong: a conflict the sync tool doesn’t detect, a half-applied change when the connection drops midway, or a case where both sides have diverged and the merge picks the wrong version. I spent months with a notes folder on my laptop, a “backup” clone on a server, and a third copy in a cloud sync tool. When I needed to recover something, I didn’t know which copy was the authoritative one.

The Git-plus-SSHFS approach solves this with a structural guarantee instead of a process one. There is exactly one writable copy, living on an always-on host (in my case a Proxmox LXC container). Your laptop doesn’t have a local copy of the repo — it has a mount that makes the remote files appear local. Every edit you make in Obsidian is literally writing to the server over SSH in real time. There’s no sync step to run, no “push to sync,” and no divergence possible because there’s only one place files exist. Git records the history, but the working copy is single and remote.

Why a Proxmox LXC container specifically? Because it’s always on, completely isolated from your other services, can be snapshotted and backed up as a unit, and costs essentially nothing in resources — the vault itself is mostly small Markdown files. An LXC with 512 MB of RAM and 20 GB of storage is more than enough for years of notes. If you don’t have a Proxmox cluster, any always-on Linux machine with SSH access works: a Raspberry Pi, a VPS, an old NUC.

The vaultwriter user in this playbook is a dedicated account with only the permissions it needs — no sudo, no shell login for remote users, just SSHFS access to the Git working directory. This isolation means that if someone obtains the SSH key used for the mount, they can read and write files in the vault, but they can’t escalate to root or touch other parts of the system. It’s a small attack surface for a simple capability.

Prerequisites

  • An always-on Linux host reachable over SSH (an LXC container is ideal). Replace 10.0.0.76 with its real IP.
  • Root/sudo on that host to create the vaultwriter user.
  • A laptop with SSH; the script installs SSHFS for you.

Notes

  • Substitute your own values before running any line — this playbook uses example stand-ins. Replace 10.0.0.76 (your vault host’s IP), vaultwriter (the user you create), /wiki-data/git (repo path), ~/wiki (local mount), and homelab.lan (your domain/email). If a value looks specific to one machine, it’s a placeholder.
  • Use your real host IP. 10.0.0.76 is a documentation placeholder — substitute the address of your vault host.
  • Key-based auth is required for the auto-mount to be silent; the script generates an ed25519 key if you don’t have one.
  • The reconnect and ServerAlive options keep the mount alive across brief network drops. Without them, a Wi-Fi blip leaves a dead mount handle that hangs on access.
  • Obsidian UI files are gitignored (workspace.json, graph.json) so per-machine window state doesn’t create noisy commits.
  • This is the substrate only. Secrets discipline, the topic graph, and published views build on top of it in the companion posts — do not commit any credential to this repo (see the secrets playbook first).
  • Mark tested: true only after you have run every step end-to-end on your own hardware.
All playbooks