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:

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:

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

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

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

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:

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:

--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:

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

For rootfs/container extraction from existing disk images:

tdnf install niceos-installer-image-factory-guestfs

Build host checklist

Before building production images, verify:

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:

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:

rpm -ql niceos-installer-image-factory

Expected commands:

/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:

tdnf provides '*/qemu-img'

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

Docker buildx is missing

Check:

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.