# vnoi-admin/image-builder architecture

> Architecture diagram of the GitHub repository vnoi-admin/image-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vnoi-admin/image-builder
- Repository: https://github.com/vnoi-admin/image-builder

## Overview

The project is an image builder designed to create a customized Ubuntu ISO specifically tailored for ICPC contests. The goal of the project is to automate the process of taking an original ICPC ISO file (or a downloaded version) and applying a set of customizations (e.g., modifications in configuration, branding changes with a logo, and installation automation) to produce a final ISO image for deployment in contest environments.

##### Main Components
- Build Orchestrator: At the very center of the system is the build.sh script. This script ties together several other elements and acts as the entry point for initiating the build process.
- Image Toolkit: The image-toolkit directory contains all the scripts and tools necessary for modifying the ISO image. Within this, you have:
- Binaries (bin folder) – Contains helper scripts (e.g., cleanup scripts, client scripts, etc.).
- System scripts in the sbin folder – Scripts for firewall setup, user creation, streaming, etc.
- Configuration samples and miscellaneous files (misc folder) – Provide samples and configuration templates.
- Testing infrastructure (tests folder) – Contains tests to validate various components like network, permissions, and language-specific configurations.
- PAM Module: The modules/pam directory holds a PAM (Pluggable Authentication Module) implementation including its source files (.c, .h), testing scripts, and a Makefile. This indicates that part of the customization involves integrating new authentication features.
- Preseed/Seed Files: The seeds directory with its different preseed files (dev.preseed, prod.preseed and legacy versions) contains configuration files for the unattended installation. They are critical for automating installation parameters.
- Configuration Files:
- Global configuration scripts (config.sh, chroot_install.sh, grub.cfg) – These files likely coordinate boot configuration and environment setup.
- Local configuration copies (config.local.sh and image-toolkit/config.local.sh) – Used to personalize the build by specifying variables like the ICPC ISO URL, root password, versioning, and network parameters.
- CI/CD and Automation: The .github/workflows directory includes GitHub Actions workflows for various tasks (push-releases, self-hosted runner/storage) ensuring that the building process is automated and integrated with version control.

##### Relationships and Interactions
- The Build Orchestrator (build.sh) initiates the image build process by reading configuration variables from its related config files. It then calls the necessary scripts in the image-toolkit.
- The image-toolkit communicates with the PAM module (modules/pam) to integrate necessary authentication capabilities.
- The seeds directory is used during the OS installation process to supply pre-configured answers in an unattended way.
- CI/CD workflows in the .github folder trigger build actions in different environments (e.g., GitHub Actions, self-hosted runners), ensuring continuous integration and deployment.
- Scripts in image-toolkit (cleanup.sh, startup.sh, etc.) interact with both the build process and system-level configurations (like firewall and networking).

##### Architectural Patterns & Design Principles
- Script-based Orchestration: The system is primarily driven by shell scripts which provide a lightweight yet powerful orchestration mechanism.
- Configuration and Customization Separation: There is a clear separation between machine-wide configuration (in image-toolkit/config.sh) and personal/local configuration (e.g., config.local.sh), promoting reusability and maintainability.
- Modularity: The segmentation of PAM module and testing infrastructure indicates a modular design that allows individual components to be tested and maintained independently.
- CI/CD Integration: The presence of GitHub Actions workflows implies that automation, testing, and release management are integrated into the development lifecycle.

##### Detail
- Important files such as config.sh, image-toolkit/config.sh, preseed files, and PAM source files.

## Diagram (Mermaid)

```mermaid
graph TD
    CI["CI/CD Workflows (.github/workflows)"]:::cicd
    BO["Build Orchestrator (build.sh)"]:::orchestrator
    GC["Global Config Files (config.sh, chroot_install.sh, grub.cfg)"]:::config
    PS["Preseed Files (seeds: dev.preseed,prod.preseed,legacy)"]:::preseed
    IT["Image Toolkit (Scripts & Tools)"]:::toolkit
    PAM["PAM Module (modules/pam)"]:::pam

    CI -->|"triggers build"| BO
    BO -->|"loads config"| GC
    BO -->|"reads preseeds"| PS
    BO -->|"calls toolkit"| IT
    IT -->|"integrates auth"| PAM

    subgraph "Image Toolkit Components"
        IT_bin["Binaries (image-toolkit/bin)"]:::toolkit
        IT_sbin["System Scripts (image-toolkit/sbin)"]:::toolkit
        IT_misc["Misc & Samples (image-toolkit/misc)"]:::toolkit
        IT_config["Config Sample (image-toolkit/config.sh.sample)"]:::toolkit
        IT_tests["Testing Infrastructure (image-toolkit/tests, image-toolkit/tests.sh)"]:::toolkit
    end

    IT -->|"includes"| IT_bin
    IT -->|"includes"| IT_sbin
    IT -->|"includes"| IT_misc
    IT -->|"includes"| IT_config
    IT -->|"includes"| IT_tests

    click CI "https://github.com/vnoi-admin/image-builder/tree/master/.github/workflows"
    click BO "https://github.com/vnoi-admin/image-builder/blob/master/build.sh"
    click GC "https://github.com/vnoi-admin/image-builder/blob/master/config.sh"
    click PS "https://github.com/vnoi-admin/image-builder/tree/master/seeds"
    click IT_bin "https://github.com/vnoi-admin/image-builder/tree/master/image-toolkit/bin"
    click IT_sbin "https://github.com/vnoi-admin/image-builder/tree/master/image-toolkit/sbin"
    click IT_misc "https://github.com/vnoi-admin/image-builder/tree/master/image-toolkit/misc"
    click IT_config "https://github.com/vnoi-admin/image-builder/blob/master/image-toolkit/config.sh.sample"
    click IT_tests "https://github.com/vnoi-admin/image-builder/tree/master/image-toolkit/tests"
    click PAM "https://github.com/vnoi-admin/image-builder/tree/master/modules/pam"

    classDef orchestrator fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef toolkit fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef pam fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef preseed fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#333,stroke-width:2px;
```
