History

xyny e749fe71d3 chore: remove raw github URLs from module.ymls (unneeded after recent refactor)		2024-07-26 16:02:32 +03:00
..
files.sh	fix(files): Error-out & fail the build when there's no file/directory supplied in recipe	2024-07-23 14:12:45 +02:00
files.tsp	docs: Update documentation to reflect change from `config/` to `files/` (#283 )	2024-07-21 19:21:28 +00:00
module.yml	chore: remove raw github URLs from module.ymls (unneeded after recent refactor)	2024-07-26 16:02:32 +03:00
README.md	docs: Update documentation to reflect change from `config/` to `files/` (#283 )	2024-07-21 19:21:28 +00:00

README.md

`files`

The files module can be used to copy directories from files/ to any location in your image at build time, as long as the location exists at build time (e.g. you can't put files in /home/<username>/, because users haven't been created yet prior to first boot).

:::note If you want to place files into /etc/, there are two ways to do it:

copying a directory in files/ directly to /etc to add all of its files at build time, or
putting the files you want there in /usr/etc/ as part of copying things over to /usr/, which rpm-ostree will then copy to /etc/ at runtime/boot.

Typically, you will want to use the latter option (putting files in /usr/etc/) in almost all cases, since that is the proper directory for "system" configuration templates on atomic Fedora distros, whereas /etc/ is meant for manual overrides and editing by the machine's admin after installation (see issue https://github.com/blue-build/legacy-template/issues/28). However, if you really need something to be in /etc/ at build time --- for instance, if you for some reason need to place a repo file in /etc/yum.repos.d/ in such a way that it is used by a rpm-ostree module later on --- then the former option will be necessary. :::

:::caution The files module cannot write to directories that will later be symlinked to point to other places (typically /var/) by rpm-ostree.

This is because it doesn't make sense for a directory to be both a symlink and a real directory that has had actual files directly copied to it, so the files module copying files to one of those directories (thereby instantiating it as a real directory) and rpm-ostree's behavior regarding them will necessarily conflict.

For reference, according to the official Fedora documentation, here is a list of the directories that rpm-ostree symlinks to other locations:

/home/ → /var/home/
/opt/ → /var/opt/
/srv/ → /var/srv/
/root/ → /var/roothome/
/usr/local/ → /var/usrlocal/
/mnt/ → /var/mnt/
/tmp/ → /sysroot/tmp/

So don't use files to copy any files to any of the directories on the left, because at runtime rpm-ostree will want to link them to the ones on the right, which will cause a conflict as explained above.

:::