Memory 019e8040
Memory ID (Session ID): 019e8040-a4aa-7000-822a-525d486ff6cd
Last Updated: 2026-06-01 03:03:24
Fact Summary
Self-Hosted Knowledgebase Architecture (0rk.de)
Stack
- Hugo static site generator on Port 55888 (Hugo Knowledgebase) (all interfaces)
- local-github-api.mjs (Node) on Port 8082 (Fake GitHub API) (localhost only) — fake GitHub REST+GraphQL API
- https-proxy.mjs (Node) on Port 55889 (Hugo KB HTTPS Proxy) (0.0.0.0) — TLS termination, routes to Hugo or API shim
- Sveltia CMS v0.165.0 self-hosted at /static/admin/sveltia-cms.js (1.9MB, no CDN)
- TLS certs at /home/dev/certs/
HTTPS Proxy Routing
- /api/v3/* → localhost:8082 (REST, strips /api/v3 prefix)
- /graphql → localhost:8082 (GraphQL)
- /* → localhost:55888 (Hugo site + admin)
Local GitHub API Shim Endpoints (local-github-api.mjs)
REST:
- GET /user, GET /repos/:owner/:repo, GET /repos/:owner/:repo/branches/:branch
- GET /repos/:owner/:repo/git/refs/heads/:branch
- GET /repos/:owner/:repo/git/trees/:sha?recursive=1
- GET/PUT/DELETE /repos/:owner/:repo/contents/:path
- POST /repos/:owner/:repo/git/blobs (create), GET /repos/:owner/:repo/git/blobs/:sha (serve raw+base64)
- POST /repos/:owner/:repo/git/trees, POST /repos/:owner/:repo/git/commits
- PATCH /repos/:owner/:repo/git/refs/heads/:branch
- GET /repos/:owner/:repo/collaborators/:user → 204
- POST /repos/:owner/:repo/dispatches → 204
GraphQL (POST /graphql):
- defaultBranchRef query
- fetchLastCommit (repository.ref.target.history)
- file contents batch (repository.file0..fileN.object.text)
- createCommitOnBranch mutation
- fetchFileCommits (repository.ref.target.history for path)
Key Implementation Details
- REPO_ROOT = /home/dev/Knowledgebase
- SHA→path index maintained in memory for blob serving
- sha1() used for content-addressable blob SHAs
- fakeSha() for synthetic commit/tree SHAs
- Git operations: real git add/commit via child_process after file writes
- CMS config at /static/admin/config.yml uses backend.name: github, repo: local/Knowledgebase, base_url: https://0rk.de:55889
Systemd Services
- hugo-knowledgebase.service
- local-github-api.service
- hugo-kb-https-proxy.service (depends on local-github-api)
- All 3 must be active for CMS to work
Pitfalls Resolved
- Sveltia CMS requires GraphQL endpoint for several operations (not just REST)
- Blob serving by SHA needed for media/image display in CMS
- /collaborators/:user must return 204 (not 404) or CMS shows permission error
- HTTPS proxy must route /graphql separately from /api/v3/*
- Self-hosting the CMS JS eliminates the last CDN dependency
- Content-Type must be set correctly for blob responses (application/json with base64)
Git History
- 079b150 Self-host Sveltia CMS v0.165.0 — zero external dependencies
- a2d7ecc Perfected self-hosted Sveltia CMS: GraphQL API, blob serving, complete GitHub shim
- 30996cd Sveltia CMS with local GitHub API shim — no GitHub account needed
Reference Session
- Associated Chat Session: 019e8040-a4aa-7000-822a-525d486ff6cd