# Kamiwaza Installation Guide 0.13.0

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

It is the administrator-facing install path for current offline release artifacts. For field-by-field analysis and internal background, see `docs/install-config_final.md`.

For the exact smoke-tested install flow used on `rhel-install`, see `docs/rhel9-offline-prod-install-smoke.sh`. It defaults to a direct host-side S3 pull from the latest `release-0.12.1` builds, the tested `release-0.12.1` tags, and `AUTH_REBAC_SESSION_ENABLED=false`, but you can override those via env vars.

## 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

> **Note:** The RHEL offline install flow now includes `dnsmasq` alignment and natively supports App Garden extension traffic routing out-of-the-box (per the 0.12.1 release).

## 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

For many releases, all three tag groups use the same value. Do not assume that; confirm from release metadata for the build you are installing.

Historical site config blocks often include many values that are now derived from `--domain`, carried by chart defaults, or no longer used in the packaged Kubernetes install path. This guide only carries forward the fields that still need administrator input.

## 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

The packaged prereq payload now includes the supported RHEL9 bootstrap path. Use `/opt/kamiwaza/scripts/bootstrap-prereqs.sh --embedded-root /opt/kamiwaza/prereqs` after the prod RPM and wrap assets are staged.

## 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.12.1"

FRONTEND_TAG="${APP_TAG}"

CONTAINERS_TAG="${APP_TAG}"
```

If your release uses different frontend or container tags, set them explicitly. If your artifacts are already staged locally, set `RELEASE_DIR` to that path.

## 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 administrator-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}"
```

These exported vars cover the current offline app/frontend/container tag paths for the packaged release flow.

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

Keep the `--wrap-bundle` glob quoted exactly as shown.

## 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}"
```

What this confirms:
- the Kamiwaza namespace came up
- the admin password secret was created
- the external hostname is reachable

## How Configuration Is Supplied

For this install path, configuration comes from three places:
1. `--domain`

This sets the external domain and the domain-derived URLs used by the chart.

2. `--admin-password`

This seeds the `kamiwaza-user-admin` secret and the initial admin user setup.

3. the exported `KAMIWAZA_OFFLINE_*` tag vars plus `/opt/kamiwaza/cluster/values/overrides.yaml`

Keep the exported `KAMIWAZA_OFFLINE_FRONTEND_TAG` and `KAMIWAZA_OFFLINE_CHAINGUARD_BASE_TAG` values when a release uses split frontend/container tags. Use the values file only for site-specific non-default settings.

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