# Kamiwaza 0.11.0 Installation Guide

This guide covers a fresh Kamiwaza production install on a RHEL9 host using the packed prod RPM, offline wrap bundle, and `install-prod.sh`.

## Scope
This guide assumes:

- a fresh RHEL9 host  
- release artifacts have already been built  
- you are installing from the packaged offline artifacts, not from live repos  
- `install-prod.sh` is the entrypoint

## Inputs You Need
Before you start, decide these values:

- `DOMAIN`: external hostname for the install, for example `kamiwaza.example.com`  
- `ADMIN_PASSWORD`: initial admin password  
- release artifact location:
  - local directory, or  
  - `s3://<bucket>/<prefix>/`  
- offline image tags:
  - app/core/init-users tag  
  - frontend tag  
  - chainguard base/containers tag

## Required Artifacts
You need these files from the offline release:

- `kamiwaza-prod-*.x86_64.rpm`  
- `kamiwaza-helm.*.tar`  
- `kamiwaza-helm.sha256`  
- `kamiwaza-helm.asc`  
- `kamiwaza-tools-rpm.pub.gpg`

## Host Prerequisites
You need:

- `sudo` access on the RHEL9 host  
- `aws` CLI only if you are pulling artifacts from S3

## Step 1: Set Operator Variables
Fill in the variables for your release:
```bash
DOMAIN="kamiwaza.example.com"
ADMIN_PASSWORD="replace-me"
RELEASE_DIR="$HOME/kajiya-release"
APP_TAG="release-0.11.0"
FRONTEND_TAG="${APP_TAG}"
CONTAINERS_TAG="${APP_TAG}"
```

## Step 2: Retrieve Release Artifacts
If the release artifacts are already on disk, skip to Step 3.

Example S3 pull:
```bash
BUCKET="kajiya"
PREFIX="builds/offline/<timestamp_folder>"
mkdir -p "${RELEASE_DIR}"
cd "${RELEASE_DIR}"
aws s3 cp --recursive "s3://${BUCKET}/${PREFIX}/" .
```

## Step 3: Verify the Required Files Are Present
```bash
cd "${RELEASE_DIR}"
ls -1 \
  kamiwaza-prod-*.x86_64.rpm \
  kamiwaza-helm.*.tar \
  kamiwaza-helm.sha256 \
  kamiwaza-helm.asc \
  kamiwaza-tools-rpm.pub.gpg
```

## Step 4: Install the Prod RPM
```bash
sudo dnf install -y perl
sudo rpm -Uvh --replacepkgs ./kamiwaza-prod-*.x86_64.rpm
```

## Step 5: Stage the Wrap Bundle Files
```bash
sudo mkdir -p /opt/kamiwaza/prereqs
sudo cp ./kamiwaza-helm.*.tar ./kamiwaza-helm.sha256 ./kamiwaza-helm.asc \
  ./kamiwaza-tools-rpm.pub.gpg /opt/kamiwaza/prereqs/
```

## Step 6: Install Host Prerequisites
```bash
sudo /opt/kamiwaza/scripts/bootstrap-prereqs.sh \
  --embedded-root /opt/kamiwaza/prereqs \
  --os rhel
export HELM_PLUGINS="/usr/local/share/helm/plugins"
```

Sanity check the required tools:
```bash
ansible-playbook --version | head -n1
podman --version
kubectl version --client
helm version
helmfile version
helm dt version
```

## Step 7: Create the Optional Site Overrides File
Most installs can skip this step. Create the file only if you need non-default settings such as security banners, consent, ReBAC, or a non-prod template catalog stage.

Use this operator-facing path:
```bash
/opt/kamiwaza/cluster/values/overrides.yaml
```

Example:
```bash
sudo tee /opt/kamiwaza/cluster/values/overrides.yaml > /dev/null <<'EOF'
core:
  security:
    consent:
      enabled: true
    banner:
      enabled: true
      topText: "UNCLASSIFIED//TEST SYSTEM"
      topColor: "#00A651"
      bottomText: "UNCLASSIFIED//TEST SYSTEM"
      bottomColor: "#00A651"
  scheduler:
    extraEnv:
      - name: LICENSE_KEY
        value: "replace-with-license-key"
      - name: AUTH_REBAC_ENABLED
        value: "true"
      - name: AUTH_REBAC_BACKEND
        value: "postgres"
      - name: AUTH_REBAC_ALLOW_COMMUNITY_FALLBACK
        value: "true"
EOF
```

## Step 8: Export Offline Image Tags
Set the tags for the release you are installing:
```bash
export KAMIWAZA_VERSION="${APP_TAG}"
export KAMIWAZA_IMAGE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_APP_IMAGE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_INIT_KEYCLOAK_USERS_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_CORE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_FRONTEND_TAG="${FRONTEND_TAG}"
export KAMIWAZA_OFFLINE_CHAINGUARD_BASE_TAG="${CONTAINERS_TAG}"
```

## Step 9: Run the Offline Install
```bash
sudo -E /opt/kamiwaza/scripts/install-prod.sh \
  --offline \
  --skip-prereq-bootstrap \
  --domain "${DOMAIN}" \
  --admin-password "${ADMIN_PASSWORD}" \
  --wrap-bundle '/opt/kamiwaza/prereqs/kamiwaza-helm.*.tar' \
  --wrap-sha256 /opt/kamiwaza/prereqs/kamiwaza-helm.sha256 \
  --wrap-signature /opt/kamiwaza/prereqs/kamiwaza-helm.asc \
  --wrap-pubkey /opt/kamiwaza/prereqs/kamiwaza-tools-rpm.pub.gpg \
  -e helm_timeout=12m \
  -y
```

## Step 10: Verify the Install
```bash
kubectl get pods -n kamiwaza
kubectl -n kamiwaza get secret kamiwaza-user-admin \
  -o jsonpath="{.data.password}" | base64 -d; echo
curl -kI "https://${DOMAIN}"
```

## How Configuration Is Supplied
For this install path, configuration comes from three places:
1. `--domain`
2. `--admin-password`
3. the exported `KAMIWAZA_OFFLINE_*` tag vars plus `/opt/kamiwaza/cluster/values/overrides.yaml`

## Troubleshooting
### `aws: command not found`
Install AWS CLI or skip the S3 download step and stage the release artifacts locally.
### `no wrap chunk files matched glob`
Keep the `--wrap-bundle` argument quoted:
```bash
--wrap-bundle '/opt/kamiwaza/prereqs/kamiwaza-helm.*.tar'
```
### ReBAC session startup failure
If you enable `AUTH_REBAC_SESSION_ENABLED="true"`, you must also provide `AUTH_REBAC_SESSION_REDIS_URL`.
### Embedded prereq payload missing
If `/opt/kamiwaza/prereqs/rpms/` is missing after RPM install, verify that you installed the correct packaged prod RPM for the offline release.