Configuring the image

The image is configured using a YAML configuration file and the apm system image build command.

Basic config

The initial file from which the configuration starts is /etc/apm/image.yml.

apm system image build applies changes to the current container based on the settings in image.yml.

Clarification

When creating an image in CI/CD, the configuration file is copied or mounted using Containerfile from the repository to the container via the aforementioned path.

Example

ALT Atomic Core:

image: ${{ Env.IMAGE }}

modules:
  - name: Set repos
    type: repos
    body:
      branch: sisyphus
      date: ${{ Env.YEAR }}/${{ Env.MONTH }}/${{ Env.DAY }}
      clean: true

  - type: packages
    body:
      update: true
      upgrade: true

  - name: Set branding
    type: branding
    body:
      name: alt-atomic-${{ Env.IMAGE_NAME }}
      build-type: ${{ Env.IMAGE_TYPE }}

  - name: Copy root
    type: copy
    body:
      source: root
      destination: /
      replace: true

  - type: include
    body:
      targets:
        - packages.yml
        - network.yml
        - apt-rpm.yml
        - filesystem.yml
        - systemd.yml
        - settings.yml
        - passwd.yml
        - disable-bins.yml

  - name: Configurate grub
    type: shell
    body:
      command: scripts/grub.sh

  - name: Update kernel
    type: kernel
    body:
      flavour: 6.12
      modules:
        - drm
      rebuild-initrd-method: dracut

  - name: Cleanup
    type: include
    body:
      targets:
        - cleanup.yml

Fields of the configuration file

Legend

! — required field

Field	Description
image	Base image to use (reference to the container).
modules	List of modules.
env	Environment variables. Can be used in any module.

image is a required field when using apm s i apply or apm s i update.

Modules (modules)

Array of modules for execution.

Field	Description
name	The name of the module for logging.
type	The type of the module body.
id	The module identifier. For more details, see the section "Module Identifier".
env	Environment variables for the module. They can only be used within the scope of this module.
if	Condition in the Expr language format.
body	Module body.
output	Data for output.

The identifier allows you to access the module to obtain the values of the following fields:

• Name (name)
• Type (type)
• Identifier (id)
• Result of the conditional expression (if)
• Output data (output)

Branding (branding)

The branding module is designed to select the branding for the installed image.

Field	Description
name	Branding name for packages (branding-<name>-*). Requires build-type.
subpackages	Subpackages of branding to be installed (branding-<name>-<subpackage>). If empty, all will be installed. Requires name.
release-overrides	A dictionary for overriding or adding fields in os-release.
build-type	The build type, required for os-release. Requires name.

Supported build types:

• stable
• nightly

Example

ALT Atomic Core:

  - name: Set branding
    type: branding
    body:
      name: alt-atomic-${{ Env.IMAGE_NAME }}
      build-type: ${{ Env.IMAGE_TYPE }}

Copying (copy)

The copy module is designed for copying files and directories.

Legend

! — required field

Field	Description
source!	Path to the file to copy.
destination!	Path to the file to copy to.
replace	Whether to replace destination.

Example

ALT Atomic Core:

  - name: Copy root
    type: copy
    body:
      source: root
      destination: /
      replace: true

Git (git)

The git module is designed to work with Git repositories: installing dependencies, building, installing the results of the work in the system, and so on.

Legend

! — required field

Field	Description
url!	URL of the git repository.
command!	Commands to execute relative to the git repository.
build-deps	Dependencies for the build. They will be removed after the module is completed.
deps	Dependencies for the program itself. They will not be removed after the module is completed, even if specified in build-deps.
rev	Git revision.
quiet	Hides command output.

Including other configs (include)

The include module is intended for including other configurations.

Legend

! — required field

Field	Description
targets!	YAML configs for execution

Example

ALT Atomic Core:

  - name: Cleanup
    type: include
    body:
      targets:
        - cleanup.yml

Working with the kernel (kernel)

The kernel module is designed to select the kernel version (flavour), connect additional modules, include headers, and rebuild initramfs.

Field	Description
kernel-info	Working with the kernel and kernel modules
initrd	Working with initrd

The kernel-info subsection

Field	Description
flavor	Kernel version
modules	Names of the kernel modules (kernel-module-<name>-<flavor>)
include-headers	Whether to include core headers

The initrd subsection

Field	Description
rebuild-initrd-method	Supported: dracut, auto. If empty and one of flavour, modules, include-headers is specified, then auto is used
plymouth-theme	Plymouth boot screen theme (plymouth-theme-<name>)

Example

ALT Atomic Core:

  - name: Update kernel
    type: kernel
    body:
      kernel-info:
        flavour: ${{ Env.KERNEL_FLAVOUR }}
        modules:
          - drm
      initrd:
        method: dracut

Creating links (link)

The link module is designed to create symbolic links to objects.

Legend

! — required field

Field	Description
target!	Where to create the link, absolute path
to!	Where it will lead
replace	Whether to replace target

Example

ALT Atomic Core

  - type: link
    body:
      target: /ostree
      to: /sysroot/ostree
      replace: true

Merging file contents (merge)

The merge module is designed to merge files.

Legend

! — required field

Field	Description
source!	Path to the file whose contents need to be taken
destination!	Path to the file where the contents need to be added
create-file-perm	Permissions for creating a file in the rwxrwxrwx format if it doesn’t exist
prepend	Should the content be added to the beginning of the file?

Creating directories (mkdir)

The mkdir module is designed to create directories at the specified paths with defined ownership rights.

Legend

! — required field

Field	Description
targets!	Paths where directories need to be created
perm!	Permissions for directories in the format rwxrwxrwx

Example

ALT Atomic Core:

  - type: mkdir
    body:
      targets:
        - /sysroot
      perm: rwxr-xr-x

Moving objects (move)

The move module is designed to move objects in the file system, with the option to leave a reference in place of the moved object.

Legend

! — required field

Field	Description
source!	What
destination!	Where
replace	Replace the object at destination
create-link	Create a link from the target’s parent directory to the destination

Example

ALT Atomic Core:

  - type: move
    body:
      source: /etc/apt
      destination: /usr/share/apt
      create-link: true

Network configuration (network)

The network module is designed to configure network settings.

Legend

! — required field

Field	Description
hostname!	Device network name

Example

ALT Atomic Core:

  - type: network
    body:
      hostname: alt-atomic-${{ Env.IMAGE_NAME }}

Working with packages (packages)

The packages module is designed to work with packages: installation, removal, updating the database and the packages themselves.

Field	Description
install	Packages to be installed
remove	Packages to be removed
update	Whether to update the database before the transaction
upgrade	Whether to update the packages before the transaction
depends	Remove packages with dependencies

Example

ALT Atomic Core:

  - type: packages
    body:
      install:
        - glxinfo
        - mesa-dri-drivers
      update: true
      upgrade: true

Removing objects (remove)

The remove module is designed to delete objects.

Legend

! — required field

Field	Description
targets!	Path to the objects that need to be deleted
inside	Clear objects instead of deleting

Example

ALT Atomic Core:

  - name: Clean logs
    type: remove
    body:
      targets:
        - /var/log/README.logs
        - /var/log/rpmpkgs
      inside: true

Changing the file content (replace)

The replace module is designed to replace the contents of a file based on a regular expression.

Legend

! — required field

Field	Description
target!	Path to the file
pattern!	Regular expression pattern
repl!	Replacement

Working with repositories (repos)

The repos module is designed to clean, install custom or pre-installed repositories, and add tasks (projects).

Legend

! — required field

Field	Description
clean	Clear all repositories. Conflicts with clean-temporary
custom	Custom entries in sources.list
branch	ALT repository branch. Comments out the remaining repositories; to clean up, use clean
date	Date in the format YYYYMMDD or YYYY/MM/DD. If empty, the current (non-archived) repository is used. Requires branch
tasks	Tasks to be included as repositories
no-update	Do not update the database after saving the repositories
clean-temporary	Clear temporary repositories. Conflicts with clean

List of available branches:

• sisyphus

Example

ALT Atomic Core:

  - name: Set repos
    type: repos
    body:
      branch: sisyphus
      date: ${{ Env.YEAR }}/${{ Env.MONTH }}/${{ Env.DAY }}
      clean: true

Executing scripts (shell)

The shell module is designed to execute imperative code in Bash.

Legend

! — required field

Field	Description
command!	Commands to execute
quiet	Hides command output

Example

ALT Atomic Core:

  - name: Set root password
    type: shell
    body:
      command: echo "root:root" | chpasswd

Working with SystemD services (systemd)

The systemd module is designed to monitor the status of SystemD.

Legend

! — required field

Field	Description
targets	Service names
enabled	Whether to enable the service or not. Conflicts with masked
global	Whether to enable the service globally, for all users
masked	Whether to mask the service. Conflicts with enabled

Example

ALT Atomic Core:

  - type: systemd
    body:
      targets:
        - ostree-remount
        - NetworkManager
        - libvirtd
        - chrony
        - podman.socket
        - sync-users.service
        - sync-directory.service
        - tmp.mount
      enabled: true