132 lines
5.9 KiB
Markdown
132 lines
5.9 KiB
Markdown
# ItWorx Knowledge Hub
|
|
|
|
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.
|
|
- 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.
|
|
|
|
```bash
|
|
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](docker-compose.yml) and
|
|
the [backup/restore guide](docs/guides/back-ups-herstel-en-unraid-beheer.md).
|
|
|
|
## 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
|
|
|
|
```text
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](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](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](CONTRIBUTING.md) before proposing a change. The project remains proprietary under [LICENSE](LICENSE). Public visibility grants no additional redistribution or open-source rights; third-party dependencies retain their own terms.
|