Cloud Knowledge Platform

Cloud Knowledge Platform is a self-hosted Obsidian Sync alternative — a 100% free, Git-versioned sync gateway for your Obsidian vaults on Ubuntu. It synchronises Markdown notes across devices over LiveSync (CouchDB) or WebDAV, versions every change in Git, exposes a Web-App for admin/data management, and dispatches new notes to the Hermes Agent, which synthesises them into structured Knowledge — the DIKW-T pipeline.

The pipeline is organised around the DIKW-T pyramid (Data → Information → Knowledge → Wisdom + Time) — one folder per stage (inbox/, notes/, knowledge/, wisdom/), plus the per-project Git repo as the time-series backbone. See docs/dikw-t.md for the authoritative model.

Capabilities

• Two sync options: Self-hosted LiveSync (CouchDB) for real-time E2E encrypted sync, or a built-in WebDAV endpoint for Obsidian Remotely Save — no CouchDB needed for the WebDAV path.
• Obsidian-like Web-App: three-pane editor with live Markdown preview, wikilinks, backlinks, tag browser, full-text search (Ctrl+K), force-directed graph, file tree with CRUD, dark theme.
• Obsidian bridge: reads <vault>/.obsidian/ (workspace, starred, plugins, graph) and exposes it via API so the dashboard reflects what Obsidian sees.
• Git-backed time-series history: per-project repo, debounced commits, per-file history, unified diff view, one-click restore.
• Event-driven Hermes pipeline: watcher fires a worker queue with exponential-backoff retries; re-trigger from the UI.
• Admin auth (bearer token) and live updates over SSE.
• Multi-project isolation: separate CouchDB DB, vault dir, Git repo, Hermes workdir per project — and every API/WebDAV file path is containment-checked, so a project-scoped token can never reach another project's vault (even via ../).

Repo layout

backend/      FastAPI service (sync monitor, projects, graph, versioning, watcher, Hermes bridge)
frontend/     Static dashboard (no build step)
docs/         Architecture, client setup, knowledge base, known issues, guidelines
reference/    External blueprints (Honcho, Obsidian) — reconstruction-grade specs
business/     Project scope, stakeholders, success criteria
scripts/      server.sh (one-script lifecycle) + deploy-new-server.sh + client/ helpers
docker-compose.yml   CouchDB + backend

Quick start

./scripts/server.sh bootstrap  # one-shot from a bare Ubuntu: apt → install → start
# open http://<server>:8787/

Already have Docker + python3-venv? Use the shorter dev path:

./scripts/server.sh install    # venv + deps + CouchDB via docker compose
./scripts/server.sh start      # boot the FastAPI backend (foreground)

scripts/server.sh is the single entry point for all server-side lifecycle operations: bootstrap, install, start, deploy, upgrade, status, backup, help.

Client setup: see docs/client-setup.md. Architecture: see docs/architecture.md.

Client onboarding

New users connecting Obsidian (desktop or mobile) to this platform should start with the step-by-step guide at docs/setup-client.md. Technical users on macOS, Linux, or Windows can run the helper scripts in scripts/client/ to pre-fill plugin settings automatically.

Production deploy

For a hardened production install (systemd service, Caddy TLS, CouchDB in Docker, idempotent deploy script) see docs/setup-server.md.

One-shot from a bare box: if you have a fresh Ubuntu/Debian VM and just want it provisioned end-to-end (apt prereqs → clone repo → generate .env → server.sh deploy), run:

sudo DOMAIN=ckp.example.com ./scripts/deploy-new-server.sh
# or curl-pipe directly onto the new box:
curl -fsSL https://raw.githubusercontent.com/bejranonda/Cloud-Knowledge-Platform/main/scripts/deploy-new-server.sh \
  | sudo DOMAIN=ckp.example.com bash

deploy-new-server.sh is the wrapper that bootstraps a brand-new server; server.sh deploy is the lower-level command it ultimately invokes. Use the wrapper on first install, server.sh upgrade thereafter.

Quickstarts

Role-specific guides for getting productive fast:

• docs/quickstart-user.md — end user who wants to take notes in Obsidian and have them sync automatically.
• docs/quickstart-manager.md — team manager who creates projects, onboards teammates, and monitors Hermes output.
• docs/quickstart-admin.md — server admin who owns the Ubuntu box, Docker, Caddy, and backups.

Reverse-engineering references

The reference/ folder contains reconstruction-grade blueprints for the two external systems that most influenced this project:

• reference/honcho/ — ambient personalisation, Conclusion/Representation/Dream pipeline, DIKW-T mapping.
• reference/obsidian/ — vault model, MetadataCache, LiveSync, headless CLI, failure modes.
• reference/hermes/ — Hermes Agent (Nous Research): self-improving loop, skill store, gateway, subagents, and how our stub contract differs from the real CLI.
• reference/livesync/ — Self-hosted LiveSync: CouchDB doc model, chunking, E2E encryption flow, conflict resolution, and the cleartext-materialisation tradeoff we accept.

Each platform_blueprint.md is complete enough that an AI given only that file could stand up a working equivalent. See reference/README.md for a guided tour.

Contributing

Before making non-trivial changes read docs/approach.md — it's the decision playbook for this codebase.

License

Internal / self-hosted use.