AAP Demo Quick Start

v2 is a beta. This branch is the Python rewrite while it is still in development. It is not an official release. The supported release line remains main.

Deploy AAP to a local MicroShift cluster in minutes.

SECURITY NOTICE — DEVELOPMENT ENVIRONMENT ONLY

aap-demo is a LOCAL DEVELOPMENT tool and must NEVER be used in production.

Install

Python 3.9 or newer. While v2 is in development, install that branch directly. No checkout is required. pipx keeps the command isolated from the rest of your Python packages:

pipx install "git+https://github.com/RedHatOfficial/aap-demo.git@v2"

Pull the latest v2 commit the same way:

pipx install --force "git+https://github.com/RedHatOfficial/aap-demo.git@v2"

pip and uv install the same branch:

pip install "git+https://github.com/RedHatOfficial/aap-demo.git@v2"
uv tool install "git+https://github.com/RedHatOfficial/aap-demo.git@v2"

The publish workflow uploads this beta to PyPI as a .dev release so the aap-demo name is reserved. pip install aap-demo does not install a .dev release. Keep using the git URL above. pipx install aap-demo is the command after the 2.0.0 release. Check out v2 only if you are changing the code.

Replace the bash v1 command

./install.sh links ~/.local/bin/aap-demo to the bash script. pipx installs v2 at that same path, so move or remove the old command before installing v2.

Keep v1 available as aap-demo-v1:

mv ~/.local/bin/aap-demo ~/.local/bin/aap-demo-v1

Or remove the command. Cluster data is left in place:

rm -f ~/.local/bin/aap-demo \
  ~/.zsh/completions/_aap-demo \
  ~/.local/share/bash-completion/completions/aap-demo

If a bash aap-demo is still earlier on PATH after install, the first v2 command asks whether to uninstall it or rename it to aap-demo-v1. Choosing keep is remembered. Set AAP_DEMO_KEEP_BASH=1 to skip that prompt.

Download a pull secret from the Red Hat console. The CLI stores it at ~/.local/state/aap-demo/pull-secret.txt. Cluster credentials live at ~/.local/state/aap-demo/kubeconfig.microshift. Those files are not merged into ~/.kube/config.

mkdir -p ~/.local/state/aap-demo
cp ~/Downloads/pull-secret.txt ~/.local/state/aap-demo/pull-secret.txt
export KUBECONFIG=~/.local/state/aap-demo/kubeconfig.microshift
# or: aap-demo kubeconfig   # refresh file and print export command

aap-demo create provisions the MicroShift VM only. aap-demo deploy installs OLM and AAP (use deploy for the typical path; create alone is for cluster-only setup).

Prerequisites

• CRC (OpenShift Local) — Download
• 16 GB RAM minimum — default VM allocation is 16 GB (override with CRC_MEMORY=24576 aap-demo create for 24 GB). On Linux, aap-demo create prompts for optional temp swap on memory-constrained hosts (see scripts/README.md)

Status

aap-demo version       # Tool version, commit, and build timestamp
aap-demo status        # Show routes and credentials

AAP Demo Status
===============

Infra:       OpenShift Local (CRC)
Cluster:     running (crc-microshift)

Namespaces:
-----------
  aap-operator         27/29 pods   aap

AAP Deployments:
----------------
  https://aap-aap-operator.apps.127.0.0.1.nip.io

Credentials:
------------
  aap-operator: admin / <password>

Addons:
-------
  mcp-server      disabled
  portal          disabled
  portal-operator disabled (AMD64 only)
  setup-pah       disabled
  ao            disabled
  local-cache     disabled
  product-demos       disabled
  product-demo-satellite  disabled

Addons to add additional functionality

aap-demo enable              # List all addons
aap-demo enable portal       # Installs Automation Portal
aap-demo enable portal-operator # Installs Operator-based Portal (Technology Preview; AMD64 only)
aap-demo enable setup-pah     # Configures Private Automation Hub Credentials
aap-demo enable mcp-server   # MCP server for AI assistants
aap-demo enable ao           # Automation Orchestrator (GA; no aapctl required — see addons/ao/README.md)
aap-demo enable local-cache  # Caches AAP containers locally so you don't re-download after destroy/create

# Ansible Product Demos - Official demo content from ansible/product-demos
aap-demo enable product-demos        # Five domains at once (includes base; Satellite opt-in)
aap-demo enable product-demo-satellite  # Satellite demos (requires a Satellite server)
aap-demo disable addon_name  # Disables addon

The Windows wrapper currently defers Fleet and local image caching; those addons remain available through the Linux/macOS Bash workflow.

When destroying a running cluster, aap-demo destroy asks whether to save the container images locally. Confirming lets the next aap-demo deploy reuse the cached containers instead of downloading them again. Existing cached images are loaded automatically at the start of the next deploy.

Normal destroy/recreate flow:

aap-demo destroy   # answer y at the cache prompt
aap-demo create
aap-demo deploy     # automatically loads the saved cache

You do not need to run aap-demo enable local-cache load for this normal flow.

To manage the cache manually:

aap-demo enable local-cache load   # one-shot reload into fresh VM
aap-demo enable local-cache        # restore auto-load on future deploys

Common Commands

# Deployment
aap-demo deploy              # Deploy AAP 2.7

# Cluster management
aap-demo status              # Show cluster status, routes, credentials
aap-demo stop                # Stop the cluster
aap-demo start               # Start the cluster
aap-demo ssh                 # SSH into the cluster node
aap-demo watch               # Monitor deployment progress
aap-demo destroy             # Delete entire cluster

# AAP Operator Idle
aap-demo idle true           # Scale down AAP to save resources
aap-demo idle false          # Scale back up
aap-demo idle                # Check current idle state

# Troubleshooting
aap-demo diagnose            # Quick health check (cluster, storage, SCCs, pods)
aap-demo must-gather         # Collect full diagnostics (AAP + cluster)
aap-demo must-gather /tmp/d  # Collect to specific directory
aap-demo repair              # Fix after sleep/wake issues

# Maintenance
aap-demo clean               # Remove AAP deployment (keeps cluster)
aap-demo update              # Pull latest code and reinstall
aap-demo help                # Full command reference

Architecture

Architecture decisions are documented in docs/adr/ (14 ADRs covering CLI design, storage, OLM, addons, and cross-platform support).

macOS / Linux / Windows

• Networking: SSH (2222), API (6443), HTTP/HTTPS (443) — all on localhost
• Routes: *.apps.127.0.0.1.nip.io (nip.io DNS, no /etc/hosts needed)
• TLS: MicroShift's ingress CA auto-trusted on macOS keychain / Linux ca-trust; on Windows, run aap-demo deploy from an elevated PowerShell (see powershell/README.md)

Environment Variables

CRC_CPUS=8                   # VM CPU count (default: 8)
CRC_MEMORY=16384             # VM memory in MiB (default: 16384)
CRC_DISK=100                 # VM disk size in GiB (default: 100)
CRC_PV_SIZE=70               # Storage reserved for LVMS PVCs in GiB (default: 70, must be < CRC_DISK)
NAMESPACE=aap-operator       # Target namespace
QUIET=true                   # Suppress disclaimer

Troubleshooting

aap-demo diagnose      # Quick health check — finds common issues
aap-demo diagnose --ai # AI-powered analysis (requires claude CLI)
aap-demo must-gather   # Collect full diagnostics for support

On MicroShift 4.22+, aap-demo deploy relaxes container signature verification for registry.redhat.io inside the CRC VM so operator index images can pull. This is a demo-only workaround and must not be used as a production pattern.

Clean Up

aap-demo clean         # Remove AAP (keep cluster)
aap-demo destroy       # Delete everything
pipx uninstall aap-demo   # Remove the CLI

Documentation

• Full README — Complete documentation, architecture, troubleshooting
• Architecture Decision Records — Design decisions and rationale
• Contributing — Development guidelines
• Linting — Ansible linting setup

Versioning

Feature PRs do not need to change VERSION. Update it deliberately when preparing a release; CI only verifies that the checked-in value is valid semver. Development builds are also identified by the commit SHA and build timestamp shown by aap-demo version.

aap-demo version              # show current version + git build info
cz bump --increment PATCH     # after ./scripts/setup-linting.sh (optional)