#1 Import Silverblue documentation as a basis for Kinoite's
Merged a year ago by ngompa. Opened a year ago by siosm.
Unknown source main  into  main

file modified
+2 -2
@@ -1,6 +1,6 @@

- # Fedora Docs Template

+ # Fedora Kinoite Documentation

  

- This repository contains a minimal source structure for a new Fedora Docs source.

+ This repository contains the Fedora Kinoite documentation.

  

  ## Structure

  

file modified
+12 -6
@@ -1,14 +1,20 @@

  # Name will be mostly visible in the URL. Treat it as an identifier.

- # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)

- name: pizza-factory  # <---- PLEASE MODIFY

+ # Tip: If you want to use the local preview scripts that come with this

+ # repository, please change this value in the site.yml file as well. (under

+ # site/start_page)

+ name: fedora-kinoite

  

- # Title will be visible on the page. 

- title: Pizza Factory # <---- PLEASE MODIFY

+ # Title will be visible on the page.

+ title: Fedora Kinoite

  

- # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.

+ # If you don't plan to have multiple versions of the docs (for example, to

+ # document multiple versions of some software), you can ignore this field.

+ # Otherwise, change "master" to a specific version.

  version: master

  

- # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise. 

+ # We encourage you to name the index page as "index.adoc". If you absolutely

+ # have to use a different name, please reflect it here. You can ignore this

+ # field otherwise.

  start_page: ROOT:index

  

  # This lists all the menu definitions of your component.

file modified
+8 -4
@@ -1,5 +1,9 @@

- * xref:architecture.adoc[Architecture]

- ** xref:pizza-oven.adoc[Pizza Oven]

- ** xref:pizza-dough.adoc[Pizza Dough]

- * xref:community.adoc[Community]

+ * xref:installation.adoc[Installation]

+ * xref:getting-started.adoc[Getting Started]

+ * xref:updates-upgrades-rollbacks.adoc[Updates, Upgrades & Rollbacks]

+ * xref:toolbox.adoc[Toolbox]

+ * xref:technical-information.adoc[Technical Information]

+ * xref:reading-and-resources.adoc[Reading and Resources]

+ * xref:troubleshooting.adoc[Troubleshooting]

+ * xref:contributing.adoc[Contributing]

  * xref:faq.adoc[FAQ]

@@ -1,3 +0,0 @@

- = Pizza Factory Architecture

- 

- The architecture of our pizza factory is quite simple. We bake our very expensive xref:pizza-dough.adoc[pizza dough] in a very cheap xref:pizza-oven.adoc[pizza oven]. This way, we can achieve a medicore result for a high price and a reasonable number of failures.

@@ -1,3 +0,0 @@

- = Pizza Factory Community

- 

- Our community is basically the same as the community of Fedora Docs. That's mostly because this is a template for new pieces of the Fedora Docs.

@@ -0,0 +1,60 @@

+ [[contributing]]

+ = Contributing to Fedora kinoite

+ 

+ Help us improve Fedora Kinoite by contributing to the project!

+ 

+ [[developing]]

+ == Developing Kinoite

+ 

+ If you are a developer, you can contribute to one of the several projects which make Fedora Kinoite possible. Submit your pull requests to:

+ 

+ * https://github.com/projectatomic/rpm-ostree[rpm-ostree]

+ * https://github.com/flatpak/flatpak[flatpak]

+ * https://github.com/ostreedev/ostree[ostree]

+ * https://github.com/containers/toolbox[toolbox]

+ * https://github.com/containers/libpod[podman]

+ 

+ Your contributions towards the main https://fedoraproject.org/wiki/Join[Fedora] and https://community.kde.org/Get_Involved[KDE] projects are also very welcome.

+ 

+ [[writing-documentation]]

+ == Writing Documentation

+ 

+ Creating or modifying documentation is easy. Head over to our https://pagure.io/fedora-kde/kinoite-docs[documentation] repository, fork it and create a pull request.

+ 

+ If you are not comfortable with using git, create a new topic in our https://discussion.fedoraproject.org/c/desktop/kinoite[community] or log an https://pagure.io/fedora-kde/kinoite-docs/issues[issue] describing what need to be changed.

+ 

+ [[writing-conventions]]

+ === Writing Conventions

+ 

+ When creating documentation, please follow these writing conventions:

+ 

+ * Code blocks for commands that require `root` privileges must show the `#`

+ * prompt symbol. Example:

+ 

+  # dnf install <package>

+ +

+ The `$` user prompt symbol can also be used but you must prefix the command with `sudo`. Example:

+ 

+  $ sudo dnf install <package>

+ 

+ [[reporting-issues]]

+ == Reporting Issues

+ 

+ You can report bugs and suggest features or improvements on the https://pagure.io/fedora-kde/SIG[KDE SIG issue tracker].

+ 

+ [[creating-flatpaks]]

+ == Creating Flatpaks

+ 

+ Your favourite application is not in the default repository and won't probably be added? You can do it yourself! Go through our tutorial for creating flatpaks from rpm packages:

+ 

+ * https://docs.fedoraproject.org/en-US/flatpak/tutorial/[RPM to Flatpak tutorial]

+ 

+ To become an official packager you need to go through several steps to gain all required permissions to use the Fedora infrastructure (Pagure, Koji, Bodhi).

+ There is a detailed https://fedoraproject.org/wiki/Join_the_package_collection_maintainers[wiki page] about becoming a packager.

+ 

+ Other useful links:

+ 

+ * https://pagure.io[Pagure]

+ * https://src.fedoraproject.org[Package Sources]

+ * https://koji.fedoraproject.org/koji/[Koji]

+ * https://bodhi.fedoraproject.org/[Bodhi]

file modified
+87 -5
@@ -1,7 +1,89 @@

  = Frequently Asked Questions (FAQ)

  

- [qanda]

- Can I see a built preview of this template to get a better idea about the result?::

-     Of course you can! Just look at the README of the repository — it should tell you everything.

- Is writing documentation hard and dreadful?::

-     Absolutely not. Writing documentation in asciidoc is very simple and straightforward. And in fact, writing documentation makes you very happy. Just try and see for yourself!

+ == About the project

+ 

+ Why is this project named Kinoite?::

+ 

+ We chose the Kinoite name for the following reasons:

+ * KDE based projects traditionally start with a 'K'

+ * Kinoite is a blue mineral (https://en.wikipedia.org/wiki/Kinoite[Wikipedia]), thus referring to both the 'silver' and 'blue' part of Silverblue and the blue color of the KDE logo.

+ * "Kinoite" means "There is a tree" in Japanese (https://translate.google.com/?sl=auto&tl=en&text=kinoite&op=translate[Google Translate]), thus referring to the 'tree' in 'ostree'.

+ 

+ What is Kinoite's relationship with Silverblue and Fedora CoreOS?::

+ 

+ Fedora Kinoite uses the same core technology as Fedora Silverblue and Fedora CoreOS. However, Kinoite is specifically focused on workstation/desktop use cases with the KDE Plasma desktop.

+ 

+ == About using Kinoite

+ 

+ How can I play more videos in Firefox, like YouTube?::

+ 

+ Firefox is included in the OS image for now. Until that changes, getting it to play videos works the same way as it does for the regular Fedora Workstation: find a package with the needed codecs, and install it. The one difference is that you use `rpm-ostree install` instead of `dnf install`. An alternative solution is to install the nightly Firefox, which is available as a https://firefox-flatpak.mojefedora.cz/org.mozilla.FirefoxNightly.flatpakref[Flatpak].

+ 

+ How do I create a VPN connection?::

+ 

+ `/etc` is not part of the immutable OS image, so you can just copy files into `/etc/NetworkManager/system-connections` (or let NetworkManager store them there when you recreate your connections). Certificates in `/etc/pki` need to be handled similarly.

+ 

+ How can I see what packages were updated between two commits?::

+ 

+ * If you want to compare the booted deployment with the pending deployment (or

+ * rollback deployment), simply issue:

+ 

+  $ rpm-ostree db diff

+ +

+ TIP: You can also see the RPM changelog by adding the `-c` option like so: `rpm-ostree db diff -c`

+ 

+ * If you want to see which packages were updated between two specific commits:

+ 

+ . find out which two commits you want to compare by issuing:

+ 

+  $ ostree log <ref>

+ 

+ . you can now compare the two commits by issuing:

+ 

+  $ rpm-ostree db diff <commit x> <commit y>

+ 

+ How can I check the version number of an installed package?::

+ 

+ You can simply use:

+ 

+  $ rpm -q <package>

+ 

+ How can I check if an `rpm` software package is available in the repository?::

+ 

+ At this point in time, there is no `rpm` package search function built into `rpm-ostree`. However, you can use `toolbox` with the following command:

+ 

+  $ toolbox run dnf search <package>

+ +

+ NOTE: The assumption is that you have already created a toolbox matching the version of your Fedora Kinoite installation.

+ 

+ How can I downgrade my system's kernel?::

+ 

+ If, for whatever reason, you need to downgrade the kernel, you can do so by following these steps:

+ 

+ . For the version you need to downgrade, download `<kernel>`, `<kernel-core>`, `<kernel-modules>` and `<kernel-modules-extra>` from https://koji.fedoraproject.org/koji/packageinfo?packageID=8[Koji].

+ 

+ . Install the packages downloaded on the previous step by issuing:

+ 

+  $ rpm-ostree override replace <kernel> <kernel-core> <kernel-modules> <kernel-modules-extra>

+ 

+ . Reboot the system to apply the changes.

+ 

+ How can I upgrade my system to the next major version (for instance: rawhide or an upcoming Fedora release branch), while keeping my current deployment?::

+ 

+ OSTree allows you to pin deployments (pinning ensures that your deployment of choice is kept and not discarded).

+ 

+ . Assuming that you want to keep your default deployment, issue the following command:

+ 

+  $ sudo ostree admin pin 0

+ +

+ NOTE: `0` here refers to the first deployment listed by `rpm-ostree status`

+ 

+ . Verify that you have pinned your deployment of choice by issuing:

+ 

+  rpm-ostree status

+ 

+ . After the deployment is pinned, you can upgrade your system by using the instructions found https://docs.fedoraproject.org/en-US/fedora-kinoite/updates-upgrades-rollbacks/#upgrading[here].

+ 

+ . When you have completed rebasing, reboot the system. The GRUB menu will now present you with both: the previous deployment major version entry (e.g.: *"Fedora 30.YYYYMMDD.n"*) and the new deployment major version entry (e.g.: *"Fedora 31.YYYYMMDD.n"*).

+ +

+ NOTE: At the moment it is not possible to name (pinned) deployments and their associated GRUB menu entries.

@@ -0,0 +1,143 @@

+ [[getting-started]]

+ = Getting Started

+ 

+ Kinoite is designed to be easy and straightforward to use, and specialist

+ knowledge should generally not be required. However, Kinoite is built

+ differently from other operating systems, and there are therefore some things

+ that it is useful to know.

+ 

+ Kinoite has different options for installing software, compared with a

+ standard Fedora Workstation (or other package-based Linux distributions). These

+ include:

+ 

+ * Flatpak apps: this is the primary way that (GUI) apps get installed on Kinoite.

+ * Toolbox: Used primarily for CLI apps; development, debugging tools etc.

+ * Package layering: The rpm-ostree tool used for host updates is a full hybrid

+   image/package system.  By default the system operates in pure image mode,

+   but package layering is useful for things like libvirt, drivers, etc.

+ 

+ For information on <<flatpak>> and <<package-layering,package layering>>, see below.

+ 

+ See the dedicated <<toolbox.adoc#toolbox,toolbox>> page to get started with it.

+ 

+ [[flatpak]]

+ == Flatpak

+ 

+ Flatpak is the primary way that apps can be installed on Kinoite. (For

+ information, see http://flatpak.org[flatpak.org].) Flatpak works out of the box

+ in Fedora Kinoite, and Fedora provides a small (but growing) collection of

+ apps that can be installed.

+ 

+ The other main source of Flatpak apps is https://flathub.org/home[Flathub],

+ which provides a large repository of Flatpak apps that can be installed.

+ 

+ [[flathub-setup]]

+ == Setting up Flathub

+ 

+ To setup Flathub on Fedora Kinoite, open the

+ https://flatpak.org/setup/Fedora/[Flathub setup page for Fedora] and click the

+ “Flathub repository file” button to download the Flathub configuration.

+ 

+ image::sfg_flathub_fedora.png[title="Fedora quick setup page"]

+ 

+ A popup window will show a download option for the file. The “Open with” option

+ should show “Software Install (default)”. Click on the “OK” button to start the 

+ download.

+ 

+ image::sfg_flathub_download.png[title="Flathub download options"]

+ 

+ After the download is complete, a new window will open showing the Flathub

+ repository. This window also shows the source location of the repository to be

+ installed, under the details heading (1). To start the installation of the

+ Flathub repository, click on the “Install” button (2).

+ 

+ image::sfg_flathub_install.png[title="Flathub install window"]

+ 

+ After the repository installation process is complete, the window will be

+ updated to show a “Remove" button in place of the “Install” button.

+ 

+ === Installing Flatpak apps from Flathub

+ 

+ Once the Flathub repository has been setup, it can be used to install Flatpak

+ apps. This can be done directly from the Software app, or apps can be browsed

+ on the https://flathub.org/home[Flathub website].

+ 

+ If you choose to install apps from the Flathub website, clicking "Install" will

+ download a file which will be opened by the Software app, which can then be

+ used to install the app. For example, to install

+ https://www.libreoffice.org/[LibreOffice], you first search for and open the

+ LibreOffice page, and then press the “Install” button 

+ (2). 

+ 

+ After clicking the “Install” button, a download information window will be

+ shown. Verify the correct Flatpak has been downloaded and then click on the

+ “OK” button to begin installing the LibreOffice application.

+ 

+ image::sfg_libreoffice_install.png[title="LibreOffice Flatpak download"]

+ 

+ Once the Flatpak is downloaded, the Software application will open a new window

+ with an “Install” button (2). Click this button to begin installation.

+ 

+ === Flatpak command line

+ 

+ In addition to using the Software app to install Flatpak apps, it is also

+ possible to use the `flatpak` command line interface. See the

+ http://docs.flatpak.org/en/latest/using-flatpak.html[Flatpak documentation] for

+ how to do this.

+ 

+ [[package-layering]]

+ == Package layering

+ 

+ Package layering works by modifying your Kinoite installation. As the name

+ implies, it works by extending the packages from which Kinoite is composed.

+ 

+ Good examples of packages to be layered would be:

+ 

+ * `fish`: An alternative Unix shell

+ * `sway`: A Wayland tiling compositor

+ * `libvirt`: The libvirt daemon

+ 

+ Most (but not all) RPM packages provided by Fedora can be installed on

+ Kinoite using this method.

+ 

+ Currently, using package layering creates a new "deployment", or bootable

+ filesystem root.  It does not affect your current root.  This preserves

+ rollback and the transactional model, but means that the system must be

+ rebooted after a package has been layered.  Eventually this limitation may be

+ lifted, but it's generally expected that you use package layering sparingly,

+ and use `flatpak` and `dnf install` inside a `toolbox` etc.

+ 

+ Package layering is generally done from the command line. However, the Software

+ application does rely on it for installing a small number of apps that are

+ currently difficult to install as Flatpaks.

+ 

+ === Installing packages

+ 

+ Packages can be installed on Kinoite using:

+ 

+  $ rpm-ostree install <package name>

+ 

+ This will download the package and any required dependencies, and recompose

+ your Kinoite image with them. `rpm-ostree` uses standard Fedora package

+ names, which can be searched using DNF (this is not available on a Kinoite

+ host, but can be used in a link:toolbox[toolbox]).

+ 

+ Once a package has been installed in this manner, it will be kept up-to-date as

+ new versions are released and as the base operating system is updated.

+ 

+ === Replacing packages

+ 

+ In some scenarios, you may want to test out a new version of `podman` or

+ `kernel` or other packages that live on the host.  The `rpm-ostree override`

+ command can be used to replace a package with a different version.  Currently

+ you must download the RPM packages locally, and then run:

+ 

+  $ rpm-ostree override replace <path to package>

+ 

+ You may also use `override remove` to effectively "hide" packages; they will

+ still exist in the underlying base layer, but will not appear in the booted

+ root.

+ 

+ Removing and replacing packages using package layering is not generally

+ recommended. For more information, see the

+ https://coreos.github.io/rpm-ostree/administrator-handbook/[rpm-ostree documentation].

file modified
+26 -6
@@ -1,9 +1,29 @@

- = The Pizza Project

- John Doe; Jane Doe

- :page-authors: {author}, {author_2}

+ = Fedora Kinoite User Guide

  

- The Pizza Project is a useful project with a very bad name — it helps you with writing some new documentation for Fedora.

+ Welcome to the Fedora Kinoite user guide!

  

- In fact, this is just a source template for a new piece of the Fedora Docs.

+ // image::kinoite-logo.svg[Kinoite logo]

  

- image::pizza.png[Pizza]

+ _Fedora Kinoite_ is an immutable desktop operating system. It aims to be extremely stable and reliable. It also aims to be an excellent platform for developers and for those using container-focused workflows.

+ 

+ [[introduction]]

+ == Introduction to Kinoite

+ 

+ Kinoite is a variant of the Fedora KDE Spin. It looks, feels and behaves like a regular desktop operating system, and the experience is similar to what you find with using a standard Fedora KDE Spin.

+ 

+ However, unlike other operating systems, Kinoite is immutable. This means that every installation is identical to every other installation of the same version. The operating system that is on disk is exactly the same from one machine to the next, and it never changes as it is used.

+ 

+ Kinoite's immutable design is intended to make it more stable, less prone to bugs, and easier to test and develop. Finally, Kinoite's immutable design also makes it an excellent platform for containerized applications as well as container-based software development. In each case, applications (apps) and containers are kept separate from the host system, improving stability and reliability.

+ 

+ Kinoite's core technologies have some other helpful features. OS updates are fast and there's no waiting around for them to install: just reboot as normal to start using the next version. With Kinoite, it is also possible to roll back to the previous version of the operating system, if something goes wrong.

+ 

+ [[this-guide]]

+ == About this guide

+ 

+ In most cases, Kinoite behaves like a standard Fedora KDE installation, and the https://docs.fedoraproject.org/[standard Fedora documentation] can be used. This guide covers those areas where Kinoite differs from a standard Fedora KDE, including:

+ 

+ * link:installation[OS installation]

+ * link:getting-started[Installing apps and software]

+ * link:updates-upgrades-rollbacks[OS upgrades and rollbacks]

+ 

+ The primary audience for these docs are new users, who aren't expected to have specialist knowledge or technical knowledge about Kinoite's internals. However, some background link:technical-information[technical information] is provided, for those who are interested and want to learn more.

@@ -0,0 +1,78 @@

+ = Installing Kinoite

+ 

+ Fedora Kinoite can be installed in the same way as Fedora Workstation, and the

+ official Fedora installation guide can be followed for your Fedora version.

+ See the https://docs.fedoraproject.org/en-US/docs/[Fedora documentation site]

+ for more details.

+ 

+ [[before-you-begin]]

+ == Before you begin

+ 

+ As with installing any new operating system, it is important to back up any

+ data that you want to save before starting, and have a clear understanding of

+ the consequences of what you are doing.

+ 

+ Kinoite is intended to provide the full range of capabilities that you would

+ expect from an installation of Fedora Workstation. However, there are some

+ differences in terms of which applications can be installed, and how the

+ operating system environment works.

+ 

+ It is therefore recommended that you read this user guide before deciding to

+ install Kinoite. It is also recommended that you determine whether Kinoite

+ meets the specific needs or requirements that you might have. If you are

+ uncertain about this, Kinoite can also be tested in a virtual machine prior to

+ installation or booted from a flash drive using Fedora Media Writer.

+ 

+ [[known-limitations]]

+ == Known limitations

+ 

+ *Kinoite does not provide a fully functional experience for dual booting or

+ manual partitioning.*

+ 

+ It is possible to make Kinoite work for both dual boot and manual partitioning,

+ and some guidance is provided on manual partitioning below.  However, there are

+ hazards involved in both cases, and you should only attempt to use these

+ features if you have done the necessary research, and are confident that you

+ can overcome any issues that you might encounter.

+ 

+ [[getting-kinoite]]

+ == Getting Kinoite

+ 

+ If you are using Fedora Media Writer, Kinoite should be listed as a download

+ option. However, if it isn't, or if you want to download it manually, an

+ install image can be downloaded from https://kinoite.fedoraproject.org/[the

+ main Kinoite website].

+ 

+ Once you have got your copy of Kinoite, it can be installed in the usual

+ manner. We hope that you love it!

+ 

+ [[manual-partition]]

+ == Manual Partitioning

+ 

+ As described above, there are known issues with manual partitioning on Kinoite,

+ and it should be used with caution. The following notes are intended as hints

+ for those attempting it, and should not be treated as recommended practice.

+ 	Automatic partitioning is recommended.

+ 

+ With Kinoite, only certain mounts can be manually specified as partitions.

+ These include:

+ 

+ * `/boot`

+ * `/var`

+ * Subdirectories under `/var`, including:

+ ** `/var/home` (Kinoite has a symlink from `/home` to `/var/home`)

+ ** `/var/log`

+ ** `/var/containers`

+ * The root filesystem: `/`

+ 

+ The Fedora installer is not aware of these restrictions and will accept custom

+ partitions without error, even if they are incompatible with Kinoite.

+ 

+ image::faw-manual-partition-complete.png[title="Partitioning Complete"]

+ 

+ The above screenshot shows a typical configuration with manual partitioning,

+ with partitions for `/boot`, `/`, `swap` and `/var/home`.

+ 

+ Manual partitioning on Kinoite can be done with `Btrfs`,

+ https://en.wikipedia.org/wiki/Logical_Volume_Manager_%28Linux%29[LVM], as well

+ as standard partitions or an `xfs` filesystem.

@@ -1,3 +0,0 @@

- = Pizza Dough Architecture

- 

- I would never thought that a pizza dough can have an architecture. Yet here we are.

@@ -1,3 +0,0 @@

- = Pizza Oven Architecture

- 

- Pizza oven architecture would be described on this page. Since this is just a template, I choose to disappoint you and not describe the pizza oven architecture.

@@ -0,0 +1,18 @@

+ = Reading & Resources

+ 

+ This page is a list of further reading and resources for Kinoite.

+ 

+ == Technology websites and documentation

+ 

+ * https://buildah.io/[Buildah] - build OCI container images

+ * http://flatpak.org[Flatpak] - next-generation desktop app framework

+ * https://ostreedev.github.io/ostree/[ostree] - OS image composition and updates

+ * https://podman.io/[podman] - daemonless container engine

+ * https://coreos.github.io/rpm-ostree/[rpm-ostree] - hybrid image/package system

+ 

+ == Documents

+ 

+ * link:{attachmentsdir}/team-silverblue-origins.pdf[Team Silverblue - The Origins] - PDF that explains the motivations, goals, and history behind Silverblue, on which Kinoite is based

+ * link:{attachmentsdir}/flatpak-print-cheatsheet.pdf[Flatpak Cheat Sheet] - PDF with common flatpak commands

+ * link:{attachmentsdir}/silverblue-cheatsheet.pdf[rpm-ostree Cheat Sheet] - PDF with common rpm-ostree commands

+ * link:{attachmentsdir}/container-commandos.pdf[Container commandos] -  a playful introduction to tools such as podman, cri-o and buildah by Máirín Duffy and Dan Walsh. Print it out, and learn as you color!

@@ -0,0 +1,57 @@

+ [technical-information]

+ = Technical Information

+ 

+ This page provides some background technical information on Kinoite, 

+ including information on the core technologies used to build it, as well as the 

+ filesystem layout.

+ 

+ Users should not need to know this information. It is provided here for those 

+ who are interested in the technical details or those who want to use Kinoite 

+ in a non-standard manner.

+ 

+ [[ostree-rpm-ostree]]

+ == ostree and rpm-ostree

+ 

+ https://ostreedev.github.io/ostree/[ostree] is the core technology that is 

+ used to compose, deploy and update Kinoite. ostree operates in a similar 

+ manner to a version control system, but it operates on entire filesystem trees. 

+ It is often described as “Git for operating system binaries”.

+ 

+ For Kinoite installs, ostree is responsible for deploying and updating the OS 

+ image (including everything below `/` that is not symlinked into `/var`). It 

+ also updates `grub.cfg` entries to point to the current image.

+ 

+ https://coreos.github.io/rpm-ostree/[rpm-ostree] builds on top of 

+ ostree, and makes it possible to install RPMs as a “layer” on top of an ostree 

+ image. This makes it possible to install RPMs on Kinoite.

+ 

+ When a package is installed with `rpm-ostree`, a new OS image is composed by 

+ adding the RPM payload to the existing OS image, and creating a new, combined 

+ image. To see the newly installed RPMs, the system needs to be rebooted with 

+ the new image. rpm-ostree also takes care of recreating the layered image 

+ whenever you update the base OS image.

+ 

+ [[filesystem-layout]]

+ == Kinoite filesystem layout

+ 

+ On Kinoite, the root filesystem is immutable. This means that `/`, `/usr` 

+ and everything below it is read-only.

+ 

+ `/var` is where all of Kinoite's runtime state is stored. Symlinks are used 

+ to make traditional state-carrying directories available in their expected 

+ locations. This includes:

+ 

+ * `/home` → `/var/home`

+ * `/opt` → `/var/opt`

+ * `/srv` → `/var/srv`

+ * `/root` → `/var/roothome`

+ * `/usr/local` → `/var/usrlocal`

+ * `/mnt`→ `/var/mnt`

+ * `/tmp` → `/sysroot/tmp`

+ 

+ This means that separate home partitions should be mounted on `/var/home`.

+ 

+ For a more detailed explanation of Kinoite's filesystem layout, refer to the 

+ excellent 

+ https://ostreedev.github.io/ostree/adapting-existing/[libostree 

+ documentation].

@@ -0,0 +1,114 @@

+ [[toolbox]]

+ = Toolbox

+ 

+ As an immutable host, Kinoite is an excellent platform for container-based development and, for working with containers, https://buildah.io/[buildah] and https://podman.io/[podman] are recommended.

+ 

+ Kinoite also comes with the https://github.com/containers/toolbox[toolbox] utility, which uses containers to provide an environment where development tools and libraries can be installed and used.

+ 

+ Toolbox makes it easy to use a containerized environment for everyday software development and debugging. On immutable operating systems, like https://kinoite.fedoraproject.org/[Fedora Kinoite], it  provides a familiar package-based environment in which tools and libraries can be installed and used. However, toolbox can also be used on package-based systems.

+ 

+ [[toolbox-why-use]]

+ == Why use toolbox?

+ 

+ Using toolbox containers to install development tools offers a number of advantages:

+ 

+ * It keeps the host OS clean and stable, and helps to avoid the clutter that can happen after installing lots of development tools and packages.

+ * Containers are a safe space to experiment: if things go wrong, it's easy to throw a toolbox away and start again.

+ * Containers are a good way to isolate and organise the dependencies needed for different projects.

+ 

+ [[toolbox-how-it-works]]

+ == How it works

+ 

+ Toolbox takes the work out of using containers, by providing a small number of simple commands to  create, enter, list and remove containers. It also integrates toolbox containers into your regular working environment, to make it easy for you to use them as an everyday development space.

+ 

+ Each toolbox container is an environment that you can enter from the command line. Inside each one, you will find:

+ 

+ * Your existing username and permissions

+ * Access to your home directory

+ * Common command lines tools, including the DNF package manager

+ 

+ In other words, toolbox containers look, feel and behave like a standard Linux command line environment.

+ 

+ In most cases, when a command is run inside a container, the program from inside the container is used. However, there are a few special cases where the program on the host is used instead (using `flatpak-spawn`). One example of this is the toolbox command itself; this makes it possible to use toolbox from inside toolbox containers.

+ 

+ [[toolbox-installation]]

+ == Installation

+ 

+ === Fedora Kinoite

+ 

+ Toolbox is preinstalled on Fedora Kinoite 30 or newer. On older versions, it can be installed with the following command:

+ 

+  $ rpm-ostree install toolbox

+ 

+ This will install toolbox as a layered RPM.

+ 

+ === Fedora Workstation

+ 

+ Toolbox can be installed on Fedora Workstation (or any package-based version of Fedora) with the following command:

+ 

+  $ sudo dnf install toolbox

+ 

+ [[toolbox-first-toolbox]]

+ == Your first toolbox

+ 

+ Once toolbox is installed, two simple commands are required to get started:

+ 

+  $ toolbox create

+ 

+ This will download an OCI image and create a toolbox container from it. Once this is complete, run:

+ 

+  $ toolbox enter

+ 

+ Once inside the toolbox, you can access common command line tools, and install new ones using DNF. 

+ 

+ NOTE: When the prompt is inside a toolbox, it is prepended with a diamond: this indicates that the prompt is inside a toolbox container. The diamond symbol may not be present if you use a custom shell theme.

+ 

+ [[toolbox-commands]]

+ == Commands and usage

+ 

+ `toolbox create [--container <name>]`::

+ 

+ Creates a toolbox container. This will download an OCI image if one isn't available (this is required to create the container). By default a Fedora image matching the version of the host is used. Used without options, `toolbox create` will automatically name the container it creates. To create additional toolboxes, use the  ``--container <name>`` option.

+ 

+ `toolbox enter [--container <name>]`::

+ 

+ Enters a toolbox for interactive use. Used without options, `toolbox enter` opens the default toolbox. If there is more than one toolbox, use the `--container name` option to specify the toolbox to enter.

+ 

+ `toolbox run [--container <name>] <cmd> <arg ...>`::

+ 

+ Runs a command in a toolbox without entering it. Used without options, `toolbox run` runs the command in the default toolbox. If there is more than one toolbox, use the `--container name` option to specify the toolbox to be used.

+ 

+ `toolbox list`::

+ 

+ Lists local toolbox images and containers.

+ 

+ `toolbox rm [--force] <name>`::

+ 

+ Removes one or more toolbox containers. The `--force` option removes the container even if it is running.

+ 

+ `toolbox rmi [--force] <name>`::

+ 

+ Removes one or more toolbox images.

+ 

+ `toolbox --help`::

+ 

+ Lists available commands.

+ 

+ === Exiting a toolbox

+ 

+ To return to the host environment, either run `exit` or quit the current shell (typically Ctrl+D).

+ 

+ [[toolbox-under-the-hood]]

+ == Under the hood

+ 

+ Toolbox uses the following technologies:

+ 

+ * https://www.opencontainers.org/[OCI container images]

+ * https://podman.io/[Podman]

+ 

+ [[toolbox-contact]]

+ == Contact and issues

+ 

+ To report issues, make suggestions, or contribute fixes, see https://github.com/containers/toolbox[toolbox's GitHub project].

+ 

+ To get in touch with toolbox users and developers, use https://discussion.fedoraproject.org/[Fedora's Discourse instance], or join the #fedora-kde IRC channel on Freenode.

@@ -0,0 +1,215 @@

+ = Troubleshooting

+ 

+ Kinoite is a radically new way of deploying and managing your

+ desktop operating system, so you may occasionally run into problems

+ while going through your day to day.  Below are some of the more

+ common problems reported and any workarounds for those problems.

+ 

+ == "Forbidden base package replacements"

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/415[GitHub Issue]

+ 

+ This can happen when a package that is being layered has a

+ dependency on a package that is in the base OS.  In the

+ problematic case, the layered package requires a newer version

+ of the dependent package which is not available in the base OS.

+ 

+ In most cases, waiting for a newer OSTree compose will resolve

+ this problem.  The dependent package will be updated in the compose

+ and the package that was going to be layered will be successful.

+ 

+ However, if you continue to encounter this problem with a newer

+ compose, you can try to cleanup the metadata with `rpm-ostree cleanup -m`

+ and then retrying the `rpm-ostree install`.

+ 

+ Alternatively, you can try rebasing to any `updates` ref,

+ like `fedora/30/updates/x86_64` after the `cleanup` operation.

+ 

+ == Installing packages to `/opt` or `/usr/local`

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/233[GitHub Issue]

+ 

+ Installing into `/opt` was commonly raised as a problem when users where

+ trying to install Google Chrome.  A partial https://github.com/projectatomic/rpm-ostree/pull/1795[solution] has been implemented

+ that allows users to layer Google Chrome, however it is not a complete

+ solution for applications that write mutable data to `/opt`.

+ 

+ == Using Nvidia drivers

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/1091[GitHub Issue]

+ 

+ Users have long wanted to use their Nvidia GPUs on their Kinoite systems.

+ Thankfully, recent changes to the `akmods` and `kmodtools` packages were

+ made by https://twitter.com/gnomealex[Alex Larsson] to allow for normal

+ installation of the Nvidia drivers.

+ 

+  # rpm-ostree install kmod-nvidia xorg-x11-drv-nvidia

+ 

+ You can read more about the work that Alex did on his https://blogs.gnome.org/alexl/2019/03/06/nvidia-drivers-in-fedora-silverblue/[blog].

+ 

+ == SELinux problems

+ 

+ As users work with Kinoite day-to-day, it is possible that they have modified

+ the default SELinux policy in an effort to workaround one or more problems related

+ to SELinux. This is usually done when a user sees a SELinux denial in the journal.

+ If this is the case and one wishes to revert back to the default SELinux policy,

+ you can try these set of actions.

+ 

+ . Check the state of the SELinux policy

+ +

+  $ sudo ostree admin config-diff | grep policy

+  M    selinux/targeted/active/policy.linked

+  M    selinux/targeted/active/policy.kern

+  M    selinux/targeted/policy/policy.31

+  A    selinux/targeted/policy/policy.30

+ +

+ If anything is returned by this command, then your SELinux policy has been modified

+ from the default.

+ +

+ .  Copy the default SELinux policy shipped in the OSTree compose

+ +

+  $ sudo cp -al /etc/selinux{,.bak}

+  $ sudo rsync -rlv /usr/etc/selinux/ /etc/selinux/

+ +

+ After doing this, the output from `ostree admin config-diff | grep policy` should

+ no longer indicate the policy is modified.

+ +

+ If your policy still appears to be modified, you can try the following approach.

+ +

+ .  Remove the SELinux policy; copy in the default policy

+ +

+  $ sudo rm -rf /etc/selinux

+  $ sudo cp -aT /usr/etc/selinux /etc/selinux

+ +

+ After this, the `ostree admin config-diff | grep policy` command should return

+ no modifications.

+ 

+ == Unable to add user to group

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/29[GitHub Issue]

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/49[GitHub Issue]

+ 

+ Due to how `rpm-ostree` handles user + group entries, it may not be possible

+ to use `usermod -a -G` to add a user to a group successfully.  Until the

+ `rpm-ostree` moves to using `systemd sysusers`, users will have to

+ populate the `/etc/group` file from the `/usr/lib/group` file before they

+ can add themselves to the group.  For example, if you wanted to add a user

+ to the `libvirt` group:

+ 

+  # grep -E '^libvirt:' /usr/lib/group >> /etc/group

+  # usermod -aG libvirt username

+ 

+ == `ostree fsck` reports file corruption

+ 

+ It is possible to end up in a situation where one or more files on the disk

+ have become corrupted or missing.  In this case, `ostree fsck` will report

+ errors in certain commits.  The https://github.com/ostreedev/ostree/pull/345#issuecomment-262263824[workaround]

+ in this case is to mark the entire OSTree commit as partially retrieved and then re-pull the commit.

+ 

+ == Read-only `/boot/efi` prevents any upgrades

+ 

+ https://github.com/projectatomic/rpm-ostree/issues/1380[GitHub Issue]

+ 

+ This issue is most commonly seen when users have installed Kinoite

+ on Apple hardware.  The `/boot/efi` partition on Apple hardware is

+ formatted as HFS+ and is not always resilient to power failures or

+ other kinds of hard power events.

+ 

+ Since Kinoite now includes the `hfsplus-tools` package in the base

+ compose, it has become relatively easy for users to workaround this

+ kind of error.

+ 

+  # umount /boot/efi

+  # fsck.hfsplus /dev/sda1

+  # mount -o rw /boot/efi

+ 

+ See the linked issue for additional details.

+ 

+ == Unable to install Kinoite on EFI systems

+ 

+ https://bugzilla.redhat.com/show_bug.cgi?id=1575957[Bugzilla Issue]

+ 

+ Users have reported that they cannot install Kinoite on an EFI based

+ system where they previously had another OS installed.  The error that

+ is often observed looks like:

+ 

+  ostree ['admin', '--sysroot=/mnt/sysimage', 'deploy', '--os=fedora-workstation', 'fedora-workstation:fedora/28/x86_64/workstation'] existed with code -6`

+ 

+ A couple of possible workarounds exist:

+ 

+ * During the install process, select "Custom Partitioning" and create an additional EFI partition. Assign the newly created EFI partition to `/boot/efi`. You will then be able to boot the previous OS(s) alongside Fedora Kinoite. If this workaround is not successful follow the below step.

+ * Reformat the EFI partition on the host during the install process. This can be done by selecting "Custom Partitioning" and checking the `Reformat` box when creating the `/boot/efi` partition.

+ 

+ WARNING: Choosing to reformat `/boot/efi` will likely result in the inability

+ to boot any other operating systems that were previously installed. Be sure that

+ you have backed up any important data before using this workaround.

+ 

+ == `toolbox: failed to list images with com.redhat.component=fedora-toolbox`

+ 

+ IMPORTANT: As of `podman` version `1.4.0` this workaround is not necessary. Ensure `podman` is up to date by issuing `rpm-ostree upgrade` before attempting this workaround.

+ 

+ When issuing the `toolbox list` command, systems using `podman` versions newer than `1.2.0`, will generate the following error:

+ 

+  toolbox: failed to list images with com.redhat.component=fedora-toolbox

+ 

+ TIP: The following workaround might be useful for other `toolbox` errors caused by `podman` versions greater than `1.2.0`. See https://github.com/debarshiray/toolbox/issues/169#issuecomment-495193902[Toolbox Github Repo]

+ 

+ As a workaround, it is possible to override `podman` packages newer than version `1.2.0` by issuing:

+ 

+  $ rpm-ostree override --remove=podman-manpages replace https://kojipkgs.fedoraproject.org//packages/podman/1.2.0/2.git3bd528e.fc30/x86_64/podman-1.2.0-2.git3bd528e.fc30.x86_64.rpm

+ 

+ Reboot the system to apply the changes.

+ 

+ For reference, it is also possible to override the package by following these steps: 

+ 

+ . Download `podman-1.2.0-2.git3bd528e.fc30.x86_64.rpm` from https://kojipkgs.fedoraproject.org//packages/podman/1.2.0/2.git3bd528e.fc30/x86_64/podman-1.2.0-2.git3bd528e.fc30.x86_64.rpm[Koji]

+ . Remove `podman-manpages` issuing: `rpm-ostree override remove podman-manpages`

+ . Override the currently installed `podman` package (using the package you have downloaded on the first step) by: `rpm-ostree override replace podman-1.2.0-2.git3bd528e.fc30.x86_64.rpm`

+ 

+ You can now reboot the system for the change to take effect.

+ 

+ To revert this workaround issue the following command:

+ 

+  $ rpm-ostree override reset podman; rpm-ostree override reset podman-manpages

+ 

+ == Unable to enter a toolbox due to permissions errors

+ 

+ https://github.com/containers/libpod/issues/3187[GitHub Issue]

+ 

+ With certain versions of `podman`, trying to enter a toolbox will result in

+ errors. You can fix this by resetting the permissions on the overlay-containers

+ with the following command.

+ 

+  $ sudo chown -R $USER ~/.local/share/containers/storage/overlay-containers

+ 

+ This will reset the permissions on your containers and allow you to enter them again.

+ 

+ == Running `restorecon`

+ 

+ WARNING: You should never run `restorecon` on a Kinoite host.  See the following

+ bug for details - https://bugzilla.redhat.com/show_bug.cgi?id=1259018

+ 

+ However, if you happened to do this, it is possible to recover.

+ 

+ 1.  Boot with `enforcing=0` on the kernel command line

+ 2.  Create a new, "fixed" commit locally

+ 3.  Deploy the new "fixed" commit

+ 4.  Run `restorecon`

+ 5.  Reboot

+ 6.  Cleanup

+ 

+  $ rpm-ostree status -b | grep BaseCommit

+                  BaseCommit: 696991d589980aeaef5eda352dd7ad3d33c444c789c209f793a84bc6e7269aee

+  $ sudo ostree checkout -H 696991d589980aeaef5eda352dd7ad3d33c444c789c209f793a84bc6e7269aee /ostree/repo/tmp/selinux-fix

+  $ sudo ostree fsck --delete

+  $ sudo ostree commit --consume --link-checkout-speedup --orphan --selinux-policy=/ /ostree/repo/tmp/selinux-fix

+  $ sudo restorecon -Rv /var

+  $ sudo restorecon -Rv /etc

+  $ sudo ostree admin deploy fedora-atomic:fedora/35/x86_64/kinoite

+  $ sudo reboot

+ 

+ The caveat to this recovery is that your layered packages will be removed; you'll

+ need to relayer them after the recovery.

+ 

+ See this upstream comment for additional details - https://github.com/ostreedev/ostree/issues/1265#issuecomment-484557615

@@ -0,0 +1,70 @@

+ [[updates-upgrades-rollbacks]]

+ = Updates, Upgrades & Rollbacks

+ 

+ Installing updates with Kinoite is easy and fast (much faster than other 

+ operating systems). It also has a special rollback feature, in case anything 

+ goes wrong.

+ 

+ [[updating]]

+ == Updating Kinoite

+ 

+ OS updates in Kinoite are fully integrated into the desktop; you will be 

+ automatically notified when an update is available. The standard behavior is 

+ to automatically download the update (this can be changed from the 

+ update preferences in Software).

+ 

+ Once an update is ready, it is just a matter of rebooting to start using the 

+ new version. There is no waiting for the update to be installed during this 

+ reboot.

+ 

+ If you'd prefer, it is also possible to update using the command line. To do 

+ this, run:

+ 

+  $ rpm-ostree upgrade

+ 

+ This will check for new updates and download and install them if they are 

+ available. Alternatively, to check for available updates without downloading 

+ them, run:

+ 

+  $ rpm-ostree upgrade --check

+ 

+ [[upgrading]]

+ == Upgrading between major versions

+ 

+ Upgrading between major versions (such as from Fedora 32 to Fedora 33) can  

+ be completed using the Software application. Alternatively, Kinoite can be 

+ upgraded between major versions using the `ostree` command.

+ 

+ First, verify the branch is available. You can print all available branches with this command:

+ 

+  $ ostree remote refs fedora

+ 

+ After you verify the name of your branch, you are ready to proceed. For example, to upgrade to Kinoite 33, the 

+ command is:

+ 

+ NOTE: Currently, the default remote for Kinoite 35 is named `fedora`. If this is not the case for your system, you can find out the remote name by issuing: `ostree remote list`.

+ 

+  $ rpm-ostree rebase fedora:fedora/35/x86_64/kinoite

+ 

+ The process is very similar to a system update: the new OS is downloaded and

+ installed in the background, and you just boot into it when it is ready.

+ 

+ [[rolling-back]]

+ == Rolling back

+ 

+ Kinoite keeps a record of the previous OS version, which can be switched to 

+ instead of the latest version. While this shouldn't usually be necessary, it 

+ can be helpful if there is a problem with an update or an upgrade (rollbacks 

+ work the same way for both), as well as for development purposes.

+ 

+ There are two ways to roll back to the previous version:

+ 

+ . Temporary rollbacks: to temporarily roll back to a previous version, simply 

+   reboot and select the previous version from the boot menu (often known as the

+   grub menu).

+ . Permanent rollbacks: to permanently switch back to the previous deployment,

+   use the `rpm-ostree rollback` command.

+ 

+ After rolling back, you will technically be on an old OS version, and may be 

+ prompted to update. Updating will undo the rollback, so should be avoided if 

+ you want the rollback to stay in effect.

file modified
+6 -6
@@ -1,6 +1,6 @@

- site: 

+ site:

    title: Local Preview

-   start_page: pizza-factory::index

+   start_page: fedora-kinoite::index

  content:

    sources:

     - url: .
@@ -10,11 +10,11 @@

      url: https://asamalik.fedorapeople.org/ui-bundle.zip

      snapshot: true

    default_layout: with_menu

- output: 

-   clean: true 

+ output:

+   clean: true

    dir: ./public

-   destinations: 

-   - provider: archive 

+   destinations:

+   - provider: archive

  runtime:

    pull: true

    cache_dir: ./cache

Imported from https://github.com/fedora-silverblue/silverblue-docs

Did a sed to replace most Silverblue -> Kinoite references and some misc cleanup.

We should have a Kinoite section there.

This should be kinoite.fedoraproject.org

silverblue.fedoraproject.org -> kinoite.fedoraproject.org

This should be adjusted to match what would be done with Kinoite.

This should be talking about Kinoite 35 with kinoite remote.

1 new commit added

  • More Silverblue -> Kinoite fixes
a year ago

2 new commits added

  • More Silverblue -> Kinoite fixes
  • Import Silverblue documentation as a basis for Kinoite's
a year ago

Should have fixed most of the comments with latest push

Kinoite category has been created on Discourse.

Pull-Request has been merged by ngompa

a year ago