myDoc24 Knowledge Base — user guide

A self-hostable knowledge-base engine. Same build artifact, two deployment shapes:

• Private KB — auth required for every read. Internal handbooks, per-tenant docs.
• Public KB — anonymous reads allowed, only authors can edit. Product docs, open wikis.

The shape is picked by one env var (KB_PUBLIC_READ_MODE). Everything else — auth providers, branding, SMTP, the guest API key — is editable live from /admin/settings after install.

For the REST surface, see the API docs.

Install

Two paths. Pick Docker Compose to spin up the app + MySQL in one command, or npm direct if you already have a MySQL.

Docker Compose (turnkey)

curl -fsSL https://get.kbapp.dev/install.sh | bash

The installer drops docker-compose.yml + .env (with random secrets) into ./kb-app, pulls the image, starts both containers, and prints the URL to open. The .env it generates only has what you need — MYSQL_ROOT_PASSWORD, MYSQL_USER_PASSWORD, AUTH_SECRET, KB_HTTP_PORT (default 3000).

Day-2 ops:

State lives in ./data (config, blob storage, auth secret) and ./mysql-data (MySQL files). Back both up alongside .env.

MySQL's port 3306 is not published to the host — the DB is only reachable from the kb-app container over the private compose network. Edit docker-compose.yml to expose it if you want CLI access.

npm direct (BYO MySQL)

git clone https://github.com/solarmd-pty-ltd/knowledgeBaseApp.git
cd knowledgeBaseApp
npm ci
npm run kb:build
AUTH_SECRET="$(openssl rand -base64 32)" KB_DATA_DIR=./data npm run kb:start
# → http://localhost:3000 → finish setup in the browser

The wizard asks for a MySQL connection URL on step 1. Paste yours (mysql://user:password@host:3306/dbname) and it'll Test → Save → run migrations → create the first admin → lock itself.

The only required runtime env vars are AUTH_SECRET and KB_DATA_DIR. Everything else is editable from the browser later.

Setup wizard

Three steps. After step 3 the wizard is unreachable (/setup → /).

1. Welcome — confirms the install URL.
2. Site name + first admin — collects the display name and bootstrap admin email / name / password. Magic-link sign-up needs SMTP, which isn't configured yet, so the first admin gets a password.
3. Finalize — runs DB migrations, creates the admin with full kb:* permissions, locks the wizard, signs you in.

To re-open the wizard you'd have to delete data/config.json, data/.setup-lock, and truncate kb_user. Deliberately manual.

Configure providers

Once signed in, go to /admin/settings. Everything is DB-backed with a 30-second cache — saves apply within 30 s, no restart needed.

Each provider has an on/off toggle alongside its credentials — useful for temporarily disabling a misconfigured provider without clearing the values.

Google + Microsoft OAuth are env-var only on kb-app (AUTH_GOOGLE_* / AUTH_MICROSOFT_*). Each customer deployment needs its own per-domain consent-screen review at Google Cloud Console / Microsoft Entra ID, so there's no admin UI to configure them — set the env vars and they appear on /auth/signin automatically.

The Environment panel is the one exception

DB connection saves write to .env.local on disk (atomic, with a timestamped backup), gated by a mandatory "Test connection" so a bad URL never reaches disk. After saving, restart the service: systemctl restart kb-app on a VM, docker compose restart kb-app on the compose bundle. If the new value breaks startup, SSH in and restore from the backup path shown in the success banner.

Signing in

Open /auth/signin. The buttons shown depend on which providers are configured and enabled (the on/off toggle on /admin/settings):

• Magic-link email — enter your address, click the link in your inbox. Needs SMTP.
• Continue with Google / Microsoft — appears when AUTH_GOOGLE_* / AUTH_MICROSOFT_* env vars are set.
• Continue with Keycloak — appears when KC config + toggle are on.
• Email + password — for accounts created by an admin or anyone who's set a password via "Forgot password?".
• System admin login — break-glass backdoor for operators. Only visible if explicitly set up via a .sysadmin-secret file on the server.

After sign-in you land on the hub at /.

Reading

The home page is a hub:

1. Hero — title + description + search bar.
2. Folders grid — every top-level folder as a card with a recursive count of published articles.
3. Uncategorised — articles that don't sit under a folder.

Click a folder to drill in (/f/<slug>). Click an article to read it (/a/<slug>). The article page has a sticky TOC sidebar on the right at lg+ widths — click any heading to jump.

Search is full-text via MySQL MATCH ... AGAINST, ranked, max 50 hits across both title and body.

Authoring

You need the kb:write:pages permission to author. Operators assign it via the user-menu → "Permissions" or /admin/users.

1. Admin → New article → fill in a title.
2. You're redirected to /admin/edit/<slug> — a ProseMirror editor with headings, lists, bold/italic, links, images (drag-drop or paste, 50 MB max), tables, video, YouTube/Vimeo embeds, four callout variants (note / tip / warning / danger), and a closed palette of text/highlight colours.
3. Save Draft stores your work-in-progress; only other authors see it.
4. Publish flips status to PUBLISHED, sanitises the body, revalidates the public reader, drops the draft.
5. Archive hides without deleting; reversible from /admin.

Editorial style — title conventions, the matched-pair rule (process + data dictionary), screenshot workflow, callout variant choice — lives in ARTICLE-AUTHORING.md. Read that before authoring real content.

Editor gotchas:

• Mod-Enter breaks out of a callout / blockquote / code block.
• Mod-K opens the link dialog (external URL or KB-article picker).
• Mod-B / Mod-I / Mod-U for bold / italic / underline.
• Tables get a floating row/col menu when the caret is inside a cell.

Personal access tokens

Any signed-in user with at least one kb:* role can mint tokens at /me/tokens (user-menu → "My API tokens").

• Scope = your current permissions, snapshotted at issuance. A read-only user gets a read-only token. You can't escalate by minting.
• Show-once. The raw kbpat_… string is printed exactly once; the DB stores only the SHA-256 hash.
• Revoke from the same page. 401s immediately on the next request, no grace window.

Send as Authorization: Bearer kbpat_… on any /api/kb/* request. See the API docs for the full reference.

Sysadmin backdoor

A non-Keycloak credential login, disabled by default. Useful for bootstrapping a fresh deployment, editing KC config when KC is down, or emergency access.

Enable via a .sysadmin-secret file (not .env.local — Next.js's dotenv-expand mangles the $2b$12$... hash). Sign in as KB_SYSADMIN_USERNAME from the "System admin login" section of /auth/signin; sessions carry the full kb-admins role set. Every attempt + every config write goes to kb_audit. Rate-limited to 5 failed attempts per 15 min per IP.

Setup details (hash script, file paths, the dotenv gotcha) live in the operator README.

Where to go next

• Authoring rules → ARTICLE-AUTHORING.md
• REST API → API docs
• Operator README → README.md (nginx + systemd + runbooks)