search

fedora-silverblue / silverblue-docs

Fedora Silverblue documentation
https://docs.fedoraproject.org/en-US/fedora-silverblue/
62 stars 79 forks source link

Ideas for Detailed User Guide #1

Open miabbott opened 5 years ago

miabbott commented 5 years ago

migrated from https://pagure.io/fedora-docs/silverblue/issue/17

(This idea has bounced around the various places Silverblue has lived; hopefully this is now a permanent home.)

I would like to create a detailed, hands-on/end-to-end guide for the Silverblue docs. It would be much more verbose, with screenshots and terminal examples, that would be geared more towards new users rather than old veterans.

My starts with documenting the install of Silverblue from the very beginning, showing all the steps required to get to that first login screen, and perhaps discussing some of the options along the way.

After that first login, the guide would talk about some of the first steps users will want to do, like enabling the Flathub repo, layering in some packages, perhaps enabling RPM Fusion, maybe turning on SSH logins, etc. It can cover these operations using the CLI and gnome-software.

Then it could delve into using containers to provide tools that aren’t available on the host, including how to use buildah and podman.

My first set of ideas for the guide is outlined below. I’d like to curate and expand on these ideas, so please weigh in!

The first steps towards this guide has already been implemented in the Installation Guide, but there is clearly more we can document.

migrated comments follow

jakfrost commented 4 months ago

I like what you have started here. I think something on SELinux might be a good thing, as well as possibly something on how portals are used by flatpaks and the ostree. Some rudimentary systemd stuff, which could be just links to the appropriate locates for the System Admin guide topics. Really though, you have a good framework started and I think it is entirely inline with what is normally out there for Fedora Doc. Of course what I noted above, all could be interleaved with your heading ideas already, also adding the configurations of some of our "professional" users as examples will do a lot for most intermediate users. The guide must afford the new user a place to get a firm start at using Fedora Silverblue, which also will likely mean linux in general, since here I am thinking of the 'new to linux and fedora' user.
znmeb commented 4 months ago

Looks good to me. I'm a long-time Linux user (Red Hat 6.2 - present) and an awful lot is different even compared to Fedora Workstation.
znmeb commented 4 months ago

The biggest stumbling blocks for me on Silverblue, as a long-time Linux workstation user, including Fedora from "Beefy Miracle" through Fedora 27 are:

    Managing rpm-ostree deployments. I need a command line tool to search for packages and ways to juggle an arbitrary number of deployments. I'd like to have, for example, Silverblue 29, Rawhide, and a rollback for each of them.
    Documenting how to turn a third-party GUI app into a flatpak that runs in user space.
    Container wrangling without Docker: basically, how to do everything I do now on a workstation with Docker and Docker Compose with buildah, podman, skopeo, kompose and Kubernetes. Right now I don't even know how to install Kubernetes.

I've got a work in progress I can use as a testbed for all of this - https://github.com/znmeb/data-science-pet-containers. That would only exercise 1 and 3 above; the toolset was deliberately designed around web apps.
jakfrost commented 4 months ago

    Managing rpm-ostree deployments. I need a command line tool to search for packages and ways to juggle an arbitrary number of deployments. I'd like to have, for example, Silverblue 29, Rawhide, and a rollback for each of them.

    This is definitely something I have noticed others talk about elsewhere, including a discussion I was having with my brother in law about Silverblue. Pointedly, I was bemoaning the fact that I felt I was back in the early days of our joint Linux use jump, when we switched off MS products on our desktops for good. I think working through the in's and out's of how to do this task would provide clear informative benefit to the community, and likely prove to be a mountain of technical solutions to climb in order to reach the preferred state.

    Documenting how to turn a third-party GUI app into a flatpak that runs in user space.

    I am currently trying, well I have to get back at it, I want to put IntelliJ's IDEA IDE in a flatpak with the necessary java libraries I use for my limited scope of Java programming, the process should be the same though in any case, and I have it partially working, still fails though.

    Container wrangling without Docker: basically, how to do everything I do now on a workstation with Docker and Docker Compose with buildah, podman, skopeo, kompose and Kubernetes. Right now I don't even know how to install Kubernetes.

    Yeah, container management has become top on my mind lately and I really was blissfully unaware of them (sometimes purposefully) until I tried out Silverblue 28.

    I've got a work in progress I can use as a testbed for all of this - https://github.com/znmeb/data-science-pet-containers. That would only exercise 1 and 3 above; the toolset was deliberately designed around web apps.

    That would be awesome!
znmeb commented 4 months ago

        Documenting how to turn a third-party GUI app into a flatpak that runs in user space.

    I am currently trying, well I have to get back at it, I want to put IntelliJ's IDEA IDE in a flatpak with the necessary java libraries I use for my limited scope of Java programming, the process should be the same though in any case, and I have it partially working, still fails though.

It turns out I also need to be able to export the container display and sound to the host for one of my projects. That's pretty easy on a Silverblue host - you just do some bind-mount magic https://stackoverflow.com/questions/25281992/alternatives-to-ssh-x11-forwarding-for-docker-containers. However, I need to be portable to Windows and Mac hosts, so I'll probably go with xpra
znmeb commented 5 years ago
  1. Can one do a side-by-side install with a "host" other than Fedora?
  2. A guide to podman networking would be useful. The rich infrastructure provided by docker network doesn't appear to be available in the current podman. Compare https://github.com/znmeb/data-science-pet-containers/blob/master/containers/docker-run.bash with https://github.com/znmeb/data-science-pet-containers/blob/master/containers/sudo-podman-run.bash to get an idea of what's missing for the simple task of building a network / pod of containers that can talk to each other by name.
  3. Grub configuration on dual-booted systems. Where does Silverblue get its /etc/default.grub, where does it store the generated configuration files, how does one manage multiple required command lines, etc.
TheOneandOnlyJakfrost commented 5 years ago

It's finally on GitHub. I can fork and clone this repo and get my latest additions incorporated. WooHoo!

allanday commented 5 years ago

One key question we need to answer is whether we want the Silverblue docs to reproduce material that's available elsewhere. Personally, I'm unconvinced that we should be maintaining our own installation guide or our own podman docs: it's a lot of material that will inevitably end up being reproduced elsewhere.

znmeb commented 5 years ago

I would think the end goal would be something like the RHEL manuals or the Fedora manuals - a comprehensive, searchable HTML / PDF / EPUB technical document that answers every question a user might have, eliminating the need for Google or Stack Overflow during troubleshooting. ;-)

Of course, nobody's documentation is that good, but some come closer than others. And it takes time and effort that may not be in anyone's budget except for volunteers.

You're right - podman and the installer that has the same name as a popular Python, R and Julia data science stack are documented well elsewhere. But the existence of that naming conflict alone is why one might want to do Silverblue installer documentation within a comprehensive Silverblue manual. P.S.: the Silverblue installer workflow differs from Fedora Workstation.

dyoungwd commented 5 years ago

Where would this be done / hosted? A separate repo, using the wiki feature on this repo, within a sub folder of this repo or somewhere else entirely?

Personally, I like the idea of an advanced / additional guide or user manual in general but as touched upon already is it necessary to get into great detail for things that have existing docs.

Would it not be best to give an introduction on how to use, for example podman, and for the more specific / technical details, provide a link to that section otherwise when they update docs it will have a knock on effect

allanday commented 5 years ago

The thing is, there is a comprehensive installation guide for Fedora, and I think that 95% of that is correct for Silverblue... Do we really want to maintain our own version of that 95%?

The other thing I'm conscious of is that, in many cases, people just need to know 2/3 key pieces of information before they install (what to expect from Silverblue, should you use manual partitioning, is dual boot possible, etc) - those could get lost in a big guide.

allanday commented 5 years ago

Where would this be done / hosted? A separate repo, using the wiki feature on this repo, within a sub folder of this repo or somewhere else entirely?

If it's a technical guide I think it's good to make it collaborative; whether that's a section in the docs or a wiki on GitHub, I'm not sure...

...

Would it not be best to give an introduction on how to use, for example podman, and for the more specific / technical details, provide a link to that section otherwise when they update docs it will have a knock on effect

I quick podman intro could be nice, as a kind of teaser. Something along the lines of a 5 minute hello world tutorial, for example.

dyoungwd commented 5 years ago

before they install (what to expect from Silverblue, should you use manual partitioning, is dual boot possible, etc) - those could get lost in a big guide.

Official Video tutorial would maybe be handy for that - people could follow along on their phone as they install ( is there a vimo or YT channel for Silverblue? ). However not sure if using the wiki if you can embed videos - ran into issues with that previously and can't remeber if we worked it out. Sure we left it as a screenshot linking to the video.

TheOneandOnlyJakfrost commented 5 years ago

I was originally working on the advanced guide for Silverblue, based initially upon the work of Micah Abbott. I followed the outline he created verbatim. Since that initial effort, there has been many updates to Silverblue (I began with F28), and there has also been changes to various parts of Fedora's internals ( if you will) in the form of BLS adoption, some advances in Podman/Buildah/Skopeo, and an ever evolving Flatpak landscape to name a few. There is an opportunity to provide a more comprehensive layout of how to do certain things within Silverblue, that at this time you must search multiple resources to find the relevant info on. As an example, take flatpaks, I envisioned the advanced Silverblue guide detailing the various flatpak options available to a user in order to tweak their favorite app to their needs, instead of just referring them to the location where flatpak has the info, also show how to do it with Silverblue. The ostree (both rpm-ostree and libostree) is another area of detail that requires searching in at least two other locations to come up with the necessary info to tackle some of the more advanced tasks. If you go here https://miabbott.github.io/2019/01/22/silverblue-day-1.html Micah has already a very good walk through guide for new Silverblue users to follow and get rapidly up to speed on how to use it and some of what is capable. As I see it, and this is largely my opinion and open to change, I didn't mind following the format outlined since it was familiar to the community, I felt it just needed the be a "closer look" at the details of doing it with Silverblue. On Wed, 2019-05-08 at 03:45 -0700, Allan Day wrote:

The thing is, there is a comprehensive installation guide for Fedora, and I think that 95% of that is correct for Silverblue... Do we really want to maintain our own version of that 95%?

The other thing I'm conscious of is that, in many cases, people just need to know 2/3 key pieces of information before they install (what to expect from Silverblue, should you use manual partitioning, is dual boot possible, etc) - those could get lost in a big guide.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[ { "@context": "http://schema.org", "@type": "EmailMessage", "potentialAction": { "@type": "ViewAction", "target": " https://github.com/fedora-silverblue/silverblue-docs/issues/1#issuecomment-490439100 ", "url": " https://github.com/fedora-silverblue/silverblue-docs/issues/1#issuecomment-490439100 ", "name": "View Issue" }, "description": "View this Issue on GitHub", "publisher": { "@type": "Organization", "name": "GitHub", "url": "https://github.com" } } ]

miabbott commented 5 years ago

One key question we need to answer is whether we want the Silverblue docs to reproduce material that's available elsewhere. Personally, I'm unconvinced that we should be maintaining our own installation guide or our own podman docs: it's a lot of material that will inevitably end up being reproduced elsewhere.

We definitely have to find the right balance between Fedora + Silverblue docs. I originally set out to have documentation that was wholly contained within the Silverblue space, regardless of what was available in the Fedora docs. However, after toiling on the first portion of the install guide (again, knowing I was reproducing content), I'm not sure that is the right approach. Even more so, since I've not been able to dedicate the time I wanted to improving the documentation.

I think the changes that @allanday has made so far definitely make the docs more approachable and easier to use. And I agree with others commenting that we need to give some introductory documentation on how to use tools that are not typical of the Fedora Workstation experience (podman, flatpak, toolbox, ostree, rpm-ostree, etc). We should link to existing documentation where possible, but let's not be afraid of creating more comprehensive docs for a topic if they don't already exist.

I'm still partial to about 75% of the original outline as being good topics to cover; maybe we don't have to get into as much depth as I originally had in mind, but it should be enough to get users moving in the right direction.

dyoungwd commented 5 years ago

Just some feedback from twitter - someone wanting to try out Silverblue but hasn't due to lack of info for installation:

I saw it. But there is no info about size of each partition. Especially root filesystem. (link: https://twitter.com/dyoungwd/status/1125901039037755392) twitter.com/dyoungwd/statu… Quote Tweet

Dazzy @dyoungwd · 21h Replying to @dz1q @fedoracommunity and @fedora Docs can be found at (link: https://docs.fedoraproject.org/en-US/fedora-silverblue/installation/) docs.fedoraproject.org/en-US/fedora-s… @teamsilverblue

Lailah commented 5 years ago

The thing is, there is a comprehensive installation guide for Fedora, and I think that 95% of that is correct for Silverblue... Do we really want to maintain our own version of that 95%?

The other thing I'm conscious of is that, in many cases, people just need to know 2/3 key pieces of information before they install (what to expect from Silverblue, should you use manual partitioning, is dual boot possible, etc) - those could get lost in a big guide.

Maybe we could document the 5% that is different from standard Fedora, and refer to the Install Guide for the rest?