Skip to content

Install and initialise HybridOps.Core

  • Purpose: Install hyops, install prerequisites where required, initialise local runtime state, and validate workstation readiness for HybridOps.Core execution. Owner: Platform operations

  • Trigger: New installation, upgrade to a new release, or workstation rebuild.

  • Impact: Until completed, init targets and modules cannot be executed reliably.

  • Severity: P3 Pre-reqs: HybridOps.Core release package (.tar.gz), sudo access for optional system install and setup steps, and internet connectivity for prerequisite installation.

  • Rollback strategy: Remove hyops wrapper/binary and remove ~/.hybridops/ runtime state.

Context

HybridOps.Core is delivered as a versioned release package.

  • install.sh installs the runtime under ~/.hybridops/core/ and provides a runnable hyops command.
  • pkg/build_release.sh and pkg/verify_release.sh are the source-side release bundle path for building and validating that package before publication.
  • hyops setup installs system prerequisites as an explicit operator action.
  • hyops preflight checks prerequisite presence and target readiness without modifying the system.
  • hyops init <target> initialises target credentials and readiness markers.
  • hyops show ... gives a read-only operator view over init markers, module state, and environment posture.
  • hyops test role ... runs collection role smoke tests through the runtime instead of an ad-hoc local harness.

Long-form reference and contracts are published on the docs site; the runtime ships command discovery via --help.

Preconditions and safety checks

  • Confirm operation on the intended workstation and user account.
  • Confirm the release package version matches the intended environment.
  • Verify package integrity (checksum/signature) where provided.
  • Confirm sudo is available for optional steps:
  • /usr/local/bin/hyops system wrapper (optional)
  • hyops setup <scope> --sudo prerequisites installation (optional)

Steps

1) Verify the release package

If a checksum file is provided:

sha256sum -c hybridops-core-<version>.tar.gz.sha256

If no checksum is provided, record the observed checksum:

sha256sum hybridops-core-<version>.tar.gz

Expected result: checksum verification passes or checksum is recorded.

2) Extract the release package

mkdir -p ~/downloads/hybridops
cd ~/downloads/hybridops
tar -xzf hybridops-core-<version>.tar.gz
cd hybridops-core-<version> 2>/dev/null || cd hybridops-core

Expected result: extracted directory contains install.sh and tools/setup/.

3) Install hyops

Default installation:

  • Runtime payload: ~/.hybridops/core/app
  • Runtime venv: ~/.hybridops/core/venv
  • User wrapper: ~/.local/bin/hyops
  • Optional system wrapper: /usr/local/bin/hyops
  • Installed blueprint payload under ~/.hybridops/core/app/blueprints/ is hardened read-only; operator edits belong under ~/.hybridops/envs/<env>/config/blueprints/ via hyops blueprint init
  • Durable module inputs belong under ~/.hybridops/envs/<env>/config/modules/ and can be materialized with hyops module init

Run:

./install.sh

Optional flags:

  • --force removes existing runtime payload and venv under the install prefix before reinstalling.
  • --no-system-link skips installing /usr/local/bin/hyops.
  • --setup-all runs tools/setup/setup-all.sh after installing the runtime (requires sudo).

Examples:

./install.sh --force
./install.sh --force --no-system-link
./install.sh --force --setup-all

Expected result: hyops is installed and executable.

4) Confirm hyops is available

command -v hyops
hyops --version
hyops --help

If hyops is installed to ~/.local/bin and not found, add it to the shell profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
. ~/.bashrc
command -v hyops

Expected result: command -v hyops returns a path.

If prerequisites were not installed via install.sh --setup-all, run the required setup scopes explicitly:

hyops setup base --sudo
hyops setup ansible

Optional cloud CLIs:

hyops setup azure --sudo
hyops setup gcp --sudo

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

6) Create runtime layout and validate preflight

Create the runtime layout on first use:

hyops preflight

Run strict preflight where appropriate:

hyops preflight --strict

Expected result: required checks pass; failures include remediation guidance.

7) Initialise required targets

Initialise only the targets required for the intended module set.

Examples:

hyops init proxmox
hyops init terraform-cloud

For targets that require vault access, ensure a password provider is available (see runbook references) and run init with a password source.

Expected result: readiness markers are created under ~/.hybridops/meta/ and run records are written under ~/.hybridops/logs/init/.

Optional state-backed inspection:

hyops show init --env dev
hyops show env --env dev

Optional role smoke command discovery:

hyops test role --help

Verification

Installation is complete when all of the following are true:

  • hyops is installed and discoverable on PATH.
  • hyops preflight completes successfully for the intended scope.
  • Required init targets are marked ready (for example ~/.hybridops/meta/proxmox.ready.json).

Post-actions and clean-up

  • Capture installation version, runtime root, and validation run records in onboarding/change records.
  • Confirm target-specific init runbooks are completed for required providers.
  • Ensure operator shell profile includes the intended hyops path and does not shadow with stale installations.

Uninstall / rollback

Remove installed wrappers:

rm -f ~/.local/bin/hyops
sudo rm -f /usr/local/bin/hyops 2>/dev/null || true

Remove runtime payload and state (destructive):

rm -rf ~/.hybridops

References