Hooks and overlays

Flashberry provides two complementary customization mechanisms: overlays copy files into the image, while hooks execute scripts during controlled build stages.

Root filesystem overlay

Files below overlays/rootfs/ are copied into the configured root filesystem with their relative paths preserved.

Example:

overlays/rootfs/
└── etc/
    └── systemd/
        └── system/
            └── example.service

Use this for declarative configuration files, service units, helper programs, and other static image content.

Boot overlay

overlays/boot/config.txt and overlays/boot/cmdline.txt are templates used during image assembly. Flashberry substitutes architecture and partition IDs as part of the build.

In-chroot hooks

Executable shell scripts under hooks/in-chroot.d/*.sh are copied into the rootfs, run in lexical filename order, then removed.

The hook environment exposes FLASHBERRY_USER for the configured user name. Hooks run as root, so keep them deterministic and fail-fast.

Other hook directories

hooks/pre-chroot.d/ and hooks/post-image.d/ currently exist as extension points but are not executed by the build pipeline. Do not rely on them until a corresponding pipeline stage is implemented.