A self-hosted knowledge, documentation and project-intelligence platform for people who want the speed of Markdown with the safety of revisions, permissions and verified backups.

Knowledge Hub combines a technical wiki, project dossiers, architecture decisions and runbooks in one searchable application. It remains fully useful without AI. A scoped REST API supports external automation, while MCP transport deliberately lives outside this repository.

What you can do

Organize Markdown pages in a fast, hierarchical knowledge tree.
Search titles, content and tags with PostgreSQL full-text and fuzzy matching.
Edit safely with private drafts, immutable revisions and explicit conflict handling.
Upload deduplicated attachments with signature-based type validation.
Track projects, milestones, updates, architecture decisions and runbook validation.
Import LeafWiki content through a read-only, preflighted and reversible workflow.
Create scoped, revocable service-account tokens for the versioned /api/v1 API.
Synchronize personal preferences across devices and manage versioned platform policy.
Follow durable course-tagging and backup jobs with live progress and cancellation.
Search knowledge, projects, services, runbooks and decisions from one workspace.
Manage source freshness and inspect recorded deployment, recovery and telemetry evidence.
Back up the database and attachments together, then verify a clean-target restore.

Screenshots

These captures come from a local instance populated with synthetic demo data.

Quick start

Requirements: Docker with Compose, Node.js 24 and Corepack.

cp .env.example .env
# Set a strong, unique POSTGRES_PASSWORD in .env.
node scripts/doctor.mjs
docker compose up --build -d

Open http://localhost:1240 and complete the one-time owner setup. The default stack contains one application container and one PostgreSQL container; PostgreSQL is not published to the host.

For a production deployment, terminate TLS at a trusted reverse proxy, use mounted secrets, persist every documented data volume and test restore before relying on a backup. Start from the reviewed Docker Compose configuration and the backup/restore guide.

Organize your first knowledge space

After first-run owner setup, create a small page, edit its Markdown and inspect the saved revision. Add a project dossier when you need structured decisions and runbooks, then test search with words from your own content. Keep drafts distinct from published reference material.

For LeafWiki migration, review the import preflight and conflicts before execution; retain the import identifier for validation and rollback. The source snapshot stays read-only. External applications should use a separately scoped service account rather than the owner's browser credentials.

Architecture

Browser or scoped API client
            |
         HTTPS
            |
  ASP.NET Core + React
            |
        PostgreSQL
            |
 attachments / backups

The backend is a modular monolith with separate Domain, Application, Contracts, Infrastructure and API projects. React is built into the production image. Markdown is the canonical human-readable content format, PostgreSQL is the transactional source of truth, and attachments are stored by SHA-256 outside the database.

Development and verification

Backend development uses the .NET SDK pinned in global.json (10.0.302, with latestFeature roll-forward). The container build supplies its own SDK; host SDK tooling is for development.

corepack pnpm install --frozen-lockfile
node scripts/verify.mjs --fast
node scripts/verify.mjs --ci

The CI gate covers formatting, compilation, static analysis, backend and frontend tests, OpenAPI consistency and the production image. The release gate adds dependency, secret and container scans plus the full-scale search proof:

node scripts/verify.mjs --release

Integration tests use real PostgreSQL through Testcontainers. Browser tests exercise desktop and mobile flows and include automated accessibility checks.

API and automation

The OpenAPI contract is in docs/api/openapi.yaml. External clients use one-time-display service-account tokens with explicit scopes. Mutating content routes use ETags and If-Match; retryable creates support Idempotency-Key.

This repository does not contain an MCP server, shell executor, arbitrary script runtime or runbook execution engine.

Security and data safety

Content is private by default and authorization is enforced server-side.
Cookie mutations require CSRF protection; API clients use scoped bearer tokens.
Normal deletion uses trash and retention; permanent purge is an explicit admin act.
LeafWiki inspection and import never modify the source.
Restore targets must be clean and are verified against backup manifests and hashes.
The production container runs non-root with a read-only root filesystem and dropped capabilities.

Report vulnerabilities using SECURITY.md. Do not include secrets or real private knowledge in an issue.

Project status and limitations

The implemented platform includes the wiki, search, projects, ADRs, runbooks, attachments, reversible import, scoped API and backup/restore path. Current limitations include no real-time collaborative editing, no built-in MCP transport, no arbitrary runbook execution and no public anonymous publishing by default.

Historical delivery and production evidence is retained in the private canonical repository. The itworx-knowledge-hub-Public repository is automatically generated from the curated source boundary after merges to private canonical main. The manifest identifies the exact source revision. Private history, real knowledge, operational evidence and internal Actions remain excluded.

Contributing and license

See CONTRIBUTING.md before proposing a change. The project remains proprietary under LICENSE. Public visibility grants no additional redistribution or open-source rights; third-party dependencies retain their own terms.