Diff: how-to/deploy-knowledge-instance.es
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "How to deploy a knowledge instance" | title: "How to deploy a knowledge instance" |
| slug: deploy-knowledge-instance | slug: deploy-knowledge-instance |
| category: how-to | category: how-to |
| content_type: how-to | content_type: how-to |
| type: how-to | type: how-to |
| status: active | status: active |
| last_edited: 2026-06-14 | last_edited: 2026-06-14 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: deploy-knowledge-instance.es.md | paired_with: deploy-knowledge-instance.es.md |
| --- | --- |
| A knowledge instance is a running deployment of `app-mediakit-knowledge` — the wiki server that renders the platform's documentation and project wikis. Deploying an instance means building the binary, writing a `knowledge.toml` configuration file pointing at the content repositories, and starting the service. This guide covers deploying a single-instance wiki from a local content path. | A knowledge instance is a running deployment of `app-mediakit-knowledge` — the wiki server that renders the platform's documentation and project wikis. Deploying an instance means building the binary, writing a `knowledge.toml` configuration file pointing at the content repositories, and starting the service. This guide covers deploying a single-instance wiki from a local content path. |
| For the three-instance model (documentation, projects, corporate), see [[app-mediakit-knowledge]]. For declarative content mounts, see [[use-knowledge-mounts]]. | For the three-instance model (documentation, projects, corporate), see [[app-mediakit-knowledge]]. For declarative content mounts, see [[use-knowledge-mounts]]. |
| ## Prerequisites | ## Prerequisites |
| - The `app-mediakit-knowledge` binary built from the monorepo (see [[install-toolchain]]) | - The `app-mediakit-knowledge` binary built from the monorepo (see [[install-toolchain]]) |
| - One or more `media-knowledge-*` content repository clones on the deployment host | - One or more `media-knowledge-*` content repository clones on the deployment host |
| - A deployment port (e.g., 9090) that is not occupied by another service | - A deployment port (e.g., 9090) that is not occupied by another service |
| - A terminal session on the host | - A terminal session on the host |
| ## Step 1: Locate the content repository | ## Step 1: Locate the content repository |
| The wiki server reads Markdown from a local path. Identify the path to the content repository you want to serve: | The wiki server reads Markdown from a local path. Identify the path to the content repository you want to serve: |
| ``` | ``` |
| ls ~/Foundry/clones/project-editorial/media-knowledge-documentation/ | ls ~/Foundry/clones/project-editorial/media-knowledge-documentation/ |
| ``` | ``` |
| The repository must contain an `index.md` at root and category subdirectories with `_index.md` landing pages. If the content has not yet been cloned, clone it first: | The repository must contain an `index.md` at root and category subdirectories with `_index.md` landing pages. If the content has not yet been cloned, clone it first: |
| ``` | ``` |
| git clone git@github.com:pointsav/media-knowledge-documentation.git | git clone git@github.com:pointsav/media-knowledge-documentation.git |
| ``` | ``` |
| ## Step 2: Write the configuration file | ## Step 2: Write the configuration file |
| Create `knowledge.toml` in the deployment directory: | Create `knowledge.toml` in the deployment directory: |
| ```toml | ```toml |
| [server] | [server] |
| port = 9090 | port = 9090 |
| bind = "0.0.0.0" | bind = "0.0.0.0" |
| [content] | [content] |
| primary_path = "/path/to/media-knowledge-documentation" | primary_path = "/path/to/media-knowledge-documentation" |
| instance_name = "documentation" | instance_name = "documentation" |
| [search] | [search] |
| enabled = true | enabled = true |
| index_path = "/var/lib/knowledge/search-index" | index_path = "/var/lib/knowledge/search-index" |
| [auth] | [auth] |
| enabled = false # set true + configure MBA if editor UI is needed | enabled = false # set true + configure MBA if editor UI is needed |
| ``` | ``` |
| `primary_path` must be an absolute path to a `media-knowledge-*` clone. `instance_name` appears in the rendered header and in log messages — use a short, descriptive value. | `primary_path` must be an absolute path to a `media-knowledge-*` clone. `instance_name` appears in the rendered header and in log messages — use a short, descriptive value. |
| ## Step 3: Build or locate the binary | ## Step 3: Build or locate the binary |
| If you have not already built the binary, build it from the monorepo: | If you have not already built the binary, build it from the monorepo: |
| ``` | ``` |
| cd ~/Foundry/clones/<your-archive>/pointsav-monorepo | cd ~/Foundry/clones/<your-archive>/pointsav-monorepo |
| cargo build -p app-mediakit-knowledge --release | cargo build -p app-mediakit-knowledge --release |
| ``` | ``` |
| The binary appears at `target/release/app-mediakit-knowledge`. Copy it to the deployment host if they are different machines. | The binary appears at `target/release/app-mediakit-knowledge`. Copy it to the deployment host if they are different machines. |
| ## Step 4: Start the instance | ## Step 4: Start the instance |
| Run the binary with the configuration file: | Run the binary with the configuration file: |
| ``` | ``` |
| app-mediakit-knowledge --config knowledge.toml | app-mediakit-knowledge --config knowledge.toml |
| ``` | ``` |
| Or start it as a systemd service using the provided unit file template (if available in the deployment). The service logs startup messages: it reads the content path, builds the search index, and starts listening on the configured port. | Or start it as a systemd service using the provided unit file template (if available in the deployment). The service logs startup messages: it reads the content path, builds the search index, and starts listening on the configured port. |
| ## Step 5: Verify the instance is serving | ## Step 5: Verify the instance is serving |
| Fetch the wiki home page: | Fetch the wiki home page: |
| ``` | ``` |
| curl -s http://127.0.0.1:9090/ | head -20 | curl -s http://127.0.0.1:9090/ | head -20 |
| ``` | ``` |
| The response should contain HTML for the wiki home page rendered from `index.md`. Fetch a category page to confirm article routing: | The response should contain HTML for the wiki home page rendered from `index.md`. Fetch a category page to confirm article routing: |
| ``` | ``` |
| curl -s http://127.0.0.1:9090/architecture/ | grep '<title>' | curl -s http://127.0.0.1:9090/architecture/ | grep '<title>' |
| ``` | ``` |
| If any page returns a 404, check that `primary_path` in `knowledge.toml` points to a directory containing the expected category folder. | If any page returns a 404, check that `primary_path` in `knowledge.toml` points to a directory containing the expected category folder. |
| ## Key takeaways | ## Key takeaways |
| - The wiki server reads content directly from the local file path — changes to the content repository appear immediately without a service restart | - The wiki server reads content directly from the local file path — changes to the content repository appear immediately without a service restart |
| - `instance_name` in the configuration is the label used in logs and the rendered header | - `instance_name` in the configuration is the label used in logs and the rendered header |
| - The search index is built at startup and lives at `index_path` — changing this path requires clearing the old index directory | - The search index is built at startup and lives at `index_path` — changing this path requires clearing the old index directory |
| - Three separate instances with three content paths serve documentation, projects, and corporate wikis independently | - Three separate instances with three content paths serve documentation, projects, and corporate wikis independently |
| ## See also | ## See also |
| - [[app-mediakit-knowledge]] — the wiki server architecture and the three-instance model | - [[app-mediakit-knowledge]] — the wiki server architecture and the three-instance model |
| - [[use-knowledge-mounts]] — mounting content from multiple repositories into one instance | - [[use-knowledge-mounts]] — mounting content from multiple repositories into one instance |
| - [[install-toolchain]] — building the binary from the monorepo source | - [[install-toolchain]] — building the binary from the monorepo source |
| - [[self-host-a-deployment]] — the broader deployment procedure of which this is one component | - [[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 | - [[federate-archives-via-content-mounts]] — how to serve content from multiple archives in one instance |