Metadata-Version: 2.4
Name: niceos-installer
Version: 2.2
Summary: Installer code for NiceOS
Home-page: https://niceos.ru
Author: NiceSOFT
Author-email: niceos@ncsgp.ru
License: Apache-2.0 OR GPL-2.0-only
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-Apachev2
License-File: LICENSE-GPL2.0
License-File: NOTICE-Apachev2
License-File: NOTICE-GPL2.0
Requires-Dist: Requests
Requires-Dist: pyOpenSSL
Requires-Dist: pyYAML
Requires-Dist: jc
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NiceOS Installer and Image Builder

`niceos-installer` is the NiceOS operating system installer package. It provides the interactive installer, ISO/initrd builder tooling, and optional KS-driven image factory tooling for preparing ready-to-use machine images.

The package is designed for NiceOS build hosts, installation media, automated image pipelines, and administrator-controlled image preparation workflows.

## Components

The project may be installed as one package or split into functional subpackages:

| Package | Purpose |
| --- | --- |
| `niceos-installer` | Base Python installer and core runtime modules. |
| `niceos-installer-iso-builder` | ISO/initrd builder for manual installation media. |
| `niceos-installer-image-factory` | KS-driven image factory for ready machine images. |
| `niceos-installer-image-factory-guestfs` | Optional guestfs helpers for rootfs/container extraction. |

## Main commands

| Command | Purpose |
| --- | --- |
| `niceos-installer` | Runs the NiceOS installer. |
| `niceos-iso-builder` | Builds installation ISO/initrd artifacts and image factory outputs. |
| `create-image-util` | Lower-level KS-driven image creation helper. |
| `niceos-create-image` | NiceOS-friendly alias for `create-image-util`. |
| `niceos-image-factory` | Operator-friendly alias for the image factory helper. |

Legacy compatibility commands may still exist when the Python packaging metadata installs them, but new automation should use the NiceOS command names.

## ISO builder vs image factory

NiceOS distinguishes two different workflows.

### ISO/initrd builder

The ISO builder creates bootable installation media intended for manual or semi-automated installation.

Typical outputs:

- `initrd.img`
- bootable ISO
- ISO-local RPM repository
- boot assets
- optional compliance metadata

Typical command:

```bash
niceos-iso-builder \
  -f build-iso \
  -v 5.2 \
  -a /DATA/niceos/images/iso \
  -R /DATA/niceos/repo/5.2 \
  --manifest \
  --sbom spdx \
  --sbom cyclonedx \
  --gost \
  --provenance
```

### KS-driven image factory

The image factory creates already installed machine images directly from installer KS/config YAML files.

This is the correct workflow for images prepared by administrators for virtualization platforms and cloud environments. It does not convert an ISO into a disk image. The KS/config YAML file is the source of truth for disks, partitions, packages, scripts, additional files, and image-specific variables.

Typical outputs:

- `raw`
- `qcow2`
- `vmdk`
- `vhdx` / Hyper-V
- `ova`
- Proxmox helper bundle
- rootfs/container bundle when optional guestfs tooling is installed

Typical command:

```bash
niceos-iso-builder \
  -f build-image \
  -v 5.2 \
  -k /DATA/src/niceos-os-installer/examples/ami/ami_ks.yaml \
  --niceos-installer-path /DATA/src/niceos-os-installer \
  --image-flavor ami \
  --image-local-repo-path /DATA/niceos/repo/5.2 \
  --outputs raw,qcow2,vmdk,proxmox \
  --artifact-path /DATA/niceos/images/ami
```

## KS/config YAML expectations

A KS/config YAML file for image factory builds should define at least:

- disk layout;
- default output disk filename;
- package list file;
- package set;
- Linux flavor if applicable;
- post-install scripts if needed;
- additional files if needed.

The image factory reads the KS/config YAML and delegates the actual image creation to the installer image pipeline. Output conversion is performed after the base raw image is created.

## Multi-output examples

### RAW only

```bash
niceos-iso-builder \
  -f build-image \
  -v 5.2 \
  -k ami_ks.yaml \
  --niceos-installer-path /DATA/src/niceos-os-installer \
  --image-local-repo-path /DATA/niceos/repo/5.2 \
  --outputs raw \
  --artifact-path /DATA/niceos/images/raw
```

### RAW + QCOW2 + VMDK

```bash
niceos-iso-builder \
  -f build-image \
  -v 5.2 \
  -k ami_ks.yaml \
  --niceos-installer-path /DATA/src/niceos-os-installer \
  --image-local-repo-path /DATA/niceos/repo/5.2 \
  --outputs raw,qcow2,vmdk \
  --artifact-path /DATA/niceos/images/multi
```

### Proxmox template bundle

```bash
niceos-iso-builder \
  -f build-image \
  -v 5.2 \
  -k proxmox_ks.yaml \
  --niceos-installer-path /DATA/src/niceos-os-installer \
  --image-local-repo-path /DATA/niceos/repo/5.2 \
  --outputs qcow2,proxmox-template \
  --artifact-path /DATA/niceos/images/proxmox \
  --proxmox-vm-id 9000 \
  --proxmox-storage local-lvm \
  --proxmox-bridge vmbr0 \
  --proxmox-memory 2048 \
  --proxmox-cores 2
```

Expected Proxmox artifacts:

```text
niceos-5.2-proxmox.qcow2
niceos-5.2-proxmox-cloudinit.yaml
niceos-5.2-proxmox-import.sh
```

The import script is intentionally not executed automatically. Operators should review it before running it on a Proxmox VE node.

## Compliance and manifest-first build

The builder can generate compliance metadata for enterprise release workflows:

```bash
--manifest
--sbom spdx
--sbom cyclonedx
--gost
--sign
--provenance
--security-gate off|warn|strict
```

Compliance artifacts may include:

- build manifest;
- RPM package manifest;
- source manifest;
- license manifest;
- repository snapshot;
- SPDX SBOM;
- CycloneDX SBOM;
- SHA256/SHA512 checksums;
- GOST R 34.11-2012 checksums when supported by the host crypto provider;
- build provenance;
- CVE/security gate status.

When building ISO media, compliance metadata may be embedded into the ISO under `niceos-compliance/` and also written next to the final artifact.

## Runtime dependencies

The base installer requires Python and installer runtime tools. The image factory additionally requires Docker and `qemu-img`.

Recommended split:

```bash
tdnf install niceos-installer
tdnf install niceos-installer-iso-builder
tdnf install niceos-installer-image-factory
```

For rootfs/container extraction from existing disk images:

```bash
tdnf install niceos-installer-image-factory-guestfs
```

## Build host checklist

Before building production images, verify:

```bash
command -v niceos-installer
command -v niceos-iso-builder
command -v create-image-util
command -v niceos-create-image
command -v docker
command -v qemu-img
```

If Docker buildx is packaged separately in the distribution, verify:

```bash
docker buildx version
```

If it is missing, install the distribution package that provides Docker buildx.

## Troubleshooting

### The package builds but image factory commands are missing

Check whether `create-image-util` was present in the source tree and installed by the RPM spec:

```bash
rpm -ql niceos-installer-image-factory
```

Expected commands:

```text
/usr/bin/create-image-util
/usr/bin/niceos-create-image
/usr/bin/niceos-image-factory
```

### `qemu-img` dependency is not resolved

Find the actual package that provides the command in NiceOS:

```bash
tdnf provides '*/qemu-img'
```

Then adjust the RPM `Requires` field to the real package name.

### Docker buildx is missing

Check:

```bash
docker buildx version
```

If the command is missing, install the package that provides buildx or add it to the `niceos-installer-image-factory` runtime requirements.

### Proxmox import script was generated but not executed

This is expected. The image factory generates a reviewable import script. Run it manually on the Proxmox VE node after reviewing VMID, storage, bridge, memory and CPU settings.

## Security note

The builder may process repository URLs, tokens, installer configuration, kickstart data and local paths. Logs should redact common secrets, but production pipelines should still avoid passing secrets on the command line when possible. Prefer protected files and environment variables.
