AAP Demo Quick Start

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.

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)
• Pull secret — download from the Red Hat console, then run:

mkdir -p ~/.aap-demo
cp ~/Downloads/pull-secret.txt ~/.aap-demo/pull-secret.txt

On Windows, the PowerShell launcher runs the maintained Bash CLI through Git for Windows. Windows deploys and AO/Product Demo enablement also require jq and a working Python runtime for shell wiring and demo provisioning. The Windows preflight installs them with winget when they are missing:

winget install --id jqlang.jq -e --source winget
winget install --id Python.Python.3.12 -e --source winget

Linux and macOS keep their existing prerequisite behavior; Python remains optional there when demo provisioning is not requested.

Install

git clone https://github.com/RedHatOfficial/aap-demo.git && cd aap-demo && ./install.sh && aap-demo deploy

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).

Cluster credentials live at ~/.aap-demo/kubeconfig.microshift and are not merged into ~/.kube/config. If you relied on the old default kubeconfig behavior, run:

export KUBECONFIG=~/.aap-demo/kubeconfig.microshift
# or: aap-demo kubeconfig   # refresh file and print export command

oc login writes into the kubeconfig named by KUBECONFIG. When that is the aap-demo file, the current context can switch to a remote cluster. Cluster commands then stop before they read or change that API, and tell you how to switch back to the microshift or aap-demo context. aap-demo kubeconfig refreshes the local file from the CRC VM. Set AAP_DEMO_ALLOW_REMOTE_KUBECONFIG=true only when that remote API is intentional.

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 ao-pr-testing  # PR validation workflow and read-only OpenShift MCP (requires AO)
aap-demo enable apme-eap     # Early Access Program only for APME
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_VERSION=2.7 aap-demo deploy  # Deploy AAP 2.7 (default)
AAP_VERSION=2.6 aap-demo deploy  # Deploy AAP 2.6

# 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
aap-demo trust-ca            # Fix ingress certificate trust without cluster repair

# 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/, 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
AAP_VERSION=2.7               # AAP version to deploy: 2.6 or 2.7
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
./install.sh --uninstall  # Remove aap-demo 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)