chore: clean up Containerfile and document "/etc" behavior

- We don't have any files remaining in "./etc/" in this repo.

- We could add a ".gitkeep" file to it, to keep the "empty" directory, but then that file would get automatically merged as a hidden file into the final image, which is silly.

- So let's just document the proper location to place things instead, which is "usr/etc/".

- The Containerfile has also been cleaned up to be a bit easier to follow along what it's doing, such as putting the "copy scripts" step closer to the actual running of the scripts.

Containerfile

@@ -4,30 +4,32 @@ ARG BASE_IMAGE_URL=ghcr.io/ublue-os/silverblue-main
 FROM ${BASE_IMAGE_URL}:${FEDORA_MAJOR_VERSION}
 ARG RECIPE
 
-# copy over configuration files
-# etc is copied to /usr/etc/ to prevent "merge conflicts"
-# as it is the proper directory for "system" configuration files
-# and /etc/ is for editing by the local admin
-# see issue #28 (https://github.com/ublue-os/startingpoint/issues/28)
-COPY etc /usr/etc
+# Copy static configurations and component files.
+# Warning: If you want to place anything in "/etc" of the final image, you MUST
+# place them in "./usr/etc" in your repo, so that they're written to "/usr/etc"
+# on the final system. That is the proper directory for "system" configuration
+# templates on immutable Fedora distros, whereas the normal "/etc" is ONLY meant
+# for manual overrides and editing by the machine's admin AFTER installation!
+# See issue #28 (https://github.com/ublue-os/startingpoint/issues/28).
 COPY usr /usr
 
-# copy scripts
-RUN mkdir /tmp/scripts
-COPY scripts /tmp/scripts
-RUN find /tmp/scripts -type f -exec chmod +x {} \;
-
+# Copy recipe.
 COPY ${RECIPE} /usr/share/ublue-os/recipe.yml
 
-# yq used in build.sh and the setup-flatpaks recipe to read the recipe.yml
-# copied from the official container image as it's not avaible as an rpm
+# "yq" used in build.sh and the setup-flatpaks recipe to read the recipe.yml.
+# Copied from the official container image since it's not available as an RPM.
 COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq
 
-# copy and run the build script
+# Copy scripts.
+RUN mkdir /tmp/scripts
+COPY scripts /tmp/scripts
+RUN find /tmp/scripts -type f -exec chmod +x {} \;
+
+# Copy and run the build script.
 COPY build.sh /tmp/build.sh
 RUN chmod +x /tmp/build.sh && /tmp/build.sh
 
-# clean up and finalize container build
+# Clean up and finalize container build.
 RUN rm -rf \
         /tmp/* \
         /var/* && \

README.md

@@ -21,10 +21,10 @@ The easiest way to start customizing is by looking at and modifying `recipe.yml`
 
 For the base-image field, you can use any other native container image. You will get all the features of that image, plus the ones added here! Check out the [uBlue images list](https://ublue.it/images/) to decide what to use!
 
-If you want to add custom configuration files, you can just add them in the `etc` directory. If you need to add other directories, you can look at the Containerfile to see how it's done. Writing to any directories under `/var` in Fedora Silverblue are not supported and will not work, as those are user-managed.
+If you want to add custom configuration files, you can just add them in the `usr/etc/` directory, which is the official OSTree "configuration template" directory. If you need to add other directories, you can look at the Containerfile to see how it's done. Writing to `/etc` or `/var` in Fedora's immutable OSTree-based distros *isn't supported* and will not work, as those are user-managed locations!
 
 > **Note**
-> The configuration files you put in the `etc` directory are actually added to `/usr/etc/` where they get applied to your local `/etc/` when rebasing to or updating the image. If a config file in `/etc/` has been changed, the changes won't be overridden, but the new version will be available in `/usr/etc/`. Run `sudo ostree admin config-diff` to see the difference between `/etc/` and `/usr/etc/` (`man ostree-admin-config-diff` for further documentation).
+> The configuration files you put in the `usr/etc/` directory are actually added to `/usr/etc/` on the final system, where they will be automatically applied to your local `/etc/` when rebasing to or updating the image. If a config file in `/etc/` has been changed by the user, OSTree will attempt to automatically merge the user's changes into the installed file, but if that fails, the new version will only be available in `/usr/etc/`. Run `sudo ostree admin config-diff` to see the difference between `/etc/` and `/usr/etc/` (`man ostree-admin-config-diff` for further documentation).
 
 ### Custom build scripts