Skip to content

Install prerequisites with hyops setup

Execution context: Run this procedure from a terminal where hyops --help succeeds. If HybridOps.Core is not installed, complete the Quickstart. For deployment support, use GitHub Discussions.

  • 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: A supported Linux host or Windows WSL2 distribution with sudo access, or macOS with Homebrew installed, plus 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).
  • On Linux or Windows WSL2, confirm sudo is available and permitted for package installation.
  • On Windows, use Ubuntu 24.04 under WSL2 and work from its Linux filesystem.
  • On macOS, confirm Homebrew is installed and run setup as the logged-in user.
  • Confirm outbound internet connectivity to OS repositories and vendor repositories.

Steps

Run one setup command for the intended platform:

hyops setup gcp
hyops setup azure
hyops setup proxmox

The command composes base setup, the selected provider tools and Galaxy dependencies. Proxmox does not install a cloud CLI. Linux and Windows WSL2 elevate system-level stages automatically. On macOS, Homebrew must be installed and setup runs as the logged-in user.

Use hyops setup <target> --verbose to stream the underlying installer output. Without --verbose, setup shows stage status and elapsed time and writes the full redacted output to its run record.

Expected result: base tools and selected provider CLIs are available on PATH. Collections are installed under <root>/state/ansible/galaxy_collections.

Refresh one pinned HybridOps collection without reinstalling every dependency:

hyops setup galaxy --collection helper --force

Valid collection names are common, helper, and app. Repeat --collection to refresh more than one.

Run strict preflight after setup:

hyops preflight --strict

Target setup prints its record root under <root>/logs/setup/<target>/. Each stage directory contains redacted output.log output and a structured result.json. No tee pipeline is required.

Verification

  • hyops preflight --strict returns exit code 0.
  • The setup run record reports status as ok and exit_code as 0.

Troubleshooting

hyops setup base --sudo prompts repeatedly

  • Cause: sudo timestamp expired or multiple shells are invoking setup.

  • Remediation:

    sudo -v hyops setup base --sudo

macOS reports that Homebrew is required

  • Cause: Homebrew is not installed or is not on PATH.

  • Remediation: install Homebrew from https://brew.sh, open a new terminal, and run:

    hyops setup base hyops setup gcp

Provider setup succeeds but the CLI is not found

  • Cause: shell cache or PATH not refreshed.

  • Remediation:

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

hyops setup galaxy 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/galaxy_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}"

  • Note: HybridOps runtime commands also derive collection roles/ directories from ANSIBLE_COLLECTIONS_PATH and add them to ANSIBLE_ROLES_PATH as a fallback. This protects remote include_role execution when ansible-core resolves collection roles inconsistently across SSH-backed plays.

  • Note: HybridOps runtime commands prefer the bundled core collection payload ahead of cached Galaxy copies under runtime state. This keeps shipped runtime content authoritative when local collection caches still contain older releases.

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.

References