Ansible/scripts/docs/INSTALLATION.md

AIM Fresh Installation

Applies to: AIM 3.3.0rc8
Canonical Ansible Core: 2.19.11
Default controller root: /etc/ansible
Supported AIM Python: Python 3.11+

This guide is for a new AIM controller with no existing AIM source tree. It installs the complete source bundle, AIM's Python runtime dependencies, the separate canonical Ansible runtime, and the required Ansible collections.

The AIM deployer deliberately does not install operating-system packages, Python dependencies, Ansible, collections, accounts, groups, services, or add-on executors. Provision those explicitly, then use the bundled deployer in install mode.

AIM remains usable as a standalone product through the built-in aim terminal. Add-on execution is optional and disabled by default.

1. Obtain and verify the release

Transfer both files through a trusted channel:

AIM-Ansible-3.3.0rc8.zip
AIM-Ansible-3.3.0rc8.zip.sha256

The SHA-256 sidecar verifies file integrity; it is not a publisher signature.

Stage the release outside /etc/ansible:

cd /var/tmp
sha256sum -c AIM-Ansible-3.3.0rc8.zip.sha256
unzip AIM-Ansible-3.3.0rc8.zip
cd aim-core-3.3.0rc8

Do not extract the release directly over /etc/ansible.

2. Provision the controller prerequisites

The controller needs:

• Linux
• Python 3.11 or newer for AIM
• a separate Ansible runtime containing exactly ansible-core==2.19.11
• the collections declared by requirements.yml
• an operator-approved execution/service account and group policy
• network and remote authentication prerequisites appropriate to the managed systems

For the default configuration shipped in this release, review scripts/aim.yml before installation. In particular, these values are environment-specific and must not be accepted blindly:

root_dir: /etc/ansible
service_user: svc_bf-ansible
required_group: srv_debsansible01_admins@bitformer.lan

Set them to the intended controller values after installation, or prepare a reviewed configuration before first operational use.

3. Create the AIM Python environment

Keep AIM's Python environment separate from the canonical Ansible runtime and from add-on environments.

Example:

sudo python3.11 -m venv /opt/aim/venv
sudo /opt/aim/venv/bin/python -m pip install --upgrade pip
sudo /opt/aim/venv/bin/python -m pip install \
  'ruamel.yaml>=0.18,<0.19' \
  'rich>=13,<15'

Verify it:

/opt/aim/venv/bin/python --version
/opt/aim/venv/bin/python -c 'import ruamel.yaml, rich; print("AIM dependencies OK")'

The deployer uses this interpreter for the aim and aimctl launchers. It does not install or upgrade these dependencies itself.

4. Create the canonical Ansible runtime

AIM 3.3.0rc8 is qualified against ansible-core 2.19.11.

One clean layout is a separate virtual environment:

sudo python3.11 -m venv /opt/ansible/venv
sudo /opt/ansible/venv/bin/python -m pip install --upgrade pip
sudo /opt/ansible/venv/bin/python -m pip install 'ansible-core==2.19.11'

Verify the exact version:

/opt/ansible/venv/bin/ansible-playbook --version

The first version line must report Ansible Core 2.19.11.

Do not silently substitute a newer Ansible Core release.

5. Install the required Ansible collections

The source bundle declares:

collections:
  - ansible.netcommon
  - name: ansible.windows
    version: ">=3.8.0,<4.0.0"
  - ansible.posix
  - community.windows
  - community.general
  - sophos.sophos_firewall
  - pfsensible.core

Install them with the canonical Ansible runtime:

sudo /opt/ansible/venv/bin/ansible-galaxy collection install \
  -r requirements.yml

AIM 3.3.0rc8 requires ansible.windows>=3.8.0,<4.0.0 for native reboot-state discovery. Other collection versions remain operator-approved and must be compatible with Ansible Core 2.19.11. AIM does not download or upgrade collections during source deployment.

Verify collection discovery:

/opt/ansible/venv/bin/ansible-galaxy collection list

If collections are installed into a nonstandard path, configure runtime.ansible_collections_path in scripts/aim.yml after installation.

6. Preview the fresh installation

For a fresh controller use install, not update.

The default installation root is /etc/ansible, and the default launcher directory for a fresh installation is /usr/local/bin.

Run a dry-run first:

sudo python3 deploy/deploy.py install \
  --aim-python /opt/aim/venv/bin/python \
  --dry-run

Review the complete plan. It should show source installation under /etc/ansible and creation of the aim and aimctl launchers.

If using a nondefault controller root, provide both an explicit target and a dedicated command directory:

sudo python3 deploy/deploy.py install \
  --target /srv/aim-controller \
  --bin-dir /usr/local/libexec/aim-controller \
  --aim-python /opt/aim/venv/bin/python \
  --dry-run

Do not use a production launcher directory for a second development/test installation.

7. Apply the installation

For a genuinely fresh tree there should be no active AIM jobs, but the deployer still requires explicit acknowledgement that source writers/runners are quiesced:

sudo python3 deploy/deploy.py install \
  --aim-python /opt/aim/venv/bin/python \
  --apply \
  --quiesced

Then refresh shell command discovery:

hash -r
command -v aim
command -v aimctl
aim --version
aimctl --version

Expected product version:

3.3.0rc8

The deployer verifies the installed launchers and source before reporting success.

8. Configure AIM

Edit the installed controller configuration:

sudoedit /etc/ansible/scripts/aim.yml

At minimum review:

root_dir: /etc/ansible
service_user: <approved execution account>
required_group: <approved local/NSS group>

runtime:
  ansible_playbook: /opt/ansible/venv/bin/ansible-playbook
  ansible_collections_path: ""
  private_key_owner: ""

addons:
  execution_enabled: false

Keep addons.execution_enabled: false until add-on/service execution has been deliberately provisioned and accepted.

runtime.private_key_owner affects newly generated keys only. It does not switch the execution UID, migrate existing keys, or grant filesystem access.

Checkmk-specific controller settings under maintenance.checkmk_agent should be configured only when that functionality is required.

9. Establish inventories and customer data

A fresh source installation does not create production inventories, Vault data, SSH keys, customer credentials, or customer-local configuration.

The standard controller layout is:

/etc/ansible/
├── scripts/
│   ├── aim.yml
│   └── ...
├── playbooks/
├── roles/
├── inventories/
└── requirements.yml

Customer inventories, Vault files, keys, and .aim.yml files are runtime/operator data and are intentionally absent from the release archive.

Create or migrate them through the approved AIM/operator workflow. Never copy credentials into the source release or documentation.

10. Verify Core discovery

Run:

aimctl capabilities

Confirm that the product/API information is correct and that expected capabilities are advertised.

Then inspect the installed documentation:

/etc/ansible/scripts/docs/README.md
/etc/ansible/scripts/docs/SANITY.md
/etc/ansible/scripts/docs/VALIDATION.md

VALIDATION.md records release-development evidence. It is not proof that this newly installed controller has passed managed-host acceptance.

11. Verify controller staging

Before service/add-on execution, check controller-local Ansible staging:

aimctl staging-check

For a normal interactive/native installation, AIM checks the relevant controller staging paths.

For a hardened service executor, run this check inside the actual service sandbox under the real execution identity. A successful sudo -u shell test does not reproduce systemd mount restrictions.

With native defaults, both of these may matter:

<process HOME>/.ansible/tmp
<execution account passwd/NSS home>/.ansible/tmp

If the service uses ProtectHome=read-only, retain that hardening and add only the narrow writable exception required for the private staging directory. Do not make the whole home writable, recursively change ownership, or disable service hardening.

See:

scripts/docs/EXECUTOR_STAGING.md

12. Test the built-in terminal first

AIM is an independent product. Validate the native terminal before introducing an add-on:

aim

Use a controlled test customer/host and follow scripts/docs/SANITY.md.

Confirm inventory discovery, credentials/Vault handling, target selection, and an approved low-risk playbook before broader production use.

13. Optional add-on/service execution

Add-on execution is disabled by default.

Only after the controller and executor identity have been accepted should the operator deliberately enable it:

addons:
  execution_enabled: true

runtime:
  ansible_playbook: /opt/ansible/venv/bin/ansible-playbook

The public integration boundary is:

aim.services.v1
aimctl

Do not have an add-on:

• import aim.ui
• parse AIM terminal output
• patch Core
• rewrite native Ansible commands
• read/export private keys
• invent its own inventory hierarchy or target outcomes
• reconstruct structured operation results from debug/stdout

The current add-on contracts are documented in:

scripts/docs/ADDON_API.md
scripts/docs/ADDON_SUPPORT.md
scripts/docs/OPERATION_RESULTS.md
ADDON_AGENTS.md

The v1 execution profile is same-UID. Cross-UID execution is not provided by this release.

14. Run the controller acceptance checklist

Use the current checklist:

scripts/docs/SANITY.md

For 3.3.0rc8, acceptance should include the structured operation-result path in addition to ordinary execution.

A useful first reporting test is host-role detection. Confirm that the final result exposes the declared structured capability booleans without requiring the client to parse task output.

Also exercise, as applicable:

• inventory hierarchy
• target outcome summaries
• controller staging
• summary and detail progress
• disk-usage reporting
• service recovery reporting
• Checkmk reporting
• Linux/Windows patch reporting
• successful and mixed-result multi-host runs

Do not promote a release candidate based only on source parsing or local simulated callback tests.

15. Recovery

Fresh installation still creates protected deployment recovery data. The deployer prints its exact recovery directory under the default:

/var/backups/aim-core/

If installation validation fails, use the same release deployer and printed recovery directory:

sudo python3 deploy/deploy.py rollback \
  --from-backup /var/backups/aim-core/RECOVERY-DIRECTORY \
  --dry-run

sudo python3 deploy/deploy.py rollback \
  --from-backup /var/backups/aim-core/RECOVERY-DIRECTORY \
  --apply \
  --quiesced

A source rollback does not reverse remote Ansible work, dependency installation, account/group changes, or add-on state.

Fresh-install completion checklist

A fresh controller is not complete merely because aim --version works. Before production use confirm:

• release ZIP checksum verified
• AIM Python 3.11+ environment provisioned
• AIM Python dependencies installed
• canonical Ansible Core 2.19.11 provisioned separately
• required Ansible collections installed and discoverable
• full source installed with deploy.py install
• aim and aimctl resolve to the intended installation
• scripts/aim.yml reviewed for this controller
• approved execution identity/group configured
• inventory/Vault/key data established separately
• aimctl capabilities succeeds
• aimctl staging-check succeeds in every execution context
• built-in terminal workflow accepted
• managed-host sanity tests completed
• add-on execution remains disabled unless separately provisioned and accepted
• recovery location recorded and protected

Related documentation

• existing root README.md --- operator-owned and preserved; AIM does not overwrite it
• deploy/README.md --- deployment and rollback mechanics
• scripts/docs/README.md --- current documentation index
• scripts/docs/SANITY.md --- controller acceptance checklist
• scripts/docs/VALIDATION.md --- release-development evidence and limits
• scripts/docs/EXECUTOR_STAGING.md --- hardened executor staging requirements
• scripts/docs/ADDON_API.md --- public add-on API
• scripts/docs/ADDON_SUPPORT.md --- current add-on support matrix
• scripts/docs/OPERATION_RESULTS.md --- structured operation-result contract
• scripts/docs/PLAYBOOKS.md --- catalog/playbook behavior
• scripts/docs/CHECKMK.md --- Checkmk-specific behavior