Rewrite the tinkerer's guide for mere mortals

[trafotin]

Documentation page in question

How is a normal person, who doesn't understand things like git, podman, and signing their image build their own image? The "tinkerer's guide" asks a lot out of its readers and should be rewritten in such a way to help "mere mortals" or more lay users:

• It expects you to know and already be using git. Git is not easy for normal people to learn. It took me a solid 8 months to learn git and I still don't understand it. I know how to sync a repository (mine or someone else's) and that's about it. Presenting someone with all of these commands is confusing and overwhelming. Most people will roll their eyes into the back of their head and not bother.
• The examples to RPMs and Flatpaks is great! The examples with adding custom RPM and Flatpaks is great! No changes needed.
• How do I change specific files? For example, let's say I want to add a custom kernel turnable like Kicksecure's patches. What file do I edit record this change? Is it autorun.sh? Does this automatically call GitHub every time I make this change? What happens when I modify an existing file, like say, /etc/hosts? These questions need to be answered, I'd imagine they would be common questions for people building their own images.
• Provide practical examples of changes people might do within the documentation. What do modified files look like? This ties into the previous point, but it's not clear what even is/should be changed. Let's say someone uses an image with lightdm and they want to customize /etc/lightdm/lightdm.conf with their favorite wallpaper. Provide an example of what this looks like.
• I am an idiot and treat me like one. I have a YouTube channel where I can handle more technical things for giggles, but if I can't figure out in an hour what to do, then normal people are toast. Explain every tiny little detail and handhold me through the process. This might even need to be broken up into multiple pages because of how much information the user is expected to do (sigining images anyone?). Have a organized step by step guide on what to do.
• The biggest barrier of all is traditional Linux distros are easier to do this with and swaying the old guard is going to be done through this page. The fact I need to do all of this configuration, churn through these repos, and struggle to understand all of these flowery concepts is way too much to ask for. Compare this to the veteran Linux user, and you probably know what I mean, the cranky old guy who refuses to update or change anything, who can just run one command in a terminal and be done. That's a problem and we need to convert these people (I sound like a cult leader wow...)

Thank for reading my college essay. This is probably a lot to ask for and I'd willing to be the test dummy, but if provided the "idiot's guide," I will volunteer myself as the first in line to test it.

[EyeCantCU]

While I would agree it is definitely worth explaining things in more detail, I wouldn't expect the traditional Linux user, or rather, a typical user for that matter, would want to maintain a custom image of their own in the first place. Ideally official images or ones made by the community should cover that faucet effectively enough

So then, I guess, how far should explaining things go outside of getting people up and running? I can understand the need for better documentation, but it seems like (at least from what I'm reading here) there's a disconnect between the need to explain the new things that are brought to the table and how to work with those things versus going in depth on tooling that has been explained a thousand times before in better detail either by that tools own man pages or resources abundantly available on the internet

There isn't actually much (as an end user) that you yourself are expected to do or understand that would require going repo to repo and knowing the infrastructure here like the backside of your hand. In sum, if someone wants a functioning system, download the Universal Blue ISO like you would for any other project and install it the same way. Ideally, as a user, you don't have to worry about breakages nearly as often, things going downhill, packages not being available, and you certainly shouldn't have to think very much about the technologies underlying the OS you're using

User friendliness of a vanilla UB installation is actually much better than what you get with a lot of traditional Linux distros where it is pretty much required that you are familiar with their specific packaging system... And I think current expectations for development are actually rather reasonable. Now, I will say, explaining these technologies and how they work in a way that benefits the end user would be a great step forward

But yes, I can honestly see the need for better documentation of the project itself that maybe leans a bit into the tooling but not so far that it dismantles, for instance, everything git is capable of on its own

[castrojo]

Just to set your expectations you're asking a ton of questions that no one knows the answer to, and you might be the first person asking them .. if we knew the answers we would have put them in the documentation. 😄

[gerblesh]

It seems like you are asking how to write to /etc in a base image, and it's really quite simple, you can basically enter the containerfile, and right below COPY usr /usr you put COPY etc /etc (you need to have an etc file in the git repository root), I don't know if this is explained in the docs but it probably wouldn't be too hard to PR in. That being said be careful when writing to /etc in the image as it's writable by the user (given they have root on the system).

[trafotin]

There isn't actually much (as an end user) that you yourself are expected to do or understand that would require going repo to repo and knowing the infrastructure here like the backside of your hand

I expect to know how to modify the root filesystem. I'm not holding this on you guys because the real problem is Silverblue's documentation, which doesn't tell you how to do this at all. A hack I came up with but haven't tested in package a custom RPM with the files I want to change and layer that package with rpm-ostree, but if there was a less labor intense way of doing this, I think the vast majority of users would appreciate it.

And if I'm being honest, I know plenty of other people online have asked this questions about the parent project, Fedora's image-based spins, and everyone seems to be in the dark about how to changes outside of package layering and Flatpaks. Make it clear to normal people that these guides aren't written to them, because right now, if you look at YouTube, Reddit (well what's left of it), and other online forums, not being able to tangibly modify the base image easily is a big deal breaker. I'm onboard with the whole "rebooting after installing" thing, but it concerning that one of the first things I would do, such as hardening the Linux kernel (which is about as niche as niche gets and probably the only thing in Fedora/image-based that I need to do tbh).

That being said, I will attempt my hack layering solution and report back. As a feedback path, this is what I did:

• Visit https://ublue.it
• Read user guide (this was well-done btw)
• Skip contributor guide, proposals, roadmap. I care and most people probably wouldn't click it, but most people would just die upon seeing those massive paragraphs appear. People are ADHD and can't read.
• And that leaves the "tinkerer's guide" and we come full circle. Hope this helps, I will attempt to ask around Fedora's people on Matrix or Gitlab.

[EyeCantCU]

Modifying the root filesystem kind of defeats the point of running an immutable system and isn't entirely possible in the sense that a normal user cannot not modify anything in the /usr directory to begin with. If they were able to, the system would no longer be immutable in the sense that the part of the filesystem storing critical system packages and resources can all off a sudden be changed. There is no way to do what you are asking outside of layering and I wouldn't recommend that as a solution

You can't open a terminal and all of a sudden make the filesystem mutable and then immutable again. That's counter to the entire point of having a verifiable chain of images. You can still modify things outside of /usr though as you would on any other system

You're going to want to make your own image if modifying the root filesystem is your end goal:

https://ublue.it/making-your-own/

There's no way around that however, there is an effort to make this process easier for people

[xynydev]

Please note that this entire thread is about making custom images.

[castrojo]

I'm not holding this on you guys because the real problem is Silverblue's documentation, which doesn't tell you how to do this at all.

Understood, but again, to set expectations, this software is alpha and currently in the process of being built, in many cases we are tracking and enabling features as they land.

Fedora doesn't consider this feature ready for mass consumption yet, it is marked as Beta. One of this project's goals is to act as an opt-in project for people who want to move faster:

Both the toolkit and the images are a work in progress, so we're kind of building the bridge while we're crossing the river so we need volunteers here who are willing to experiment.

[trafotin]

I stand by my other points, but this is interesting. This was replicated in Silverblue, Kinoite, and Sericea's documentation, but under "tips and tricks:" https://docs.fedoraproject.org/en-US/fedora-sericea/tips-and-tricks/#_working_with_ostreerpm_ostree

So the answer to the question is aside from writing an image, it's on the onus of the user? I did attempt this once by changing /etc/hosts/, but it got reset when I updated. Seems to work this time when I tried some things in /etc/ and did survive a reboot. But I can't be crazy to have looked in the dead middle of "tips and tricks..."

There are some issues with custom /opt packages, like Chrome (I think this was fixed) and Portmaster but I will be testing some of my own. Most of what I need can run out of a container anyway.

It's up to you guys if you want this to be closed vs leave it open for comment later.

[castrojo]

There's a good deal of value in the discussion already so if anything we've got more information for the next set of folks, so I'll just move this to discussions.

[xynydev]

@trafotin
Some of the stuff you’re asking about is universal to all OCI container building, some is universal to rpm-ostree and some is specific to the template (like the supported way of adding custom files to the filesystem).

I’d be happy to go over your confusions one-by-one and turn those into documentation if you laid them out below in seperate short comments that could be discussed as reply-chains.

One thing that the Make Your Own documentation could state more clearly, that it is just a setup guide and not a customization guide (just a shallow introduction). Most instructions regarding customizing your own image lay in the startingpoint repository’s README, and are not always applicable to images made using other templates.

The issue of setup becomes pretty easy when you use a automatic setup tool like the one I built (which requires just a little bit more testing for me to add it to the docs).

Regarding what you need to know how to use, a very shallow understanding of git and being able to commit and push is required when using automatic setup, while manual setup requires a bit more. Syncing your repo and merging with the Github UI is also useful, but not strictly necessary when you don’t want to keep up with upstream changes (which can be breaking as we’re still pre-release). You do not need to know Podman or Cosign at all, they are the tools that are used to make your image, but all that is set up in the repo. Only adding the signing secrets is needed, which also becomes easier with automatic setup.

For further customization, you do need to know some of how the OCI Containerfile is written, but by following by example it should be pretty easy. (if you need to add files in directories other than /usr/, there’s already some COPY statements you can see in startingpoint’s Containerfile) For running scripts at build time, the scripts directory has the documentation for that. Everything in the template is intended for you to browse around and grow to understand, but you do not need to do that. For most people, editing recipe.yml and adding config files in /usr/etc/ should be just enough.

---

What is important here is that this is for ”tinkerers”, people who want to customize their OS like their used to doing on Arch etc. This is not for ”normal people” because 1. those don’t really exist 2. statistically the average person does not even use or care about Linux.
I think it’s a shame that the main uBlue images don’t provide all of the same QoL (yafti, nix-me-up but that’s changing) ootb as startingpoint does. I think they should be very fitting for the needs of the ”average user”. If you just need to layer a couple of things, go ahead, but if you want to create a custom image with those packages built-in insteadd, we have the tools, an just adding a couple of packages should be pretty easy.