docs(files): re-add file documentation (#205)

modules.json

@@ -1,4 +1,5 @@
 [
+  "https://raw.githubusercontent.com/blue-build/modules/main/modules/files/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/akmods/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/bling/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/default-flatpaks/module.yml",

modules/files/README.md

@@ -1 +1,54 @@
-### The documentation for the `files` module exists in the [blue-build/cli](https://github.com/blue-build/cli/tree/main/template/templates/modules/files) repository.
+# `files`
+
+The `files` module can be used to copy directories from `config/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:
+
+1. copying a directory in `config/files` directly to `/etc` to add all of its
+   files at build time, or
+2. 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](https://docs.fedoraproject.org/en-US/fedora-silverblue/technical-information/#filesystem-layout),
+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.
+
+:::

modules/files/module.yml

@@ -0,0 +1,12 @@
+name: files
+shortdesc: Copy files to your image at build time
+readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/files/README.md
+example: |
+  modules:
+    - type: files
+      files:
+        - usr: /usr # copies config/files/usr into your images /usr
+                    # put configuration files you want in /etc/ on a *booted*
+                    # system in /usr/etc/ in the image.
+        - etc: /etc # copies config/files/etc into your image's /etc immediately,
+                    # for use with further modules.