Skip to content

Wiki

The wiki is the central place for „how we do things", runbooks, service docs, notes.

Concept

  • Categories (root level) group articles
  • Articles in Markdown with FTS index + vector embeddings
  • Service linking — an article can attach to specific profile-checks or hosts
  • AI RAG source — AI chat draws from the wiki first

Create an article

/wiki → New article or via quick-lookup on the service detail (see below).

Field Meaning
Title required
Category from list or new
Tags optional
Content Markdown, with toolbar and live preview
Service links n:m with profile-checks
Host-specific? optionally bind to one or more hosts

Editor toolbar: H1/H2/H3, bold, italic, code, link, lists, table, code block. Markdown mode or WYSIWYG (toggle).

Service linking

An article can be bound to profile-checks. Effect:

  • On the host detail, in the service detail there's a „Wiki" tab with linked articles
  • AI service analysis prioritizes linked articles in RAG context

Example: an article „Disk-Full Runbook" can be bound to all agent_disk profile-checks — once a disk-full alert fires, the runbook is one click away.

Host-specific binding via wiki_article_services junction with host_id field:

Article „Special handling db01" → bound to db01-specific services

Useful for „this machine has a quirk that doesn't apply to all hosts".

/wiki has a search bar with three combined methods:

  1. Full-text search (German FTS index)
  2. ILIKE fallback for partial strings (e.g. „backup" finds „backup-script")
  3. Vector search (pgvector + embeddings) for semantically similar content

Hit list with highlight, category badge, tags.

Embeddings

On article save, an embedding is computed in the background:

  • Model: nomic-embed-text (default, via Ollama) or configurable
  • Dimension: 4096 (pgvector with vector(4096))
  • Storage: wiki_articles.embedding

Embedding updates run async (asyncio.create_task), so saving doesn't block. Large bulk imports may take time to sync — status visible at /admin/embeddings.

asyncpg cast for vector

For custom SQL queries with pgvector: use CAST(:emb AS vector) not ::vector — asyncpg interprets :: as bind parameter and breaks the cast.

Quick-lookup on service detail

On a service row of a host → Wiki lookup:

  1. AI asks: „which articles could be relevant"
  2. Top 3–5 hits as a slide-in panel
  3. Click opens the article in a modal

Fastest path to a runbook mid-incident.

Soft delete

Articles are soft-deleted (see Trash) — deleted means hidden first, physically removed after 30 days.

Wiki articles with service links keep them on soft delete — restoring brings everything back.

URL Effect
/wiki Overview
/wiki?article=<id> Open article directly
/wiki?new=1 New article modal
/wiki?category=<id> Filter category

Useful for bookmarks and cross-links from emails / Slack.

Permissions

Permission Effect
wiki.view View articles
wiki.edit Edit
wiki.create Create new
wiki.delete Soft delete
wiki.purge Permanently delete from trash

Next