Deploy a knowledge instance

Prerequisites

• The app-mediakit-knowledge binary built from the monorepo (see How to install the development toolchain)
• One or more media-knowledge-* content repository clones on the deployment host
• A deployment port not occupied by another service (default 127.0.0.1:9090)
• A terminal session on the host

Purpose

A knowledge instance is a running deployment of app-mediakit-knowledge, the engine that serves the platform's documentation and project wikis. Deploying one means writing a knowledge.toml that names a [site] and at least one content [[mount]], then starting the binary against it with the serve subcommand.

Procedure

1. Locate or clone the content repository you want to serve:

   ls /path/to/media-knowledge-documentation/
   

   If it isn't cloned yet:

   git clone git@github.com:pointsav/media-knowledge-documentation.git
   

2. Write knowledge.toml:

   [site]
   title = "PointSav Documentation"
   brand = "pointsav"            # "pointsav" or "woodfine" — selects the token set
   bind = "127.0.0.1:9090"
   instance = "documentation"    # "documentation" | "projects" | "corporate"
   
   [[mount]]
   path = "/path/to/media-knowledge-documentation"
   role = "primary"              # the primary mount is editable; others are read-only
   

   [site] fields other than title all have defaults (brand → "pointsav", bind → "127.0.0.1:9090", state_dir → /var/lib/local-knowledge/state) — set them explicitly only when they need to differ. [[mount]] is repeatable; a second, read-only mount is how a single instance federates content from another archive (see Use declarative knowledge mounts).

3. Build the binary, if you don't already have one:

   cd /path/to/pointsav-monorepo
   cargo build -p app-mediakit-knowledge --release
   

   The binary lands at target/release/app-mediakit-knowledge. Copy it to the deployment host if that's a different machine.

4. Start the instance:

   app-mediakit-knowledge serve --knowledge-toml knowledge.toml
   

   --knowledge-toml can also be supplied via the WIKI_KNOWLEDGE_TOML environment variable, which is the form a systemd unit typically uses. A sibling check subcommand (app-mediakit-knowledge check --knowledge-toml knowledge.toml) validates the configuration and content without starting a server — useful as a CI gate before deploying a config change.

Expected outcome

The instance binds to the address in [site].bind, reads Markdown directly from every mounted path, and serves the wiki. Content edits in the repository appear on the next request — there is no build or reindex step between an edit and it showing up.

Verification

Fetch the home page:

curl -s http://127.0.0.1:9090/ | head -20

The response should contain rendered HTML from the mount's index.md. Fetch a category page to confirm routing:

curl -s http://127.0.0.1:9090/category/architecture | grep '<title>'

If a page 404s, confirm the path in [[mount]] points at a directory that actually contains the expected category folder, and that knowledge.toml's check subcommand passes cleanly first.

Rollback

Stop the process (or systemctl stop the unit, if running as one). No state is written outside state_dir; removing or reverting knowledge.toml and restarting returns the instance to its prior configuration. The content repository itself is untouched by serving it — reverting a bad content edit is a normal git operation in that repo, not a deployment rollback.

Next steps

• Use declarative knowledge mounts — mount a second, read-only content repository into this instance
• Federate archives via content mounts — serve content from multiple archives through one instance
• Self-host a deployment — the broader appliance-image deployment path this instance can run inside

See also

• MediaKit knowledge application — the wiki server architecture and the three-instance model
• Use declarative knowledge mounts — mounting content from multiple repositories into one instance
• How to install the development toolchain — building the binary from the monorepo source
• Self-host a deployment — the broader deployment procedure of which this is one component
• Federate archives via content mounts — how to serve content from multiple archives in one instance