This is documentation for Kamiwaza **0.7.0**, which is no longer actively maintained. For the current GA release, see [**1.0.1**](https://docs.kamiwaza.ai/).

Version: 0.7.0

## Overview
Kamiwaza supports offline installation for air-gapped RHEL environments where internet access is restricted or unavailable. The offline installer includes:

- **Pre-packaged NVM + Node.js** (version 22.11.0)
- **Frontend node_modules** (if available during build)
- **Docker images** (containerized services)
- **Python wheels** (pip dependencies)
- **System dependencies** (RPM packages)

These instructions have been tested for Kamiwaza Enterprise.

## Dependencies
The following dependencies are required:

- net-tools
- gcc-c++
- nodejs
- npm
- jq
- pkgconfig
- fontconfig-devel
- freetype-devel
- libX11-devel
- libXrender-devel
- libXext-devel
- libpng-devel
- libSM-devel
- pixman-devel
- libxcb-devel
- glib2-devel
- python3-devel
- libffi-devel
- gtk3-devel
- ca-certificates
- curl
- libcurl-devel
- cmake
- gnupg2
- iptables
- pciutils
- dos2unix
- unzip
- coreutils
- systemd
- wget
- make
- gcc
- openssl
- sqlite
- ncurses-libs
- readline
- libffi
- xz-libs
- expat
- tk
- zlib-devel
- bzip2-devel
- openssl-devel
- ncurses-devel
- sqlite-devel
- readline-devel
- tk-devel
- xz-devel
- expat-devel
- libuuid-devel
- yum-utils
- device-mapper-persistent-data
- lvm2
- git
- python3.12
- python3.12-pip
- python3.12-devel

For systems that can temporarily connect to the internet, these dependencies can be installed via the command:

```bash
sudo dnf install -y net-tools gcc-c++ nodejs npm jq pkgconfig fontconfig-devel freetype-devel libX11-devel libXrender-devel libXext-devel libpng-devel libSM-devel pixman-devel libxcb-devel glib2-devel python3-devel libffi-devel gtk3-devel ca-certificates curl libcurl-devel cmake gnupg2 iptables pciutils dos2unix unzip coreutils systemd wget make gcc openssl sqlite ncurses-libs readline libffi xz-libs expat tk zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel xz-devel expat-devel libuuid-devel yum-utils device-mapper-persistent-data lvm2 git python3.12 python3.12-pip python3.12-devel
```

## For Users: Installing Offline
### Step 1: Transfer Files to Target System
You should receive these files from your builder:

```text
kamiwaza_[version]_rhel9_x86_64.rpm     # Main installer package

kamiwaza-requirements-export.zip        # Additional dependencies (optional)
```

**Transfer Methods:**

- USB drive/removable media
- Secure file transfer (scp, rsync)
- Physical media delivery

### Step 2: Basic Installation
**IMPORTANT:** You must accept the Kamiwaza License Agreement to install Kamiwaza. By including `KAMIWAZA_ACCEPT_LICENSE=yes` in the installation command, you are agreeing to the Kamiwaza License Agreement.

To review the full license terms, visit: [https://www.kamiwaza.ai/license](/content/license/index.html)

```bash
# Install the RPM package. Add your Kamiwaza license key between the quotation marks.

sudo -E KAMIWAZA_ACCEPT_LICENSE=yes -E KAMIWAZA_LICENSE_KEY="" dnf install kamiwaza_[version]_rhel9_x86_64.rpm

# The installer will automatically detect offline mode and use bundled resources
```

**Tip:** While the installer says "Running scriptlet", use `sudo tail -f /var/log/kamiwaza-postinst-debug.log` to monitor logs.

### Step 3: Verification
```bash
kamiwaza start
```
The first time you run this command, it will take longer to start Kamiwaza as it does initial setup. Once it is starting, you can monitor its progress by running:

```bash
kamiwaza status
```
Once are all services are confirmed to be running, Kamiwaza is started.

#### Create a Fernet Key
If you are creating a fresh install and are on the head node / a single node run the following to create a Fernet key:

```bash
cd /opt/kamiwaza/kamiwaza && source venv/bin/activate

python -c "from kamiwaza.lib.util import generate_fernet_key; print(generate_fernet_key())" | sudo tee /opt/kamiwaza/kamiwaza/runtime/fernet.key > /dev/null
```
If you are on worker nodes, copy the key from the head node.

### Step 4: Extension Configuration (Offline builds)
Offline bundles include the Kamiwaza Extension Registry so App Garden extensions remain available without external connectivity. The installer appends the following defaults to `/opt/kamiwaza/kamiwaza/env.sh`—verify they match your environment:

| Variable | Typical offline value | Purpose |
| --- | --- | --- |
| `KAMIWAZA_EXTENSION_STAGE` | `LOCAL` | Forces the platform to serve extensions from the bundled registry |
| `KAMIWAZA_EXTENSION_LOCAL_STAGE_URL` | `file:///opt/kamiwaza/extensions/kamiwaza-extension-registry` | Points to the unpacked registry assets on disk |
| `KAMIWAZA_EXTENSION_INSTALL_PATH` | `/opt/kamiwaza/kamiwaza/extensions` | Destination directory for the registry archive |

If the builder omitted these entries (or they differ), edit `/opt/kamiwaza/kamiwaza/env.sh` and update the existing `export` lines rather than appending duplicates. One approach:

```bash
sudo nano /opt/kamiwaza/kamiwaza/env.sh
```

Ensure the file contains exactly one copy of each export:

```bash
export KAMIWAZA_EXTENSION_STAGE=LOCAL

export KAMIWAZA_EXTENSION_LOCAL_STAGE_URL="file:///opt/kamiwaza/extensions/kamiwaza-extension-registry"

export KAMIWAZA_EXTENSION_INSTALL_PATH="/opt/kamiwaza/extensions"
```
Restart Kamiwaza to load any environment edits:

```bash
sudo systemctl restart kamiwaza
```

### Step 5: Verify Extensions
Use the following checklist to confirm the bundled extensions are ready:

1. **Registry assets present**

```bash
ls /opt/kamiwaza/extensions/kamiwaza-extension-registry/garden/default/apps.json

jq '.apps | length' /opt/kamiwaza/extensions/kamiwaza-extension-registry/garden/default/apps.json
```

The `apps.json` file should exist and list the expected number of extensions.

2. **Extension services healthy**
Run `kamiwaza status` and confirm the extension sync service reports `RUNNING`. (In docker-compose deployments the service appears as `extension-sync`; in systemd-based installs it runs as `kamiwaza-extension-sync`.)

For container installs:

```bash
docker compose logs --tail=50 extension-sync
```

For systemd-managed installs:

```bash
sudo systemctl status kamiwaza-extension-sync

sudo journalctl -u kamiwaza-extension-sync --since "10 minutes ago"
```

Both modes also write to `/var/log/kamiwaza/extension-sync.log`.

3. **App Garden validation**
Sign in to the Kamiwaza UI, open **App Garden → Extensions**, and confirm the extension catalog appears without network access.

If any step fails, rerun the installer with the `--extension-path` option or reapply the registry archive, then repeat the verification steps above.

### File Locations
| Component | Installed Location | Purpose |
| --- | --- | --- |
| Main Application | `/opt/kamiwaza/` | Core application files |
| Configuration | `/opt/kamiwaza/kamiwaza/` | Runtime configuration |
| Data Storage | `/var/lib/kamiwaza/` | Models, databases, logs |
| Offline Resources | `/usr/share/kamiwaza/` | Bundled dependencies |
| Service Scripts | `/usr/bin/kamiwaza*` | Command-line tools |
| Log Files | `/var/log/kamiwaza/` | Application logs |

### Network Ports
| Service | Port | Purpose |
| --- | --- | --- |
| Web Interface | 3000 | Main UI |
| API Server | 8000 | REST API |
| Ray Dashboard | 8265 | Ray monitoring |
| Ray Client | 10001 | Ray cluster comm |
| Traefik | 80/443 | Reverse proxy |