Configuring the image

Use this method only if you really need a system-wide image change, because it is time-consuming and uses PC resources for rebuilding.

The contents of the local image are described declaratively in the file /etc/apm/image.yml. You can create it manually, or it will be created automatically: after the first apm system install <pkg> and the next apm system image apply, the installed package and the current base image will appear in the file.

To change the system, edit the file and apply the changes:

sudo apm system image apply

apply will build a new local image based on your config and switch the system to it via bootc. A reboot is required for the changes to take effect.

Declarativeness

The image is always built from scratch: the host state is not remembered. Therefore, all required changes (packages, services, files) must be described in image.yml — otherwise they will be lost after the next apply.

The image field

A required field is the link to the base OCI image on top of which your local image is built. Usually the current system image is specified; it can be viewed via apm system image status. Without this field, apply will fail with an error.

Example: installing packages

To add packages to the image, describe them in the packages module:

image: altlinux.space/alt-atomic/onyx/stable:latest
modules:
  - name: My custom packages
    type: packages
    body:
      install:
        - hello
        - tmux

An alternative way is quick installation via apm system install <pkg>: the package will immediately appear in the system, and the next call to apm system image apply will add it to image.yml and rebuild the image.

Example: changing the kernel

To switch to kernel 6.18 and connect the drm module, add the kernel module:

image: altlinux.space/alt-atomic/onyx/stable:latest
modules:
  - name: Update packages
    type: packages
    body:
      update: true

  - name: Update kernel
    type: kernel
    body:
      kernel-info:
        flavour: 6.18
        modules:
          - drm
      initrd:
        method: dracut

Apply:

sudo apm system image apply
sudo reboot

After rebooting, the system will run on the new kernel. The previous image version remains available in the GRUB menu for rollback.

More modules and fields

The full list of available modules, their fields, and environment variables is in the article "Configuring the image".