# vyos/vyos-build architecture

> Architecture diagram of the GitHub repository vyos/vyos-build, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vyos/vyos-build
- Repository: https://github.com/vyos/vyos-build

## Overview

Step 1. Identify the Core Purpose and Project Type
- This project is essentially a build orchestration system for a Linux distribution.
- Its purpose is to compile multiple packages (including upstream and in-house developed ones) and create a custom ISO image for VyOS.
- It integrates several sub-components (scripts for building packages, data for configuration, Docker containers for isolated builds, and CI workflows for automation).

Step 2. Analyze the File Structure to Identify Main Components
- .github – Contains multiple GitHub Actions workflows. These define CI/CD jobs such as linting, PR checks, image build triggers, and syncing operations.
- data – Holds all configuration files: architectures (.toml files), build flavors/types, certificates, and extensive live-build configurations (archives, bootloaders, hooks, includes, package lists). This is the configuration backbone that informs how the ISO is built.
- docker and docker-vyos – These directories include Dockerfiles and installation scripts that enable containerized building of VyOS images.
- packages – Contains arbitrary *.deb packages (such as the Linux Kernel, FRR, Netfilter, etc.) to be embedded in the resulting ISO.
- scripts – This is the engine room where:
- scripts/image-build handles the overall image construction (invokes build-vyos-image, raw image generation, default settings, and utilities).
- scripts/package-build contains subdirectories for each package (e.g. amazon-cloudwatch-agent, dropbear, frr, linux-kernel, etc.) along with specific build scripts (build.py) and configuration files (package.toml). This clearly represents the modular, multi-step process required to compile and package the OS components.
- scripts/utils provides utility functions to support the build and merge configurations.
- tools – Hosts scripts for maintainer automation (cloud-init related tasks and container configuration) that aren’t used directly during the ISO build process.

Step 3. Determine the Relationships and Interactions
- CI workflows initiating package builds,
- Code quality/linting tasks ensuring the integrity of scripts.
- Docker components provide an isolated environment. They interact with the build scripts to encapsulate the build process for different architectures.
- The live-build configuration found within the data/ directory feeds into the ISO creation process, where the various package builds are integrated.
- The scripts in package-build, image-build, and utils coordinate the overall build cycle:
- Package sources are compiled separately,
- Outputs are stored within packages/,
- The ISO image is assembled using live-build configurations (found in data/live-build-config).

Step 4. Identify Key Architectural Patterns and Technologies
- The system is modular: different packages are built by dedicated scripts and then integrated.
- There is a clear separation of concerns:
- Data/configuration (data/),
- Build execution (scripts/),
- Containerization (docker/),
- Continuous integration (GitHub workflows).
- The architecture follows a multi-step build process which is common in custom Linux distribution builds: compile packages → generate .deb packages → integrate into final ISO.
- The repository also uses Docker for containerized builds, ensuring consistency in the build environment.
- Automation via GitHub Actions ensures that all builds are checked and triggered automatically based on changes.

- CI/CD Pipeline:
- GitHub Actions workflows as a trigger mechanism.
- Build Orchestrator:
- Scripts directory (split into “image-build”, “package-build”, “utils”) as the central engine.
- Data/Configuration:
- Data directory containing live-build configurations, build flavors, architectures, and certificates.
- That configuration data flows into the build orchestrator.
- Package Repository:
- Packages/ folder (and potentially the Git submodules not shown but referenced in the README) as the output/integration point.
- Docker Container Environment:
- Docker and docker-vyos as an isolated build system.
- Directional flow from the Docker container to the build orchestrator—demonstrating that some build tasks run within containers.
- Tools:
- A smaller block for “Maintainer Tools” drawn from the tools/ directory; note these aid in automation and repo maintenance.

- From CI/CD to Build Orchestrator.
- From Data/Configuration feeding into the Build Engine.
- From Package Build processes into the final integrated Package Repository/ISO build.
- From Docker environments into the overall build process.

##### Incorporate relevant details
- If possible, include a note about the multi-step build process (package compilation followed by ISO assembly).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions CI"]:::cicd
    end

    %% Configuration Data
    subgraph "Configuration"
        Config["Configuration Data (data/)"]:::data
    end

    %% Docker Environment
    subgraph "Docker Environment"
        Docker["Docker (docker/)"]:::docker
        DockerVyos["Docker VyOS (docker-vyos/)"]:::docker
    end

    %% Build Orchestrator
    subgraph "Build Orchestrator"
        IBU["Image Build (scripts/image-build)"]:::build
        PB["Package Build (scripts/package-build)"]:::build
        UT["Utility Scripts (scripts/utils)"]:::build
    end

    %% Package Repository
    subgraph "Output"
        PKG["Package Repository (packages/)"]:::package
    end

    %% Maintainer Tools
    subgraph "Maintainer Tools"
        Tools["Maintainer Tools (tools/)"]:::tools
    end

    %% Relationships
    CI -->|"triggers"| IBU
    CI -->|"initiates"| PB
    Config -->|"informs"| IBU
    Docker -->|"isolatedBuild"| IBU
    DockerVyos -->|"isolatedBuild"| IBU
    IBU -->|"assemblesISO"| PKG
    PB -->|"compilesPackages"| PKG
    UT -->|"supports"| IBU
    Tools ---|"automationAids"| IBU

    %% Styles
    classDef cicd fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef build fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef data fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef docker fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef package fill:#d8bfd8,stroke:#000,stroke-width:2px;
    classDef tools fill:#d3d3d3,stroke:#000,stroke-width:2px;

click CI "https://github.com/vyos/vyos-build/tree/current/.github/workflows/"
click IBU "https://github.com/vyos/vyos-build/tree/current/scripts/image-build"
click PB "https://github.com/vyos/vyos-build/tree/current/scripts/package-build"
click UT "https://github.com/vyos/vyos-build/tree/current/scripts/utils"
click Config "https://github.com/vyos/vyos-build/tree/current/data/"
click PKG "https://github.com/vyos/vyos-build/tree/current/packages/"
click Docker "https://github.com/vyos/vyos-build/tree/current/docker/"
click DockerVyos "https://github.com/vyos/vyos-build/tree/current/docker-vyos/"
click Tools "https://github.com/vyos/vyos-build/tree/current/tools/"
```
