diff --git a/source/clear-linux/concepts/figures/mixer-about-1.png b/source/clear-linux/concepts/figures/mixer-about-1.png new file mode 100644 index 00000000..8120a068 Binary files /dev/null and b/source/clear-linux/concepts/figures/mixer-about-1.png differ diff --git a/source/clear-linux/concepts/figures/mixer-about-2.png b/source/clear-linux/concepts/figures/mixer-about-2.png new file mode 100644 index 00000000..83f03375 Binary files /dev/null and b/source/clear-linux/concepts/figures/mixer-about-2.png differ diff --git a/source/clear-linux/concepts/mixer-about.rst b/source/clear-linux/concepts/mixer-about.rst index 1caf3764..58799554 100644 --- a/source/clear-linux/concepts/mixer-about.rst +++ b/source/clear-linux/concepts/mixer-about.rst @@ -3,21 +3,83 @@ Mixer ##### -Mixing refers to composing a custom, versioned image of |CL-ATTR| for a -specific use case. While upstream |CL| provides options to install bundles -for various capabilities, some developers and OSVs may wish to either -augment the operating system with functionality from their own packages -or modify the structure of current bundles. Mixing offers a method to add -capabilities while retaining the ability to stay up to date with an upstream -version of |CL|. +|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers +many images for different deployment environments and use-cases. There are +hundreds of bundles that will meet most, if not all, of your OS and software +needs. -Mixing is a multi-step process that starts with installing the mixer bundle -using swupd. You will also need a working knowledge of -:abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a -detailed guide on how to create a |CL| mix, visit :ref:`mixer`. +However, if you need additional customization or content, |CL| provides the +mixer tool to customize the OS. With mixer, there are two approaches to +customization: + +* :ref:`create-mix` +* :ref:`create-mixin` + +Which approach you choose will depend on the level of customization that you +need. + +.. _create-mix: + +Create a mix +============ + +The first approach is to use the mixer tool to create a derivative of the |CL| +that contains your custom software. This is known as creating a mix. In your +mix, you can + +* Use any existing upstream bundles with no modification. +* Redefine what goes into existing bundles. +* Create completely new, custom bundles with your own custom packages. + +With mixer you are not required to incorporate every upstream release into your +mix. You decide which upstream versions to update your derivative to, as +illustrated in Figure 1. + +.. figure:: figures/mixer-about-1.png + :scale: 75% + :alt: Creating a custom mix. + + Figure 1: With a custom mix, you add your custom bundle and decide which + upstream versions to update your mix to, on your own release cycle. + +Creating your own mix forks away from the |CL| upstream and requires that you +act as your own OSV. There is a greater level of responsibility, requiring +more infrastructure and processes to adopt. However, with this approach, you +have a higher degree of control and customization of your custom |CL|. + + +.. _create-mixin: + +Create a mixin +============== + +The second approach is to use the mixin tool, a light wrapper for mixer, to +create custom bundles and sideload them into your upstream version of |CL|. +This is known as a mixin. A mixin is useful when you need to add custom or 3rd +party content but want to keep on the upstream update cycle, as shown in +Figure 2. You can also create new bundles using upstream packages. + +.. figure:: figures/mixer-about-2.png + :scale: 75% + :alt: Creating a custom mix. + + Figure 2: With a mixin you can add custom bundles, but stay on upstream. + +Mixin is primarily intended for end users. It is easier to adopt as it does +not require breaking from upstream or acting as an OSV. With mixin + +* You are responsible for maintaining and testing your custom bundle(s). +* You retain access to all upstream bundles and updates. +* You can easily revert your system back to the upstream version. Related topics ============== -* :ref:`swupd-about` +|CL| provides flexibility in how you customize your OS. Learn more about mixer +and related topics to decide which customization approach is best for you. + +* :ref:`mixer` +* :ref:`mixin` * :ref:`bundles-about` +* :ref:`swupd-about` +* :ref:`deploy-at-scale` diff --git a/source/clear-linux/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst index 2f0bced2..5b3867df 100644 --- a/source/clear-linux/guides/deploy-at-scale.rst +++ b/source/clear-linux/guides/deploy-at-scale.rst @@ -1,4 +1,4 @@ -.. _deploy-at-scale.rst: +.. _deploy-at-scale: Deploy at Scale ###############