Skip to content

Restructure docs in deployment order and migrate to OKF v0.2 - #5

Merged
tyson-swetnam merged 1 commit into
mainfrom
claude/cyverse-docs-okf-migration-yz97f0
Jul 30, 2026
Merged

Restructure docs in deployment order and migrate to OKF v0.2#5
tyson-swetnam merged 1 commit into
mainfrom
claude/cyverse-docs-okf-migration-yz97f0

Conversation

@tyson-swetnam

Copy link
Copy Markdown
Member

Convert the documentation bundle to the Open Knowledge Format v0.2 and
reorganize it to follow the order in which CyVerse is actually deployed.

Format (OKF v0.2)

  • Every concept document carries YAML frontmatter: type, title,
    description, tags, status, generated, and sources where the content is
    derived from something.
  • Every directory carries an index.md listing, with the bundle-root
    index declaring okf_version.
  • Bundle history is recorded in docs/log.md.
  • references/ holds provenance notes for derived material.

Structure

  • architecture/ what the system is, what it needs, what depends on what
  • platform/ the products and services offered to users
  • deployment/ phases 1-7, ordered by dependency
  • operations/ running a deployed system
  • api/, development/, references/
  • deployments/, database/, guides/, and services/ are retired; their
    content moved into the tree above.

New content

  • deployment/from-scratch.md: end-to-end runbook for a two-node
    deployment, written from an anonymized pilot deployment record. All
    hostnames, zone names, DNs, realm and client names, and credentials
    are placeholders; secrets are generated per install.
  • Previously undocumented steps: HAProxy, iRODS provider and DE
    integration, iCAT, database migrations, cert-manager, Harbor, Argo,
    OpenLDAP, OpenSearch, NATS, bootstrap, verification, troubleshooting.
  • architecture/component-inventory.md and network-requirements.md.

Editorial

  • Deduplicated: mail (exim4 + local-exim), the golang-migrate procedure
    repeated in every database document, the deployment-order list that
    appeared in three places, the database list that appeared twice, and
    two retired overview pages now covered by directory indexes.
  • Corrected: databases ordered before the services that need them; the
    rsyslog path; dirname vs basename for the kubeconfig directory; the
    helm uninstall invocation; VRRP as IP protocol 112 rather than a TCP
    port; QMS extensions created in the qms database; recomputed sizing
    totals with the source's 100/110 TB discrepancy noted.
  • Fixed the docs build: zensical.toml named a theme that is not
    installable, so the published build was failing, and extra_css named a
    stylesheet that does not exist.
  • Marked Elasticsearch deprecated in favor of OpenSearch, and
    ingress-nginx transitional in favor of Traefik.
  • Replaced site-specific hostnames, DNs, and sample credentials with
    placeholders; replaced XXX placeholders in the system overview.
  • Fixed 13 broken anchors and links; the build now reports no issues.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01UKieNHmYbysTvGDK2SC1YM

Convert the documentation bundle to the Open Knowledge Format v0.2 and
reorganize it to follow the order in which CyVerse is actually deployed.

Format (OKF v0.2)
- Every concept document carries YAML frontmatter: type, title,
  description, tags, status, generated, and sources where the content is
  derived from something.
- Every directory carries an index.md listing, with the bundle-root
  index declaring okf_version.
- Bundle history is recorded in docs/log.md.
- references/ holds provenance notes for derived material.

Structure
- architecture/  what the system is, what it needs, what depends on what
- platform/      the products and services offered to users
- deployment/    phases 1-7, ordered by dependency
- operations/    running a deployed system
- api/, development/, references/
- deployments/, database/, guides/, and services/ are retired; their
  content moved into the tree above.

New content
- deployment/from-scratch.md: end-to-end runbook for a two-node
  deployment, written from an anonymized pilot deployment record. All
  hostnames, zone names, DNs, realm and client names, and credentials
  are placeholders; secrets are generated per install.
- Previously undocumented steps: HAProxy, iRODS provider and DE
  integration, iCAT, database migrations, cert-manager, Harbor, Argo,
  OpenLDAP, OpenSearch, NATS, bootstrap, verification, troubleshooting.
- architecture/component-inventory.md and network-requirements.md.

Editorial
- Deduplicated: mail (exim4 + local-exim), the golang-migrate procedure
  repeated in every database document, the deployment-order list that
  appeared in three places, the database list that appeared twice, and
  two retired overview pages now covered by directory indexes.
- Corrected: databases ordered before the services that need them; the
  rsyslog path; dirname vs basename for the kubeconfig directory; the
  helm uninstall invocation; VRRP as IP protocol 112 rather than a TCP
  port; QMS extensions created in the qms database; recomputed sizing
  totals with the source's 100/110 TB discrepancy noted.
- Fixed the docs build: zensical.toml named a theme that is not
  installable, so the published build was failing, and extra_css named a
  stylesheet that does not exist.
- Marked Elasticsearch deprecated in favor of OpenSearch, and
  ingress-nginx transitional in favor of Traefik.
- Replaced site-specific hostnames, DNs, and sample credentials with
  placeholders; replaced XXX placeholders in the system overview.
- Fixed 13 broken anchors and links; the build now reports no issues.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UKieNHmYbysTvGDK2SC1YM
@tyson-swetnam
tyson-swetnam marked this pull request as ready for review July 30, 2026 12:12
@tyson-swetnam
tyson-swetnam merged commit 9d42155 into main Jul 30, 2026
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants