> 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/latest/cli/commandreference/deploy.md).

# OS Deployment

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/08/21    |

## Table of Contents

* [1. Overview](#overview)
* [2. Subcommands](#subcommands)
* [3. Deployment Workflow](#deployment-workflow)
* [4. Usage Examples](#usage-examples)

***

## 1. Overview <a href="#overview" id="overview"></a>

{% hint style="warning" %}
**⚠️ Prerequisite: `aidc-cli init` required first**

This command depends on settings saved by [`aidc-cli init`](/guide/latest/cli/commandreference/init.md). Before running it, make sure you have completed:

* [`aidc-cli init inventory`](/guide/latest/cli/commandreference/init.md#inventory) — render the node inventory from `aidc.csv`
* [`aidc-cli init dhcp-set`](/guide/latest/cli/commandreference/init.md#dhcp-configuration) — configure the DHCP/PXE subnet
* [`aidc-cli init image-active`](/guide/latest/cli/commandreference/init.md#deploy-image-management) — select the active deploy image
* [`aidc-cli init bmc-set`](/guide/latest/cli/commandreference/init.md#bmc-configuration) — save the BMC credentials
* [`aidc-cli init swraid-set` / `lvm-set`](/guide/latest/cli/commandreference/init.md#disk-configuration) — optional: disk layout for installation

For the full setup sequence, see the [Getting Started](/guide/latest/cli/gettingstarted.md) guide.
{% endhint %}

The `deploy` command handles OS deployment via PXE boot, including DHCP service management, ISO image downloading, SSH access key distribution, and proxy configuration.

This module is primarily the **execution layer** for PXE deployment. In practice, it consumes values prepared earlier with `aidc-cli init`, especially DHCP settings, the active image, inventory rendering, and BMC defaults.

```bash
aidc-cli deploy <subcommand> [flags]
```

{% hint style="info" %}
See [Init.md §10.6](/guide/latest/cli/commandreference/init.md#deploy-image-management) for the authoritative, up-to-date list of operating systems `deploy install` can install.
{% endhint %}

***

## 2. Subcommands <a href="#subcommands" id="subcommands"></a>

### 2.1 `install` — Install OS via PXE

Triggers unattended OS installation on target nodes via PXE boot.

```bash
aidc-cli deploy install [-m <mode>]
```

| Flag     | Short | Required | Description                                          |
| -------- | :---: | :------: | ---------------------------------------------------- |
| `--mode` |  `-m` |     ❌    | Deployment mode: `stateful` (default) or `stateless` |

**Deployment modes:**

* `stateful` — Installs the OS to disk (default behavior).
* `stateless` — PXE-boots a live/rescue session instead of installing to disk. Useful for one-off diagnostics or rescue scenarios where no changes should be written to local disk.

**Pre-flight checks:**

* Validates CSV IPs against DHCP subnet configuration
* Prompts for confirmation if mismatches are detected
* Requires DHCP to be enabled and an active image to be set

{% hint style="info" %}
Typical prerequisite flow before `deploy install`:

1. `aidc-cli init inventory`
2. `aidc-cli init dhcp-set`
3. `aidc-cli init dhcp-validate`
4. `aidc-cli init image-downloadable` then `aidc-cli init image-download -x <index>` (select the image to download; skip for RHEL — see [Init.md §10](/guide/latest/cli/commandreference/init.md#deploy-image-management))
5. `aidc-cli deploy image-download`
6. `aidc-cli init image-discovery` then `aidc-cli init image-active -x <index>` (confirm the locally available image to deploy)
7. `aidc-cli deploy dhcp-enabled`
8. `aidc-cli deploy install --limit-hosts <targets>`
   {% endhint %}

***

### 2.2 `dhcp-enabled` — Enable DHCP Service

Starts and enables the DHCP service on the management node.

```bash
aidc-cli deploy dhcp-enabled
```

***

### 2.3 `dhcp-disabled` — Disable DHCP Service

Stops and disables the DHCP service. Useful after deployment is complete to prevent unintended PXE boots.

```bash
aidc-cli deploy dhcp-disabled
```

{% hint style="warning" %}
It is strongly recommended to disable the DHCP server after OS deployment is complete. Leaving DHCP enabled may cause unexpected PXE boots on newly connected machines in the network.
{% endhint %}

***

### 2.4 `image-download` — Download OS Image

Downloads the ISO for the image currently selected as the **active downloadable image**.

```bash
aidc-cli deploy image-download
```

{% hint style="info" %}
Select the active downloadable image first with `aidc-cli init image-download -x <index>` (see [Init.md §10.2](/guide/latest/cli/commandreference/init.md#deploy-image-management)) before running this command. RHEL images cannot be downloaded this way — upload the ISO manually instead.
{% endhint %}

***

### 2.5 `access-key` — Setup SSH Access Key

Distributes SSH public key to target nodes for passwordless access. This also enables integration of non-AIDC-deployed machines into the management scope.

```bash
aidc-cli deploy access-key [-f]
```

| Flag      | Short | Required | Description                                      |
| --------- | :---: | :------: | ------------------------------------------------ |
| `--force` |  `-f` |     ❌    | Force regenerate and overwrite existing SSH keys |

***

### 2.6 `proxy-enabled` — Enable Proxy

Configures proxy settings on target nodes for internet access. This is a one-way package retrieval proxy from the AIDC server.

```bash
aidc-cli deploy proxy-enabled
```

{% hint style="info" %}
The proxy allows target nodes to retrieve packages from the AIDC server when they do not have direct internet access.
{% endhint %}

***

## 3. Deployment Workflow <a href="#deployment-workflow" id="deployment-workflow"></a>

```mermaid
flowchart TD
    A["Render Inventory<br>init inventory"] --> B["Configure DHCP<br>init dhcp-set"]
    B --> C["Validate DHCP<br>init dhcp-validate"]
    C --> D["Select Active Image<br>init image-active"]
    D --> E["Set PXE Boot<br>bmc pxe-boot"]
    E --> F["Download Image<br>deploy image-download"]
    F --> G["Enable DHCP<br>deploy dhcp-enabled"]
    G --> H["Install OS<br>deploy install"]
    H --> I["Distribute SSH Keys<br>deploy access-key"]
    I --> J["Disable DHCP<br>deploy dhcp-disabled"]
```

***

## 4. Usage Examples <a href="#usage-examples" id="usage-examples"></a>

```bash
# Complete PXE deployment flow
aidc-cli deploy dhcp-enabled
aidc-cli deploy image-download
aidc-cli deploy install
aidc-cli deploy access-key
aidc-cli deploy dhcp-disabled

# Deploy on specific nodes
aidc-cli deploy install -l node01,node02

# Install OS to disk (stateful, default)
aidc-cli deploy install --mode stateful

# PXE-boot a live/rescue session without installing to disk (stateless)
aidc-cli deploy install --mode stateless

# Force overwrite SSH keys
aidc-cli deploy access-key -f
```