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:

``` text
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`:

``` bash
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:

``` yaml
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:

``` bash
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:

``` bash
/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:

``` bash
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:

``` bash
/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:

``` yaml
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:

``` bash
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:

``` bash
/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:

``` bash
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:

``` bash
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:

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

Then refresh shell command discovery:

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

Expected product version:

``` text
3.3.0rc8
```

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

## 8. Configure AIM

Edit the installed controller configuration:

``` bash
sudoedit /etc/ansible/scripts/aim.yml
```

At minimum review:

``` yaml
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:

``` text
/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:

``` bash
aimctl capabilities
```

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

Then inspect the installed documentation:

``` text
/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:

``` bash
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:

``` text
<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:

``` text
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:

``` bash
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:

``` yaml
addons:
  execution_enabled: true

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

The public integration boundary is:

``` text
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:

``` text
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:

``` text
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:

``` text
/var/backups/aim-core/
```

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

``` bash
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