Skip to content

Enterprise deployment runbook

Deploy OntoCode (VS Code) and OntoIndex (CLI/LSP) in regulated, air-gapped, or centrally managed environments. Complements enterprise evaluation and production readiness.

Deployment patterns

Pattern Components Typical owner
Developer desktop VS Code + Marketplace or VSIX Engineering
CI validation ontoindex Linux x64 binary or cargo install Platform / DevOps
CI + desktop Both Most common enterprise pilot
Air-gapped Internal VSIX + CLI mirror + NOTICES IT security

Ontology content stays on disk — no cloud upload by default (security policy).

VS Code extension rollout

Option A — Marketplace (internet-connected)

  1. Allowlist extension publisher ontocode and extension ontocode.ontocode
  2. Pin minimum VS Code 1.85+ (vscode-install)
  3. Document Trust workspace requirement (Restricted Mode blocks custom LSP path)
  4. Communicate single-root workspace rule — only first folder indexed (FAQ)
  1. On a connected staging machine, download from GitHub Releases for version v0.8.0 (or your pinned version):
  2. ontocode-<version>.vsix
  3. SHA256SUMS
  4. NOTICES
  5. Optional: ontoindex-lsp-v<version>-<platform>.tar.gz per platform if not using bundled VSIX LSP
  6. Verify checksums:
sha256sum -c SHA256SUMS
  1. Transfer artifacts to internal artifact store (Artifactory, Nexus, S3 with policy, etc.)
  2. Distribute install procedure to developers:

Extensions → … → Install from VSIX… → select internal copy of ontocode-*.vsix

  1. Archive NOTICES and version metadata alongside the VSIX for legal/compliance audits.

See release integrity for full verification steps.

Option C — Build from source (highest control)

From an internal git mirror of the repository:

./scripts/package-extension.sh
cd extension && npx vsce package --no-dependencies

Install resulting VSIX internally. Requires Rust + Node toolchains on build host.

Pinning and updates

Practice Recommendation
Version pin Standardize on one release tag (e.g. v0.8.0) across VSIX and CLI
Update cadence Quarterly review of changelog and SECURITY.md on GitHub
Staged rollout Pilot group → department → org (see production readiness)
Rollback Keep previous VSIX + CLI tarball in internal registry

Pre-1.0: expect minor release API changes — test CI and integrators before org-wide bump.

CLI on CI agents

Download pinned release binary — fastest cold start:

VERSION=0.8.0
ASSET="ontoindex-v${VERSION}-x86_64-unknown-linux-gnu.tar.gz"
BIN="ontoindex-v${VERSION}-x86_64-unknown-linux-gnu"
curl -fsSL -o "${ASSET}" \
  "https://github.com/eddiethedean/ontocode/releases/download/v${VERSION}/${ASSET}"
tar xzf "${ASSET}"
chmod +x "${BIN}"
./"${BIN}" validate /path/to/ontologies

Verify against SHA256SUMS in production pipelines (ci-integration).

macOS / Windows CI

Platform Release CLI binary Alternatives
Linux x64 Yes —
macOS No cargo install ontoindex-cli --locked --version 0.8.0 (requires Rust on agent)
Windows No Same, or WSL/Linux job for validate

Cache ~/.cargo or an internal cargo registry mirror to reduce cargo install time.

Language server hardening

Control Action
Never expose LSP on network stdio only with trusted editor (SECURITY.md)
ontocode.lspPath Disable via policy or restrict to trusted workspaces only
Restricted Mode Default untrusted repos — bundled LSP used; custom path ignored
Workspace trust Document that untrusted clones skip admin LSP overrides

Group policy / MDM checklist

  • [ ] Extension allowlist includes ontocode.ontocode OR distribute VSIX via internal portal only
  • [ ] Block Marketplace auto-update if policy requires pinned VSIX
  • [ ] Document single-root workspace convention in internal wiki
  • [ ] Provide internal support link for troubleshooting (empty explorer, LSP start failures)
  • [ ] Archive NOTICES + version per deployment wave (LGPL compliance)

Remote development (SSH, dev containers, Codespaces)

Documentation does not certify these environments. Pilot checklist:

  1. Install VSIX on remote VS Code server if using Remote-SSH (extension runs remotely)
  2. Confirm bundled ontoindex-lsp matches remote OS/architecture (VSIX bundles Linux/macOS/Windows x64)
  3. Open ontology folder on remote filesystem (indexing is local to LSP process)
  4. Re-run first success on the remote host

Report gaps via GitHub issues.

Audit and logging

OntoCode does not ship centralized audit logging. For compliance:

Event Suggested org control
Ontology edits Git commit history (write-back modifies .ttl on disk)
CI validation Pipeline logs for ontoindex validate / classify exit codes
Extension install MDM/Marketplace audit logs
Vulnerability response Subscribe to GitHub Security Advisories for eddiethedean/ontocode

Reference architecture

flowchart LR
  subgraph corp [Corporate network]
    Artifactory[Internal artifact mirror]
    Dev[Developer VS Code]
    CI[CI runner Linux x64]
    Git[Git ontology repo]
  end
  Artifactory -->|VSIX NOTICES CLI| Dev
  Artifactory -->|ontoindex binary| CI
  Dev -->|stdio| LSP[ontoindex-lsp]
  LSP --> Git
  CI --> Git