# Documentation for Kamiwaza 0.13.0

This guide covers the standard installation of Kamiwaza on Red Hat Enterprise Linux 9 systems with internet access. This is the recommended installation method for most users.

**For air-gapped environments without internet access**, see the [Offline Installation Guide](https://docs.kamiwaza.ai/0.13.0/installation/redhat_offline_install). The offline installation is supported but requires additional preparation steps and is intended for restricted environments only.

These instructions have been tested for Kamiwaza Enterprise on RHEL 9.

## Prerequisites

Before installing Kamiwaza, ensure you have:

- **Red Hat Enterprise Linux 9** installed
- **Root or sudo access** to the system
- **Internet connectivity** for downloading packages and dependencies
- **Docker Engine** installed (see Step 2 below)

Review the full [System Requirements](https://docs.kamiwaza.ai/0.13.0/installation/system_requirements) for hardware, storage, and GPU requirements.

## Step 1: Install System Dependencies

Install the required system packages:

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

## Step 2: Install Docker

Docker is required to run Kamiwaza. Follow the official Docker installation guide for Red Hat Enterprise Linux:

**[Docker Installation for RHEL](https://docs.docker.com/engine/install/rhel/)**

The installation steps typically include:

1. Remove any older Docker versions:

```bash
   sudo dnf remove docker docker-client docker-client-latest docker-common \
        docker-latest docker-latest-logrotate docker-logrotate docker-engine \
        podman runc
   ```

2. Set up the Docker repository:

```bash
   sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
   ```

3. Install Docker Engine:

```bash
   sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

4. Enable and start Docker:

```bash
   sudo systemctl enable docker
   sudo systemctl start docker
   sudo chmod 666 /var/run/docker.sock
   ```

5. Verify Docker installation:

```bash
   docker --version
   docker compose version
   ```

## Step 3: Install the Kamiwaza RPM Package

Download and install the Kamiwaza RPM package for RHEL 9:

```bash
# Download the package
curl -LO https://packages.kamiwaza.ai/rpm/kamiwaza_v0.9.3_rhel9_x86_64.rpm
```

**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
# Option A: Install the package (Community Edition)
sudo -E KAMIWAZA_ACCEPT_LICENSE=yes dnf install ./kamiwaza_v0.9.3_rhel9_x86_64.rpm

# Option B: Install the package (Enterprise Mode with License Key)
sudo -E KAMIWAZA_ACCEPT_LICENSE=yes KAMIWAZA_LICENSE_KEY="YOUR_LICENSE_KEY_HERE" dnf install ./kamiwaza_v0.9.3_rhel9_x86_64.rpm
```

**Note:** Omit the `KAMIWAZA_LICENSE_KEY` option if you are installing the Community Edition without an enterprise license.

After the package is installed, run the production installation script.

> **Warning:** Avoid passing the admin password directly as a static CLI argument or an inline environment variable to prevent it from being saved in your shell history. Use `read -s` to securely prompt for the password and export it. Note that passing the exported variable to the installation script (`--admin-password "${KAMIWAZA_ADMIN_PASSWORD}"`) will still expose the password briefly in process lists (e.g., `ps aux`) while the script runs, but protects it from permanent shell logs.

```bash
# Run the production install script (online mode)
echo "Enter admin password for Kamiwaza:"

read -s KAMIWAZA_ADMIN_PASSWORD

export KAMIWAZA_ADMIN_PASSWORD

sudo -E /opt/kamiwaza/scripts/install-prod.sh --domain "your-configured-domain-or-ip" --admin-password "${KAMIWAZA_ADMIN_PASSWORD}" -y
```

The installer will automatically detect online mode and download required resources from the internet.

**Monitoring Installation Progress:**

While the installer runs, you can monitor the installation logs:

```bash
sudo tail -f /var/log/kamiwaza-postinst-debug.log
```

## Step 4: Configure System Environment Variables

After installation, configure Kamiwaza by editing `/etc/kamiwaza/env.sh` (enterprise edition - requires sudo access) or `/opt/kamiwaza/kamiwaza/env.sh` (community edition):

**Optional (for non-production systems only):**

On non-production systems where self-signed certificates or insecure TLS is acceptable, ensure existing variables are set as:

```bash
export AUTH_GATEWAY_TLS_INSECURE=true
export AUTH_REBAC_SESSION_ALLOW_INSECURE=true
```

> **Warning:** Do not use `AUTH_GATEWAY_TLS_INSECURE=true` in production environments.

## Step 5: Start and Verify Kamiwaza

Start the Kamiwaza service:

```bash
kamiwaza start
```

The first time you run this command, it will take longer to start as Kamiwaza performs initial setup and downloads required Docker images.

Monitor the startup progress:

```bash
kamiwaza status
```

Once all services show as running, Kamiwaza is ready to use.

**Access the Web Interface:**

Open your browser and navigate to the URL you configured in `KAMIWAZA_ORIGIN`:

```text
https://your-configured-domain-or-ip
```

## Step 6: Create Users

After installation, create administrator and standard-user accounts through the identity provider or supported administrative workflow used by your deployment.

Use the [Security Admin Guide](https://docs.kamiwaza.ai/0.13.0/security/admin-guide) for the recommended public-facing user-management model.

## File Locations

| Component          | Installed Location                       | Purpose                     |
| ------------------ | ---------------------------------------- | --------------------------- |
| Main Application    | `/opt/kamiwaza/`                        | Core application files      |
| Configuration       | `/opt/kamiwaza/kamiwaza/`              | Runtime configuration       |
| Environment Config  | `/etc/kamiwaza/env.sh`                  | System environment variables |
| Data Storage        | `/var/lib/kamiwaza/`                    | Models, databases, logs     |
| Service Scripts     | `/usr/bin/kamiwaza*`                    | Command-line tools          |
| Log Files           | `/var/log/kamiwaza/`                    | Application logs            |

## Network Ports

Ensure the following ports are accessible:

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

## Troubleshooting

### Docker Permission Errors

If you encounter permission errors when running Docker commands:

```bash
# Add your user to the docker group
sudo usermod -aG docker $USER
# Apply group membership (choose one):
newgrp docker          # Apply in current terminal session
# OR log out and back in
# OR reboot
# Verify group membership
groups | grep docker
```

### Installation Logs

If installation fails, check the logs:

```bash
sudo tail -100 /var/log/kamiwaza-postinst-debug.log
```

### Service Status

Check if the Kamiwaza service is running:

```bash
sudo systemctl status kamiwaza
```

### Restart Kamiwaza

If you need to restart the service:

```bash
kamiwaza stop
kamiwaza start
```