Install prerequisites with hyops setup¶

Purpose: Install workstation prerequisites required for HybridOps.Core execution.
Owner: Platform operations
Trigger: First-time install, new workstation, CI runner bootstrap, or dependency drift.
Impact: Missing tools prevent init targets and modules from executing.
Severity: P3
Pre-reqs: Ubuntu/Debian host with sudo access and internet connectivity.
Rollback strategy: Package removal follows OS package manager procedures; no platform state is modified.

Context¶

HybridOps.Core requires a small set of system tools for target initialisation and module execution. Installation is an explicit operator action and is not performed automatically by hyops preflight or hyops init.

Preconditions and safety checks¶

Confirm correct host and intended scope (workstation vs CI runner).
Confirm sudo is available and permitted for package installation.
Confirm outbound internet connectivity to OS repositories and vendor repositories.

Steps¶

1) Install base prerequisites
- Command:

hyops setup base --sudo

- Expected result: Base tools are installed or reported as already present.

2) Install cloud CLIs (optional)
- Azure:

hyops setup azure --sudo

- GCP:

hyops setup gcp --sudo

- Expected result: az and/or gcloud are available on PATH where installed.

3) Install Ansible Galaxy dependencies (runtime state)
- Command:

hyops setup ansible

- Expected result: Collections are installed under <root>/state/ansible/collections for the active runtime root.

4) Validate prerequisites
- Command:

hyops preflight --strict

- Expected result: Required checks pass; failures include remediation guidance.

Verification¶

hyops preflight --strict returns exit code 0.
hyops setup <scope> --report reflects expected versions and paths.

Troubleshooting¶

`hyops setup base --sudo` prompts repeatedly¶

Cause: sudo timestamp expired or multiple shells are invoking setup.
Remediation:
```
sudo -v
hyops setup base --sudo
```

`hyops setup azure --sudo` or `hyops setup gcp --sudo` succeeds but CLI not found¶

Cause: shell cache or PATH not refreshed.

Remediation:

hash -r
command -v az || true
command -v gcloud || true

`hyops setup ansible` installs collections but Ansible cannot find them¶

Cause: collections installed into runtime-managed directories but environment not configured.

Remediation:

export ANSIBLE_COLLECTIONS_PATH="$HOME/.hybridops/state/ansible/collections:${ANSIBLE_COLLECTIONS_PATH:-$HOME/.ansible/collections:/usr/share/ansible/collections}"
export ANSIBLE_ROLES_PATH="$HOME/.hybridops/state/ansible/roles:${ANSIBLE_ROLES_PATH:-$HOME/.ansible/roles:/etc/ansible/roles}"

Post-actions and clean-up¶

Standardise environment variables for configuration tooling execution where runtime-managed dependencies are used.
Record a baseline in change control where required.