> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/v1.4.0/portal/installation.md).

# Installation & Setup

## Prerequisites

### 1. Install Development Tools and required packages (Example for RHEL)

Before provisioning the AIDC-Portal VM, ensure the following software packages are installed on your system:

```bash
sudo dnf groupinstall "Development Tools" -y

# Required only on Rocky Linux
sudo dnf group install -y "virtualization hypervisor"
sudo dnf group install -y "virtualization tools"
sudo dnf config-manager --set-enabled crb

sudo dnf install -y qemu-kvm qemu-img virt-manager libvirt libvirt-client libvirt-devel virt-install ruby ruby-devel yum-utils
sudo systemctl enable --now libvirtd
sudo systemctl start libvirtd

sudo systemctl stop firewalld
sudo systemctl disable firewalld
```

### 1.5 Pre-check (One-click Environment Check)

Before running `vagrant up`, ensure the host environment is properly installed and running. You can use the following one-click script to verify the environment:

```bash
#!/bin/bash

echo "==== Check libvirt status ===="
sudo systemctl is-active --quiet libvirtd && echo "libvirtd: active" || echo "libvirtd: inactive"

echo "==== Check KVM modules ===="
lsmod | grep -E "kvm|kvm_intel|kvm_amd" >/dev/null && echo "KVM modules: loaded" || echo "KVM modules: not loaded"

echo "==== Check libvirt network ===="
virsh net-list --all

echo "==== Check vagrant-libvirt plugin ===="
vagrant plugin list | grep -q libvirt && echo "vagrant-libvirt: installed" || echo "vagrant-libvirt: not installed"

echo "==== Check Vagrant version ===="
vagrant --version
```

### 2. Add HashiCorp's official repository and install Vagrant (Example for RHEL)

```bash
# Install Vagrant (ensure version is after 2.3.0 stable)
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum install vagrant
sudo vagrant plugin install vagrant-libvirt
```

### 3. Obtain the aidc-portal.box File

Extract the aidc-portal.box file from the release package and place it in the same directory as the Vagrantfile.

### 4. Import the aidc-portal.box

If the AIDC-Portal box already exists, remove it before importing:

```bash
vagrant box remove aidc-portal
vagrant box add aidc-portal aidc-portal.box
```

***

## System Requirements

### AIDC Server Node (VM Resources)

**Host OS:**

* RHEL 8.8 (x86\_64)
* Rocky Linux 8.10 (x86\_64)

| Deployment Scale | Nodes    | CPU     | Memory | Storage |
| ---------------- | -------- | ------- | ------ | ------- |
| **Small**        | ≤ 50     | 4 cores | 32 GB  | 200 GB  |
| **Medium**       | 51 – 500 | 8 cores | 64 GB  | 500 GB  |
| **Large**        | 500+     | 8 cores | 128 GB | 500 GB  |

**Network (fixed for all scales):**

| NIC            | Speed | Purpose                                                                                        |
| -------------- | ----- | ---------------------------------------------------------------------------------------------- |
| Management NIC | 1 GbE | Internet access / License activation / Administrative operations / Communication with AIDC-CLI |

### Network Requirements

* The VM requires **one** bridged network interface:
  * **Management NIC (1 GbE):** Used for internet access, administrative operations, and communication with the AIDC-CLI system. This NIC must be on the same subnet as the CLI Interconnect NIC.

***

### Vagrantfile Configuration

```ruby
Vagrant.configure("2") do |config|
    # Define network variables
    external_ip      = "192.168.1.100"
    netmask_external = "255.255.255.0"

    # Management network (internet access / admin / CLI communication)
    aidc_portal.vm.network "public_network", ip: external_ip, netmask: netmask_external, dev: "enp3s0"

    ...(details omitted).

    # Libvirt provider configuration
    aidc_cli.vm.provider :libvirt do |v, override|
      v.memory = 32768
      v.cpus = 4
      v.connect_via_ssh = false
    end
  end
end
```

***

### Network Configuration Notes

* The Management NIC must be defined in the `Vagrantfile` with a bridged network adapter.
* The assigned IP must **not conflict** with any Host OS IP to avoid network issues.
* This NIC must be on the same subnet as the CLI Interconnect NIC.

### Resource Specifications

* Modify the `Vagrantfile` provider section to adjust resources based on deployment scale:

```ruby
# Small  (≤ 50 nodes):   memory = 32768,  cpus = 4
# Medium (51-500 nodes): memory = 65536,  cpus = 8
# Large  (500+ nodes):   memory = 131072, cpus = 8
v.memory = 32768
v.cpus = 4
```

***

## Usage - Initialize Vagrant environment

Start the VM:

```bash
sudo vagrant up
vagrant up
```

Set VM and network to autostart:

```bash
virsh autostart aidc-portal
virsh net-autostart vagrant-libvirt
```

## Hostname Mapping (Required)

After the VM is started, please add a hostname mapping on your client machine to ensure proper access to the AIDC Portal.

Update the hosts file on your operating system as follows:

**Linux / macOS**

```bash
/etc/hosts
```

**Windows**

```
C:\Windows\System32\drivers\etc\hosts
```

Add the following entry, replacing the IP address with the External Network IP of the AIDC Portal VM:

```
192.168.1.100   aidc.asus
```

This hostname mapping is required for accessing the AIDC Portal using the designated domain name.

## Access AIDC Portal

After completing the hostname mapping, you can now access the AIDC Portal through your web browser.

### Open Portal in Browser

Navigate to the following URL:

```
https://aidc.asus/aidc/portal
```

**Recommended Browsers:**

* Google Chrome
* Mozilla Firefox
* Microsoft Edge
* Safari

### Default Credentials

Use the following default credentials for initial login:

* **Username:** `admin`
* **Password:** `admin`

> **Security Note:** It is strongly recommended to change the default password after your first login for security purposes.

***

## Troubleshooting (vagrant up Failure Common Issues)

If `vagrant up` fails during the process, the common causes and solutions are listed below:

### 1. `libvirtd` not running or failed

**Symptom:** `failed to connect to libvirt` or `libvirtd is not running` **Solution:**

```bash
sudo systemctl enable --now libvirtd
sudo systemctl status libvirtd
```

***

### 2. KVM modules not loaded

**Symptom:** `kvm` related modules not found or VM fails to start **Solution:**

```bash
sudo modprobe kvm
```

***

### 3. `vagrant-libvirt` plugin missing or incompatible

**Symptom:** `provider 'libvirt' not found` **Solution:**

```bash
vagrant plugin install vagrant-libvirt
```

***

### 4. Network bridge not defined or IP conflict

**Symptom:** `vagrant up` stuck on network or IP assignment failure **Solution:**

* Verify the interface names (`internal_device`, `external_device`) in the Vagrantfile.
* Confirm `internal_ip` and `external_ip` do not conflict with host IPs.
* Check interface availability using `ip a` or `nmcli`.

***

### 5. Permission issue (mixing sudo and non-sudo)

**Symptom:** Using `sudo vagrant up` once and then `vagrant up` fails **Solution:**

* Use the same permission mode consistently.
* To reset, remove the `.vagrant` directory and rebuild:

```bash
sudo rm -rf .vagrant
vagrant up
```

***

### 6. Box file corrupted or download failed

**Symptom:** `box add` fails or `vagrant up` cannot load the box **Solution:**

* Re-download `aidc-portal.box`
* Verify file integrity (e.g., MD5 checksum)

***