Skip to main content

INVESTIGATE: Old Deployment System Cleanup & Documentation Gaps

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

Created: 2026-03-17 Status: Completed (2026-03-17) Related to: INVESTIGATE: Old Deployment System & UIS Migration

Problem Statement​

The migration from the old deployment system (provision-host/kubernetes/) to the UIS CLI (provision-host/uis/) is functionally complete — all 30 services deploy through UIS. But the old system is still in the repo, creating confusion for anyone trying to understand how UIS works. Dead code undermines documentation — if someone sees 60 scripts in provision-host/kubernetes/, they can't tell which system is real.

Cleanup and documentation are the same task: remove the noise so the signal is clear.

What Exists Today​

Dead Code: provision-host/kubernetes/​

60 scripts (6,149 lines), 59 already in not-in-use/ subfolders. The one remaining active script (01-core/020-setup-nginx.sh) is a 125-line wrapper that calls the same Ansible playbook as ./uis deploy nginx. Plus provision-kubernetes.sh (the old orchestrator) and ./uis provision legacy fallback command.

FolderActiveInactive
01-core11
02-databases08
03-queues04
04-search02
05-apim01
06-management04
07-ai06
08-development02
09-network06
10-datascience06
11-monitoring014
12-auth02
99-test02
Total159

Existing Documentation​

The CLI and deployment system are documented across several files:

DocumentWhat it coversAudience
docs/reference/uis-cli-reference.mdFull command referenceUsers
docs/getting-started/installation.mdInstall and first runUsers
docs/getting-started/overview.mdQuick start, first deployUsers
docs/getting-started/architecture.mdSystem architecture diagramUsers
docs/contributors/guides/adding-a-service.md11-step guide to add a serviceContributors
docs/contributors/rules/kubernetes-deployment.mdMetadata, categories, deploy flowContributors
docs/contributors/architecture/deploy-system.mdDeploy system architectureContributors
provision-host/uis/templates/uis.extend/README.mdConfiguration directoryUsers
provision-host/uis/templates/uis.secrets/README.mdSecrets workflowUsers

Documentation Gaps​

What's missing or incomplete:

  1. How deployment works under the hood — no user-facing page explaining the flow from ./uis deploy → service metadata → Ansible playbook → Kubernetes resources. The contributor docs cover this but users don't see it.

  2. Service override customization — uis.extend/service-overrides/ exists but has no guide on what can be overridden or examples.

  3. Stack creation — stacks are documented in rules but no guide on defining custom stacks.

  4. Cloud host deployment — out of scope, covered by INVESTIGATE: Remote Deployment Targets.

  5. Old system references in docs — some docs may still reference provision-host/kubernetes/ paths or the old deployment model.

Naming Inconsistency: "Services" vs "Packages"​

The CLI and data model use services everywhere, but the documentation uses packages:

WhereTerm used
CLI commands./uis deploy <service>, ./uis list, ./uis status
Service definitionsprovision-host/uis/services/*/service-*.sh
Generated datawebsite/src/data/services.json
Navbar link"Services" → /services
Documentation folderwebsite/docs/packages/
Sidebar category/docs/category/packages
Doc generator outputuis-docs-markdown.sh writes to docs/packages/

A user clicks "Services" in the navbar, then finds "Packages" in the sidebar. This looks like two different things when it's the same thing.

Decision: Rename packages to services throughout the documentation. This affects:

  • website/docs/packages/ → website/docs/services/
  • All internal links referencing /docs/packages/...
  • Sidebar category labels and _category_.json files
  • uis-docs-markdown.sh output path
  • services.json docs field in every service entry (currently /docs/packages/...)
  • Service script metadata (SCRIPT_DOCS field in every service-*.sh)

References to Old System Outside provision-host/kubernetes/​

The old deployment system is referenced in active code and documentation outside the folder itself. These must be updated before or during deletion:

Host-side CLI wrappers (execute the old system):

  • uis (bash wrapper, line ~243) — provision command calls provision-kubernetes.sh
  • uis.ps1 (PowerShell wrapper, line ~174) — same provision command

Note: The investigation scope says "Remove from uis-cli.sh" but the command actually lives in the host-side wrappers, not in uis-cli.sh.

Legacy package scripts (separate dead code):

  • scripts/packages/ai.sh — references old script paths
  • scripts/packages/auth.sh — references old script paths

This scripts/packages/ folder appears to be another legacy system predating UIS. Should be evaluated for deletion.

Host installation scripts (still call the old system):

  • hosts/install-azure-microk8s-v2.sh (line ~220) — executes provision-kubernetes.sh
  • hosts/install-azure-aks.sh (line ~168) — references old system in instructions
  • hosts/azure-aks/02-azure-aks-setup.sh (line ~173) — references old system in instructions

Important: hosts/install-azure-microk8s-v2.sh actively calls the old orchestrator. Deleting provision-host/kubernetes/ without migrating this script will break Azure VM deployment. This is tied to INVESTIGATE: Remote Deployment Targets.

Documentation (6 files reference old paths):

  • docs/reference/troubleshooting.md
  • docs/advanced/hosts/azure-aks.md
  • docs/advanced/hosts/index.md
  • docs/contributors/rules/kubernetes-deployment.md
  • docs/networking/tailscale-internal-ingress.md
  • docs/packages/ai/environment-management.md

Deletion Order​

Cannot just delete provision-host/kubernetes/. The order matters:

  1. Migrate hosts/install-azure-microk8s-v2.sh to use UIS (or accept it breaks until remote targets are implemented)
  2. Remove provision command from uis and uis.ps1 wrappers
  3. Evaluate and clean up scripts/packages/ folder
  4. Update all 6 documentation files
  5. Delete provision-host/kubernetes/

Investigation Questions​

  1. Can provision-host/kubernetes/ be deleted entirely? It's in git history if needed. Or tag a release first?
  2. Does ./uis provision legacy command still need to exist in uis-cli.sh?
  3. Are there references to provision-host/kubernetes/ in CI/CD workflows, Dockerfiles, or entrypoint scripts?
  4. The "how deployment works" page should go in advanced/ — users who just want to deploy don't need it, but anyone who wants to understand the system does.
  5. Cloud host docs are covered by INVESTIGATE: Remote Deployment Targets — not in scope here.

Scope​

This investigation will produce multiple plans, each tackling a different part:

Plan area: Rename "packages" to "services" — COMPLETED​

Implemented: PLAN-rename-packages-to-services (2026-03-17, PR #88)

Plan area: Delete old deployment system — COMPLETED​

Implemented: PLAN-delete-old-deployment-system (2026-03-17, PR #90)

Plan area: "How Deployment Works" documentation — COMPLETED​

Implemented: PLAN-how-deployment-works (2026-03-17)

Plan area: Documentation gap filling — COMPLETED​

Implemented: PLAN-documentation-gap-filling (2026-03-17)

Findings: CI/CD pipelines and generators documented in contributors/guides/ci-cd-and-generators.md. Integration testing documented in contributors/guides/integration-testing.md. Stack creation guide added to contributors/rules/kubernetes-deployment.md. Service override service-overrides/ directory removed — was never implemented. Getting-started path improved with deployment suggestions and cross-links.