Merge branch 'development' of https://github.com/intelkevinputnam/clear-linux-documentation into development

Merge branch 'mv-about-architect' of https://github.com/mvincerx/clear-linux-documentation into development
Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
2026-08-24 00:15:57 +00:00 · 2020-04-03 19:45:38 -07:00 · 2020-04-03 19:44:57 -07:00 · 2020-04-03 19:29:23 -07:00 · 2020-04-03 18:06:51 -07:00 · 2020-03-30 17:02:59 -07:00
125 changed files with 3391 additions and 1147 deletions
@@ -0,0 +1,23 @@
+name: Check
+
+on: [pull_request]
+
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+        
@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+        - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:developmentHTML
@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    branches:
+        - publish
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:latestHTML
+    - name: Publish the docs
+      run: |
+        wget ${{secrets.PUBLISH_URL}}
+        cat clearlinux-latest
@@ -176,7 +176,16 @@ displays a preview of the site at http://localhost:8000 on your local machine.

 To stop the web server simply use ``ctrl-c``.

+<<<<<<< HEAD
+
+### Silly header to test dev branch
+
+
+
+.. _Clear Linux\* OS documentation:  https://clearlinux.org/documentation
+=======
 .. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
+>>>>>>> 550b919bc013159156f80110867aa1ab7c858d29
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 .. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html
@@ -5,5 +5,5 @@ sphinx_rtd_theme
 sphinx-intl==2.0.0
 sphinx-sitemap==1.0.2
 Jinja2==2.10.1
-GitPython==2.1.11
+GitPython==3.0.8
 sphinx-tabs
@@ -12,8 +12,17 @@ Below is a list of commonly asked questions with answers sourced from the
 General
 *******

-Why did you make another distro?
-================================
+What is |CL|?
+=============
+
+|CL| is an open source, rolling release Linux distribution optimized for
+performance and security. See `the about page <https://clearlinux.org/about>`_
+for more information.
+
+|
+
+Why another Linux distribution?
+===============================

 The |CL| team felt that performance was left on the table with Linux software.
 |CL| takes a holistic approach to improve performance across the stack. We
@@ -21,15 +30,23 @@ also wanted to take more modern approaches with OS updates and tooling.

 |

-Can other distros copy |CL| improvements?
-=========================================
+Is it a derivative of another Linux distribution?
+=================================================
+
+No. |CL| is a new Linux distribution. It is not a fork and does not have a
+parent Linux distribution.
+
+|
+
+Can others copy improvements from |CL|?
+=======================================

 Yes, we absolutely love open source reuse and upstreaming improvements.

 |

-How often do you update?
-========================
+How often does it update?
+=========================

 The |CL| team puts out multiple releases a week, often releasing two or more
 times a day. This rolling release approach allows |CL| to remain agile to
@@ -43,15 +60,16 @@ Is telemetry required?
 The telemetry solution provided by |CL| is entirely optional and customizable.
 It is disabled by default. If you do choose to enable telemetry, the data
 helps the |CL| team proactively identify and resolve bugs. See the
-:ref:`telem-guide` guide for more information.
+:ref:`telemetry <telem-guide>` guide for more information.

 |

 What is the default firewall?
 =============================

-|CL| packages :command:`iptables` as a bundle, however, there are no default
-firewall rules. All network traffic is allowed by default.
+|CL| packages :command:`iptables` and :command:`firewalld` as optional
+bundles, however, there are no default firewall rules. All network traffic is
+allowed by default.

 |

@@ -60,21 +78,35 @@ Where are the files that I usually see under /etc like fstab?

 |CL| has a stateless design that maintains a separation between system files
 and user files. Default values are stored under :file:`/usr/share/defaults/`.
-Files under :file:`/etc/` are not created unless you create one.
+|CL| starts with a mostly empty :file:`/etc` directory to store user-defined
+configurations. See the :ref:`stateless <stateless>` page for more information.
+
+See `this blog post
+<https://clearlinux.org/news-blogs/where-etcfstab-clear-linux>`_ for an
+example explaining how this is accomplished with :file:`/etc/fstab/`
+specifically.

-A blog post explaining how this is accomplished with :file:`/etc/fstab/`
-specifically is available here:
-https://clearlinux.org/news-blogs/where-etcfstab-clear-linux

 |

-Software packages
-*****************
+Does it use the Intel Compiler (icc)?
+=====================================
+
+No. |CL| uses open source compilers: :command:`gcc` and :command:`clang`. |CL|
+does not compile any packages with :command:`icc`. 
+
+For a more detailed explanation, see `this discussion on the community forum
+<https://community.clearlinux.org/t/does-clear-linux-os-use-the-intel-compiler-icc-tl-nope/>`_.
+
+|
+
+Software
+********

 How is software installed and updated?
 ======================================

-|CL| provides software in the form of :ref:`bundles-guide` and
+|CL| provides software in the form of :ref:`bundles <bundles-guide>` and
 updates software with :ref:`swupd <swupd-guide>`.

 :ref:`Flatpak\* <flatpak-tutorial>` is an application virtualization solution
@@ -86,15 +118,29 @@ bundles whenever possible.

 |

-Does |CL| use RPMs like other distros?
-======================================
+Does it use RPMs or DEBs packages like other distros?
+=====================================================

-|CL| provides software in the form of :ref:`bundles-guide`. The RPM
-format is used as an intermediary step for packaging and determining software
-dependencies at OS build time.
+No. |CL| provides software to systems in the form of :ref:`bundles-guide`.
+Under the hood, |CL| developers use the RPM format as an intermediary step for
+packaging and determining software dependencies at OS build time.
+
+Individual RPMs and DEBs can sometimes be manually extracted and installed on
+a |CL| system with the right tools, but that is not the intended use case.
+
+|
+
+Why does it have a different approach to software management?
+=============================================================
+
+The |CL| team wants software *installation* and *updates* to be as efficient
+and error free as possible. |CL| packages software differently and uses a
+novel updater to solve some of the classic problems with how the software
+packages are on Linux. 
+
+For a more detailed explanation, see `this discussion on our community forum
+<https://community.clearlinux.org/t/why-does-clearlinux-use-swupd-and-not-apt-deb-rpm/>`_.

-Individual RPMs can sometimes be manually installed on a |CL| system with the
-right tools, but that is not the intended use case.

 |

@@ -127,8 +173,9 @@ Is Google\* Chrome\* available?
 The Google Chrome web browser is not distributed as a bundle in |CL| due to
 copyright and licensing complexities.

-A discussion on manually installing and maintaining Google Chrome can be found
-on GitHub: https://github.com/clearlinux/distribution/issues/422
+A `discussion on manually installing and maintaining Google Chrome
+<https://github.com/clearlinux/distribution/issues/422>`_ can be found on
+GitHub.

 |

@@ -142,13 +189,17 @@ the `software store`_. Installing Flatpak apps is also covered in our
 The |CL| team is working on a natively packaged version of Visual Studio Code
 for future release.

-Join a community forum discussion about manually installing and maintaining
-Visual Studio Code: https://community.clearlinux.org/t/need-native-support-for-vs-code-through-swupd/
+Join a community `forum discussion about manually installing and maintaining
+Visual Studio Code
+<https://community.clearlinux.org/t/need-native-support-for-vs-code-through-swupd/>`_.
+

 .. _VS Code: https://clearlinux.org/software?search_api_fulltext=vscode

 |

+.. _licensing_restrict:
+
 Is FFmpeg available?
 ====================

@@ -159,13 +210,12 @@ various media encoding/decoding, streaming, and playback.
 complexities (See https://www.ffmpeg.org/legal.html and
 http://blog.pkh.me/p/13-the-ffmpeg-libav-situation.html).

-Read more in the |CL| repository, including discussion of an alternative
-hardware-based solution:
-https://github.com/clearlinux/distribution/issues/429.

-While |CL| cannot distribute FFmpeg, a manual solution to build and install
-FFmpeg under :file:`/usr/local` has been shared on the community forums:
-https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install.
+While |CL| cannot distribute FFmpeg, solutions for manually building and
+installing FFmpeg have been shared by users `on GitHub
+<https://github.com/clearlinux/distribution/issues/429>`_ and `the community
+forums
+<https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install>`_.

 |

@@ -176,8 +226,8 @@ ZFS is not available with |CL| because of copyright and licensing
 complexities. BTRFS is an alternative filesystem that is available in |CL|
 natively.

-A user on GitHub notes that the ZFS kernel module can be compiled, built, and
-installed manually: https://github.com/clearlinux/distribution/issues/631
+A user on GitHub notes that the `ZFS kernel module can be compiled, built, and
+installed manually <https://github.com/clearlinux/distribution/issues/631>`_.

 |

@@ -2,9 +2,12 @@

 /* make the page width fill the window */
 .wy-nav-content {
-   max-width: none;
+   max-width: 1100px;
   background: linear-gradient(white 58px, #f2f4f5 58px 100%);
   padding-top: 10px;
+   padding-right: 20px;
+   padding-left: 20px;
+   padding-bottom: 20px;
 }

 .wy-nav-content-wrap .wy-nav-content {
@@ -489,10 +492,26 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
  margin: 10px;
  border: 10px;
  background: white;
+  position: relative;
 }

 .column.featurecard {
  background: #CCE9F5;
+  width: 300px;
+}
+
+.column.squarecard {
+  height: 320px;
+}
+
+.column.smallcard {
+  height: 150px;
+}
+
+.endlink {
+  position: absolute;
+  bottom: 10px;
+  right: 10px;
 }

 .column.verticalcard {
@@ -500,6 +519,10 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
  overflow: auto;
 }

+.multicolumns.three {
+  max-width: 1200px;
+}
+
 /* Clear floats after the columns */
 .multicolumns:after {
  content: "";
@@ -546,4 +569,4 @@ div.figure.dropshadow img {
  box-shadow: 10px 10px 10px LightGray;
 }

-/*end figure drop shadow*/
+/*end figure drop shadow*/
@@ -3,57 +3,93 @@
 About
 #####

-The |CL| delivers a secure, hardware optimized OS. Its easy updates ensure that
-software dependencies remain mutually compatible.
-
-|CL| does this via custom infrastructure components and process innovations.
+|CL-ATTR| does things differently. Our software architecture provides a 
+unique and innovative platform for Linux* developers focused on
+performance, security, and cutting-edge computation in the cloud. 

 .. contents::
   :local:
   :depth: 1


-For detailed information on these topics, refer to the :ref:`cl-guides` guides.
+What is |CL|?
+*************

+|CL| is an open source, rolling-release Linux* distribution, optimized for 
+performance and security from the cloud to the Edge.  With an emphasis on 
+customization and manageability, |CL| provides an industry blueprint on how 
+to incorporate Intel® architecture, from leveraging instruction sets to 
+optimizing kernel configurations and compiler flags, so tuning across the stack coalesces in a single, performance-driven development environment. 

-Release Cadence
+What |CL| isn't?
+****************
+
+|CL| is not intended to be a general-purpose Linux distribution, suitable 
+for novice end-users. While we ship common applications, our purpose isn’t 
+to make an OS for routine desktop tasks and provide immunity from all 
+security threats in all situations. Our unique focus means what we consider 
+*essential* use cases, *optional* use cases, or even *unwanted* use cases, 
+differs from other Linux distros.
+
+Target audience
 ***************

+Rather than making a standard Linux distribution, the |CL| team decided to
+build its own. |CL| mainly targets professionals in IT, DevOps, Cloud/
+Container deployments, and :abbr:`AI (Artifical Intelligence)`. 
+
+One advantage of developing a distro in house is that our experiments help us
+continually optimize performance and deliver security patches, several times
+per week. Yet our experiments are only valuable if our software architecture 
+gives you the freedom to innovate, too. To improve manageability, |CL| 
+employs a :ref:`stateless` design, separating user and system management.  
+
+Understanding what it takes to integrate features into our own Linux distro 
+helps us collaborate with other distro owners and submit enhancements to 
+upstream. We demonstrate the value of our distro by offering users the 
+same tools we use. For example, :ref:`mixer`, a tool unique to |CL|, allows 
+users to build custom derivatives and act as their own 
+:abbr:`(OSV) OS Vendor`. 
+
+For more details on |CL| features, refer to the :ref:`cl-guides` guides.
+
+What makes |CL| different?
+**************************
+
+Release Cadence
+===============
+
 |CL| updates are based on a rolling release that can occur daily, up to a few
-times per week. Each release has a unique version number that
-identifies every component in the OS from kernel, to driver, to tool, to GUI
-application. Most components are included in entities called *bundles*.
+times per week. Each release has a unique version number that identifies
+every component in the OS from kernel, to driver, to tool, to GUI
+application. Most components are included in entities called :ref:`bundles<bundles>`.

 Updates
-*******
+=======

-By default, |CL| automatically checks for updates, ensuring that the latest
+By default, |CL| automatically checks for updates, ensuring the latest
 performance and security fixes are installed as soon as they are available.
-:ref:`swupd-guide` is the custom tool designed to manage updates and bundles.
-
-|CL| is :ref:`stateless` to make sure that system components can be updated
-without impacting user settings.
-
+|CL| stays in lockstep with upstream for current security upgrades and is 
+designed to rapidly deliver security mitigations to customers.
+:ref:`swupd-guide` is designed to manage updates and bundles.

 Ease of Use
-***********
+===========

 |CL| makes it easier to manage a number of difficult problems.

 * :ref:`autoproxy` makes it possible for |CL| tools to operate in some proxy
  environments without needing to be configured.

-* Being :ref:`stateless` means that configuration settings are easier to manage
+* :ref:`stateless` means that configuration settings are easier to manage
  and remain untouched when system software is updated.

 * :ref:`swupd-guide` simplifies managing software and maintaining compatibility.

 Custom Derivatives
-******************
+==================

-The same tools used to build the |CL| are available *in* the OS. These tools can
-be used to create a custom distribution that continues to benefit from upstream
-rolling releases.
+The same tools used to build the |CL| are available *in* the OS. These tools can be used to create a custom distribution that continues to benefit from upstream rolling releases.

 .. figure:: /_figures/about/clear-lifecycle.png
   :scale: 75%
@@ -82,4 +118,191 @@ Administrate
 |CL| provides a :ref:`telem-guide` solution for collecting useful information
 about a deployment, as well as :ref:`debug` capabilities.

+Performance and security
+------------------------
+
+We apply the same strategy when it comes to performance. Our developers 
+strive to optimize performance for *essential* use cases while we ignore 
+*unwanted* or unsupported use cases.
+
+For example, while |CL| does not enable antivirus by default, we provide
+a bundle for it (`clamav`). We leave antivirus configuration to our users. 
+In addition, firewalls are less important if the OS doesn’t expose services 
+to the outside by default. In |CL|, we enforce this strategy by disabling 
+network services by default - e.g. mariadb listens on a UNIX socket, nginx 
+won’t listen at all, and other services similarly like that are restricted 
+from being accessed over the network. This strategy alone makes firewall 
+software much less urgent - there simply isn’t anything that a firewall 
+could easily block.
+
+If you want a general purpose Linux distro with little to no configuration, 
+|CL| may not be the distro enough for you. 
+
+
+Is |CL| completely Open Source?
+*******************************
+
+Wherever possible, |CL| aims to be completely open source.  Our 
+`source code`_ is available on GitHub. When considering projects for inclusion, we check that they are in active development and are well maintained. We have a very strict requirement for not accepting proprietary packages and non-open source components.  For example, many Linux distros may not be able to include certain media codecs due to  
+:ref:`licensing restrictions <licensing_restrict>`, but alternatives are available.
+
+What’s the thinking around Command line v. Desktop?
+***************************************************
+
+|CL| focuses on performance for server and cloud use-cases first because
+many design decisions associated with them are applicable to other use-cases, such as IoT and the desktop client. 
+
+While our initial focus was on the command line, we realized that many people valued the ease-of-use of a desktop environment.  We've been trying to accommodate these people as much as we can, but there are clear limits to what a desktop environment can do. This is especially true, given our desire to deliver a highly performant and secure Linux distro, one that provides unique tools for customization, and one that enables several cloud use cases. |CL| has a strong bias toward servers and what developers use, 
+rather than including "random stuff".
+
+Why create new components rather than modifying existing projects?
+******************************************************************
+
+One question that's often asked: “Why did you develop your own solution 
+instead of using <XYZ>?” (e.g. `swupd post`_).  We do evaluate existing 
+projects for inclusion in |CL|, yet there are cases where our unique 
+architecture and components would require too much customization to use 
+off-the-shelf projects.  In other situations, we may feel that using a new 
+language to develop the component would give us a performance advantage, 
+ease code development and maintenance, and grow the skills of our engineers 
+on new and upcoming programming languages.  And yes, sometimes there are 
+personal biases for and against some projects by the architects and 
+engineers.  We tend to move fast, and sometimes it’s easier to live with 
+suboptimal choices until we have the time or incentive to re-architect them 
+properly. 
+
+Which Components are used in Clear Linux?
+*****************************************
+
+.. list-table::
+   :widths: 33,33,33
+   :header-rows: 1
+
+   * - Component
+     - Enabled in OS/Bundle
+     - Optional
+
+   * - OS Installer
+     - `Clear Linux installer`_
+     - 
+
+   * - Bootloader
+     - `systemd-boot`_ (UEFI) / `syslinux`_ (Legacy)
+     - 
+
+   * - Boot Manager
+     - `Clear Linux Boot Manager`_
+     - 
+
+   * - Configuration initialization and management
+     - 
+     - `micro-config-drive`_ (minimal cloud-init), Ansible
+
+   * - Software component installer, manager, updater
+     - `swupd`_
+     - 
+
+   * - Software bundle generator - 
+     - `mixer`_ and `clr-distro-factory`_
+     - 
+
+   * - Package builder
+     - `autospec`_
+     - 
+
+   * - Software debugging
+     - 
+     - `clr-debug-info`_ 
+
+   * - Unified TLS Trust Store Management
+     - `clrtrust`_
+     - 
+
+   * - System and software telemetry
+     - 
+     - `Telemetrics`_ (disabled by default)
+
+   * - File system
+     - `EXT4`_ (default for rootfs)
+     - `VFAT`_, `EXT2 and EXT3`_, `F2FS`_
+
+   * - Disk encryption
+     - 
+     - `LUKS`_ 
+
+   * - System /Service manager  
+     - `systemd`_
+     - 
+
+   * - Display manager 
+     - `Gnome`_
+     - ``KDE``, ``i3``, ``XFCE`` ``LXQt`` (see`Clear Linux store`_)
+
+   * - Display services (Desktop installed)
+     - `X.Org`_
+     - `Wayland`_ compositor
+
+   * - Network services
+     - `NetworkManager`_ by default*, `systemd-networkd`_
+     - 
+
+   * - SSH Port scanning blocker
+     - `Tallow`_
+     - 
+
+   * - Firewall
+     - None by default
+     - iptables and `firewalld`_
+
+   * - Antivirus
+     - None by default
+     - `ClamAV®`_
+
+   * - Web browser
+     - `Lynx`_ or `links`_ for text environments, `Firefox`_ for GUI
+     - 
+
+   * - Additional Software
+     - `Supplied Bundles`_
+     - Flatpak, 3rd-party software bundles
+
+.. note::
+   
+   The |CL| OS images targeted for cloud deployments continue to use
+   ``systemd-networkd`` to manage network connections.  In earlier |CL|, 
+   ``systemd-networkd`` was used to manage Ethernet interfaces and NetworkManager was used for wireless interfaces.
+
 .. _how-to-clear: https://github.com/clearlinux/how-to-clear
+.. _Clear Linux store: https://clearlinux.org/software
+.. _source code: https://github.com/clearlinux
+.. _swupd post: https://community.clearlinux.org/t/why-does-clearlinux-use-swupd-and-not-apt-deb-rpm/
+.. _swupd: https://github.com/clearlinux/swupd-client
+.. _Clear Linux installer: https://github.com/clearlinux/clr-installer/
+.. _systemd-boot: https://www.freedesktop.org/software/systemd/man/systemd-boot.html
+.. _syslinux: https://wiki.syslinux.org/wiki/index.php?title=The_Syslinux_Project
+.. _Clear Linux Boot Manager: https://github.com/clearlinux/clr-boot-manager
+.. _mixer: https://github.com/clearlinux/mixer-tools
+.. _clr-distro-factory: https://github.com/clearlinux/clr-distro-factory
+.. _autospec: https://github.com/clearlinux/common
+.. _clr-debug-info: https://github.com/clearlinux/clr-debug-info
+.. _clrtrust: https://github.com/clearlinux/clrtrust
+.. _EXT4: https://ext4.wiki.kernel.org/index.php/Main_Page
+.. _VFAT: https://www.kernel.org/doc/html/latest/filesystems/vfat.html
+.. _EXT2 and EXT3: https://ext4.wiki.kernel.org/index.php/Main_Page
+.. _F2FS: https://www.kernel.org/doc/Documentation/filesystems/f2fs.txt
+.. _LUKS: https://gitlab.com/cryptsetup/cryptsetup/
+.. _systemd: https://www.freedesktop.org/wiki/Software/systemd/
+.. _Gnome: https://www.gnome.org/
+.. _X.Org: https://www.x.org/
+.. _Wayland: https://wayland.freedesktop.org/
+.. _NetworkManager: https://wiki.gnome.org/Projects/NetworkManager
+.. _systemd-networkd: https://www.freedesktop.org/software/systemd/man/systemd.network.html
+.. _Tallow: https://github.com/clearlinux/tallow
+.. _firewalld: https://docs.01.org/clearlinux/latest/guides/network/firewall.html#firewalld
+.. _ClamAV®: https://www.clamav.net/
+.. _Lynx: https://lynx.invisible-island.net/
+.. _links: http://links.twibright.com/
+.. _Firefox: https://www.mozilla.org/en-US/firefox/
+.. _Supplied Bundles: https://clearlinux.org/software
+.. _micro-config-drive: https://github.com/clearlinux/micro-config-drive
+.. _Telemetrics: https://github.com/clearlinux/telemetrics-backend
@@ -380,7 +380,7 @@ root partition

   * :guilabel:`New size:`                <varies>
   * :guilabel:`Partition name:`          CLR_ROOT
-   * :guilabel:`File system:`             ext[234] or XFS
+   * :guilabel:`File system:`             ext[234], XFS, or f2fs
   * :guilabel:`Label:`                   root

   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-14.png
@@ -638,17 +638,17 @@ Create partitions per requirements in Table 1.
     - Mount Point
     - Default size

-   * - **VFAT (FAT32)**
+   * - ``VFAT (FAT32)``
     - boot
     - /boot
     - 150MB

-   * - **linux-swap**
+   * - ``linux-swap``
     - swap
     -
     - 256MB

-   * - **ext[234] or XFS**
+   * - ``ext[234], XFS, or f2fs``
     - root
     - /
     - *Size depends upon use case/desired bundles.*
@@ -41,7 +41,6 @@ Install |CL| on your target system
 Ensure that your system is configured to boot UEFI. The installation method
 described below requires a wired or wireless Internet connection with DHCP.

-
 Follow these steps to install |CL| on the target system:

 #. Insert the USB drive into an available USB slot.
@@ -89,7 +88,7 @@ Launch the |CL| Installer

      Figure 2: root login

-#. .. note::
+  .. note::

      If a wireless connection is needed, connect to the network using
      :command:`nmtui` before lauching the installer. See the documentation on
@@ -127,8 +126,7 @@ The |CL| Installer Main Menu appears as shown in Figure 4.
   Figure 4: Clear Linux OS Installer

 The |CL| Installer Main Menu has two tabs: :guilabel:`[R] Required options`
-and :guilabel:`[A] Advanced options`. Navigate between tabs using the arrow
-these shortcut keys:
+and :guilabel:`[A] Advanced options`. Navigate between tabs using these shortcut keys:

 * :kbd:`Shift+A` for :guilabel:`[A] Advanced options`
 * :kbd:`Shift+R` for :guilabel:`[R] Required options`
@@ -160,8 +158,6 @@ Choose Timezone
 #. In :guilabel:`Select System Timezone`, use :kbd:`Up/Down` arrows
   navigate to the desired timezone.

-.. todo: User need only select Enter; can only select Confirm with mouse.
-
 #. Press :kbd:`Enter` to confirm.

   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-05.png
@@ -356,7 +352,7 @@ root partition
 #. Enter the hex code `8300` and press :kbd:`Enter`.

 #. In :guilabel:`Enter new partition name...`, type: CLR_ROOT.
-   The `/root` partition must be `ext[234]` or `XFS`.
+   The `/root` partition must be `ext[234]`, `XFS`,  or `f2fs`.
   If no filesystem exists, the installer will default to `VFAT(FAT32)`
   for `/boot`, and `ext4` for all others.

@@ -749,6 +745,31 @@ Bundle selection is disabled if no network connection exists.

 Optional: Skip to `Finish installation`_.

+Assign Hostname
+===============
+
+#. In Advanced Options, select :guilabel:`Assign Hostname`.
+
+#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
+
+   .. note::
+
+      Hostname does not allow empty spaces. Hostname must start with an
+      alphanumeric character but may also contain hyphens. Maximum length of
+      63 characters.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-28.png
+      :scale: 100%
+      :alt: Assign Hostname
+
+      Figure 28: Assign Hostname
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :kbd:`Confirm`.
+
+Optional: Skip to `Finish installation`_.
+
 Kernel Command Line
 ===================

@@ -762,11 +783,11 @@ new kernel.

 #. Select :kbd:`Enter`.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-28.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-29.png
      :scale: 100%
      :alt: Kernel Command Line

-      Figure 28: Kernel Command Line
+      Figure 29: Kernel Command Line

 #. Choose from the following options.

@@ -783,15 +804,15 @@ Kernel Selection
 ================

 #. Select a kernel option. By default, the latest kernel release is
-   selected. Native kernel is shown in Figure 29.
+   selected. Native kernel is shown in Figure 30.

 #. To select a different kernel, navigate to it using :guilabel:`Tab`.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-29.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-30.png
      :scale: 100%
      :alt: Kernel selection

-      Figure 29 Kernel selection
+      Figure 30 Kernel selection

 #. Select :kbd:`Spacebar` to select the desired option.

@@ -810,36 +831,11 @@ If you have your own custom mirror of |CL|, you can add its URL.

 #. Select :kbd:`Confirm`.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-30.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-31.png
      :scale: 100%
      :alt: Swupd Mirror

-      Figure 30: Swupd Mirror
-
-Optional: Skip to `Finish installation`_.
-
-Assign Hostname
-===============
-
-#. In Advanced Options, select :guilabel:`Assign Hostname`.
-
-#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
-
-   .. note::
-
-      Hostname does not allow empty spaces. Hostname must start with an
-      alphanumeric character but may also contain hyphens. Maximum length of
-      63 characters.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-31.png
-      :scale: 100%
-      :alt: Assign Hostname
-
-      Figure 31: Assign Hostname
-
-#. Navigate to :kbd:`Confirm` until highlighted.
-
-#. Select :kbd:`Confirm`.
+      Figure 31: Swupd Mirror

 Optional: Skip to `Finish installation`_.

@@ -872,9 +868,9 @@ Save Configuration Settings

   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-33.png
      :scale: 100%
-      :alt: Automatic OS Updates
+      :alt: Save configuration to YAML file

-      Figure 33: Automatic OS Updates
+      Figure 33: Save configuration to YAML file

 #. Use the :file:`clr-installer.yaml` file to install |CL|, with the same
   configuration, on multiple targets.
@@ -924,7 +920,7 @@ Create partitions per requirements in Table 1.
     -
     - 256MB

-   * - ``ext[234] or XFS``
+   * - ``ext[234], `XFS`, or f2fs``
     - root
     - /
     - *Size depends upon use case/desired bundles.*
@@ -954,7 +950,7 @@ Erase LVM Partitions Before Installing |CL|
 ===========================================

 If you’re planning to install |CL| on a drive that has LVM partitions, 
-you must erase them first before using clr-installer.  
+you must erase them first before using the clr-installer.  

 Here is an example of a drive (/dev/sda) with LVMs:

@@ -1,18 +1,17 @@
 .. _bootable-usb:

-Create a bootable USB drive using BalenaEtcher
-##############################################
+Create a bootable USB drive using Etcher\*
+##########################################
+
+Use Etcher* software from Balena\* to flash the |CL| image to a USB drive. 
+An `Advanced: Linux CLI`_ option is also available.

 Prerequisites
 *************

 * Download the |CL| Desktop or Server image from the `Downloads`_ page
 * Recommended minimum **4GB** USB drive or larger
-* Download and install `BalenaEtcher`_
-
-.. _bootable-usb-linux:
-
-* Make sure you completed all `Prerequisites`_.
+* Download and install the `Etcher`_ version per your operating system.

 Burn the |CL| image onto a USB drive
 ====================================
@@ -22,90 +21,151 @@ Burn the |CL| image onto a USB drive
   Burning an image formats the USB drive and destroys all pre-existing
   content.  Back up your data before proceeding.

-#. Launch balenaEtcher.
+#. Launch Etcher.
+
+   .. rst-class:: dropshadow

   .. figure:: /_figures/bootable-usb/balenaEtcher_Start.PNG
      :scale: 100%
-      :alt: BalenaEtcher Start
+      :alt: Start screen
         
-      Figure X: BalenaEtcher Start
+      Figure 1: Start screen
 
 #. Press :guilabel:`Select Image`.

 #. Change directory to where the image resides.

-#. Open the Image.
+#. Select the image and click :guilabel:`Open`.

-   .. figure:: /_figures/bootable-usb/balenaEtcher_ImgaeSlect.PNG
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_ImageSelect.PNG
      :scale: 100%
-      :alt: 
+      :alt: In Open, select the image
         
-      Figure X: 
+      Figure 2: In Open, select the image

 #. Plug in the USB drive.

-#. Identify the USB drive using the :guilabel:`Change` under the middel icon.
+#. Identify the USB drive or click :guilabel:`Change` to select a 
+   different USB.
    
   .. note::
+
      This shows all USB drives attached to the system.

+   .. rst-class:: dropshadow
+
   .. figure:: /_figures/bootable-usb/balenaEtcher_DriveSlect.PNG
      :scale: 100%
-      :alt: 
+      :alt: USB drives attached
         
-      Figure X: 
+      Figure 3: USB drives attached

-#. Select the proper drive and press :guilabel:`Continue`.
+#. Select the proper device and press :guilabel:`Continue`.
+
+   .. rst-class:: dropshadow

   .. figure:: /_figures/bootable-usb/balenaEtcher_ReadyToFlash.PNG
      :scale: 100%
-      :alt: 
+      :alt: USB Flash Device selected
      
-      Figure X: 
+      Figure 4: USB Flash Device selected

-#. When ready Press the  :guilabel:`Flash!` Button.
+#. When ready press the :guilabel:`Flash!` Button. 
+   The dialog shows :guilabel:`Flashing` while in progress.

-#. Flashing starting.
+   .. rst-class:: dropshadow

   .. figure:: /_figures/bootable-usb/balenaEtcher_StartingToFlash.PNG
      :scale: 100%
-      :alt: 
+      :alt: Starting to flash

-      Figure X: 
+      Figure 5: Starting to flash

-#. Flashing in progress.
+   .. rst-class:: dropshadow

   .. figure:: /_figures/bootable-usb/balenaEtcher_Flashing.PNG
      :scale: 100%
-      :alt: 
+      :alt:  Flashing, percentage complete
      
-      Figure X: 
+      Figure 6: Flashing, percentage complete

-#. Flashing complete.
+#. :guilabel:`Flash complete!` shows when the process is finished.
+
+   .. rst-class:: dropshadow

   .. figure:: /_figures/bootable-usb/balenaEtcher_Done.PNG
      :scale: 100%
-      :alt: 
+      :alt: Flash Complete!
      
-      Figure X: 
+      Figure 7: Flash Complete!

   .. note::
-      The process can take more than a few minutes. When the process completes, close BalenaEtcher.
-      

-Ejecting the |CL| image USB drive
-=================================
+      The process may take more than a few minutes. When the process completes, close BalenaEtcher.
+      
+Advanced: Linux CLI
+===================
+
+#. Open a Terminal window.
+
+#. Change directory to where the image resides. 
+
+#. Plug in the USB drive.  
+
+#. Identify all drives attached to the system. In the example output below, there are 3 drives (`/dev/sda`, `/dev/sdb`, and `/dev/sdc`) attached, where `/dev/sda` is the primary drive and the remaining are USB drives.   
+
+   .. code-block:: bash 
+
+      lsblk -po NAME,SIZE,VENDOR,MODEL,TRAN,TYPE,PARTLABEL,MOUNTPOINT 
+   
+   Example output:   
+
+   .. code-block:: console 
+
+      NAME          SIZE VENDOR   MODEL                    TRAN   TYPE PARTLABEL                    MOUNTPOINT 
+      /dev/sda    119.2G ATA      SAMSUNG_MZ7PC128HAFU-000 sata   disk                                
+      ├─/dev/sda1   450M                                          part Basic data partition           
+      ├─/dev/sda2   100M                                          part EFI system partition           
+      ├─/dev/sda3    16M                                          part Microsoft reserved partition   
+      ├─/dev/sda4  97.2G                                          part Basic data partition           
+      ├─/dev/sda5   142M                                          part EFI                            
+      ├─/dev/sda6   245M                                          part linux-swap                   [SWAP]  
+      └─/dev/sda7  21.1G                                          part /                            / 
+      /dev/sdb      7.5G General  UDisk                    usb    disk                                
+      └─/dev/sdb1   7.5G                                          part Microsoft Basic Data         /run/media/clear/CENA_X64FRE 
+      /dev/sdc       15G          Patriot_Memory           usb    disk                                
+      └─/dev/sdc1    15G                                          part                              /run/media/clear/U  
+
+   .. note::   
+
+      Some Linux distros may automatically mount a USB drive when it is plugged in. 
+
+#. Unmount the USB drive you want to use before burning an image onto it.
+   Use the :command:`umount` command followed by the device identifier/partition. For example, to unmount all ``/dev/sdc`` partitions:   
+
+   .. code-block:: bash 
+
+      sudo umount /dev/sdc*   
+
+#. Burn the image onto the USB drive. This example burns an image onto
+   ``/dev/sdc``. The device name of the USB may vary.   
+
+   .. code-block:: bash
+
+      sudo dd if=./clear-[version number]-live-[desktop | server].iso of=/dev/sdc oflag=sync bs=4M status=progress
+
+Eject the |CL| image USB drive
+==============================

 .. caution::

-   Not fully unmounting the USB drive before removing the drive could cause
-   file system checksum errors in it. If this happens, burn the image again,
-   ensuring all the USB drive partitions are unmounted first befor removing drive.
+   If you do not properly unmount the USB drive before removing it, it may cause file system checksum errors in it. If this happens, burn the image again, ensuring all the USB drive partitions are unmounted first before removing drive.

+#. Unmount the USB per your OS instructions. 

-#. Select the Windows taskbar menu for USB and select
-   :guilabel:`Eject <drive name>`.
+#. Then eject the USB. 
   
- 
 .. _Downloads: https://clearlinux.org/downloads
-.. _BalenaEtcher: https://www.balena.io/etcher/
+.. _Etcher: https://www.balena.io/etcher/
@@ -147,6 +147,8 @@ Upload image

   See Figure 1.

+   .. rst-class:: dropshadow
+
   .. figure:: ../../_figures/digitalocean/01-digitalocean.png
      :scale: 100 %
      :alt: DigitalOcean - Upload custom images
@@ -0,0 +1,511 @@
+.. _import-clr-aws:
+
+Import Clear Linux Image and Launch Instance on AWS
+###################################################
+
+Clear Linux is available on the AWS marketplace.  However, it may not 
+be the latest version because we only update the marketplace on a 
+periodic basis, as often as weekly or but maybe monthly as well.  
+If you want to use the latest release from us or upload your own 
+custom image, follow this guide.  
+
+.. contents::
+   :local:
+   :depth: 1
+
+Prerequisites
+*************
+
+* You are familiar with AWS and how to use it
+
+Download or create a |CL| image for AWS
+***************************************
+
+Obtain an AWS |CL| image using one of these methods.  
+
+Download pre-built image
+========================
+#. Go to the `Downloads`_ page and download the 
+   *Amazon\* Web Services (AWS)* image.
+
+#. Uncompress it.  
+
+Create a custom image using clr-installer
+=========================================
+#. On a |CL| system, open a terminal.
+
+#. Install the `clr-installer` bundle.
+
+   .. code-block:: bash
+
+      sudo swupd bundle-add clr-installer
+
+#. Download a sample `aws.yaml`_ configuration file. 
+
+#. Make changes to the configuration file as needed.
+   See `Installer YAML Syntax`_ for more information on clr-installer 
+   configuration YAML syntax.
+
+#. Download the `AWS image post-install script`_ and make it executable.
+
+#. Produce an image with clr-installer.
+
+   .. code-block:: bash
+      
+      clr-installer --template $PWD/aws.yaml
+
+Create an S3 bucket
+*******************
+
+#. Log into AWS.
+
+#. Go to :guilabel:`Services`, :guilabel:`Storage`, and select :guilabel:`S3`.
+   See Figure 1. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-01.png
+      :scale: 100%
+      :alt: AWS Services - S3 Management Console
+
+      Figure 1: AWS Services - S3 Management Console
+
+#. Click :guilabel:`+ Create bucket`.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-02.png
+      :scale: 100%
+      :alt: AWS S3 - Create bucket
+
+      Figure 2: AWS S3 - Create bucket
+
+#. Set a bucket name and select a region.  
+   See Figure 3.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-03.png
+      :scale: 100%
+      :alt: AWS S3 - Create bucket - Set bucket name and region
+
+      Figure 3: AWS S3 - Create bucket - Set bucket name and region
+
+#. Leave the :guilabel:`Configure options" and :guilabel:`Set permissions`
+   settings as is or configure as desired.  See Figure 4 and 5.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-04.png
+      :scale: 100%
+      :alt: AWS S3 - Create bucket - Configure options
+
+      Figure 4: AWS S3 - Create bucket - Configure options
+
+   .. figure:: ../../_figures/aws/import-clr-aws-05.png
+      :scale: 100%
+      :alt: AWS S3 - Create bucket - Set permissions
+
+      Figure 5: AWS S3 - Create bucket - Set permissions
+
+#. At the :guilabel:`Review` screen, click :guilabel:`Create bucket`.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-06.png
+      :scale: 100%
+      :alt: AWS S3 - Create bucket - Review
+
+      Figure 6: AWS S3 - Create bucket - Review
+
+   The created bucket should appear.  See Figure 7.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-07.png
+      :scale: 100%
+      :alt: AWS S3 - Created bucket
+
+      Figure 7: AWS S3 - Created bucket
+
+Upload the |CL| image into the bucket
+*************************************
+
+#. Click on the bucket.
+   See Figure 8.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-08.png
+      :scale: 100%
+      :alt: AWS S3 - Select bucket
+
+      Figure 8: AWS S3 - Select bucket
+
+#. Click :guilabel:`Upload`.
+   See Figure 9.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-09.png
+      :scale: 100%
+      :alt: AWS S3 - Upload
+
+      Figure 9: AWS S3 - Upload
+
+#. Click :guilabel:`Add files` and select the |CL| image file to upload.
+   See Figure 10.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-10.png
+      :scale: 100%
+      :alt: AWS S3 - Add files
+
+      Figure 10: AWS S3 - Add files
+
+#. Click :guilabel:`Next`.  Leave remaining settings as is or set as desired.
+   See Figure 11, Figure 12, and Figure 13.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-11.png
+      :scale: 100%
+      :alt: AWS S3 - Add files
+
+      Figure 11: AWS S3 - Add files
+
+   .. figure:: ../../_figures/aws/import-clr-aws-12.png
+      :scale: 100%
+      :alt: AWS S3 - Set permissions
+
+      Figure 12: AWS S3 - Set permissions
+
+   .. figure:: ../../_figures/aws/import-clr-aws-13.png
+      :scale: 100%
+      :alt: AWS S3 - Set properties
+
+      Figure 13: AWS S3 - Set properties
+
+#. Click :guilabel:`Upload` to upload the image.
+   See Figure 14.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-14.png
+      :scale: 100%
+      :alt: AWS S3 - Upload
+
+      Figure 14: AWS S3 - Upload
+
+Add a user to IAM with AWS_CLI privilege
+****************************************
+
+#. Go to :guilabel:`Services`, :guilabel:`Security, Identity, & Compliance`,
+   and select :guilabel:`IAM`.
+   See Figure 15. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-08.png
+      :scale: 100%
+      :alt: AWS Services - IAM
+
+      Figure 15: AWS Services - IAM
+
+#. On the left navigation bar under :guilabel:`Access management`, 
+   select :guilabel:`Users`.
+   See Figure 16.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-16.png
+      :scale: 100%
+      :alt: AWS AIM - Access management
+
+      Figure 16: AWS AIM - Access management
+
+#. Click :guilabel:`Add user`.
+   See Figure 17.
+   
+   .. figure:: ../../_figures/aws/import-clr-aws-17.png
+      :scale: 100%
+      :alt: AWS AIM - Add user
+
+      Figure 17: AWS AIM - Add user
+
+#. Under the :guilabel:`Set user details` section, enter a user name.
+   See Figure 18.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-18.png
+      :scale: 100%
+      :alt: AWS AIM - Enter user name and select access type
+
+      Figure 18: AWS AIM - Enter user name and select access type
+
+#. Under the :guilabel:`Select AWS access type` section, 
+   checkmark :guilabel:`Programmatic access`.
+   See Figure 18.
+
+#. Click :guilabel:`Next: Permissions`.
+
+#. Under :guilabel:`Set permissions`, select :guilabel:`Add user to group`.
+   See Figure 19.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-19.png
+      :scale: 100%
+      :alt: AWS AIM - Set user permissions
+
+      Figure 19: AWS AIM - Set user permissions
+
+#. Under :guilabel:`Add user to group`, enter `AWS_CLI` into search window.
+   Checkmark :guilabel:`AWS_CLI`.
+   See Figure 19.
+
+#. Click :guilabel:`Next: Tags`.
+
+#. Click :guilabel:`Next: Review`.
+
+#. Click :guilabel:`Create user`.
+   See Figure 20.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-20.png
+      :scale: 100%
+      :alt: AWS AIM - Create user
+
+      Figure 20: AWS AIM - Create user
+
+#. After the user is successfully added, save the :guilabel:`Access key ID`
+   and the :guilabel:`Secret access key`.  These will be used when setting up
+   the AWS CLI tool at a later step.
+   See Figure 21.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-21.png
+      :scale: 100%
+      :alt: AWS AIM - Access key ID and secret access key
+
+      Figure 21: AWS AIM - Access key ID and secret access key
+
+#. Click :guilabel:`Close`.
+
+Install and configure the AWS CLI tool on your system
+*****************************************************
+
+#. To install the tool on |CL|, simply run:
+
+   .. code-block:: bash
+
+      sudo swupd bundle-add cloud-api
+
+   .. note:
+
+      If you are using a different OS, follow the 
+      `Installing the AWS CLI version 2`_ guide.
+
+#. Configure it with your security credentials, default region,
+   and default output format. See `Configuring the AWS CLI`_ for more information.
+
+   .. code-block:: bash
+
+      aws configure
+
+   Below is an example (using the security credentials that was created in 
+   the previous section):
+
+   .. code-block:: console
+
+      AWS Access Key ID [None]: AKIA5LEGQPQ3EUB3JMS7
+      AWS Secret Access Key [None]: EcvbWpWr+Gp7NhBoVEacwR3EifzN7xTTg8B1PHvO
+      Default region name [None]: us-west-2
+      Default output format [None]: json 
+
+#. Verify your credentials are good.
+
+   .. code-block:: bash
+      
+      aws iam list-access-keys
+
+   If you get something like the example below, then make sure you set your 
+   system date and time properly.
+
+   .. code-block:: console
+
+      An error occurred (SignatureDoesNotMatch) when calling the ListAccessKeys operation: Signature expired: 20200305T153154Z is now earlier than 20200305T231847Z (20200305T233347Z - 15 min.)
+
+Import a snapshot of the |CL| image
+***********************************
+
+#. Create a :file:`container.json` with the description of the image to import.
+   Specify the name of the S3 bucket that was created earlier for the 
+   `S3Bucket` field and the name of |CL| image that was uploaded to the S3 bucket
+   for the `S3Key`.
+
+   Here's an example:
+
+   .. code-block:: console
+
+      {
+        "Description": "My Clear Linux AWS 32400 Image",
+        "Format": "raw",
+        "UserBucket": {
+          "S3Bucket": "my-clearlinux-bucket",
+          "S3Key": "clear-32400-aws.img"
+        }
+      }
+
+#. Import a snapshot of the image.
+
+   .. code-block:: bash
+
+      aws ec2 import-snapshot \
+      --description "My Clear Linux AWS 32400 Snapshot" \
+      --disk-container file://container.json
+
+   You should get an output similar this example:
+
+   .. code-block:: console
+
+      {
+        "Description": "My Clear Linux AWS 32400 Snapshot",
+        "ImportTaskId": "import-snap-00fa9ccd98e9b8378",
+        "SnapshotTaskDetail": {
+            "Description": "My Clear Linux AWS 32400 Snapshot",
+            "DiskImageSize": 0.0,
+            "Format": "RAW",
+            "Progress": "3",
+            "Status": "active",
+            "StatusMessage": "pending",
+            "UserBucket": {
+                "S3Bucket": "my-clearlinux-bucket",
+                "S3Key": "clear-32400-aws.img"
+            }
+        }
+    }
+
+#. Using the `ImportTaskId` from the previous step, check the status 
+   of the import.  For example:
+
+   .. code-block:: bash
+
+      snapshot_id=$(aws ec2 describe-import-snapshot-tasks \
+      --import-task-ids "import-snap-00fa9ccd98e9b8378" \
+      | grep SnapshotId | awk -F '"' '{print $4}')
+
+   Wait for the `Status` field to show `completed` before proceeding.
+
+   The resulting `snapshot_id` will be used to create an AMI in 
+   the next section.
+
+Create an AMI from the snapshot
+*******************************
+
+There are 2 methods to create an AMI from the snapshot.
+
+* *AWS CLI Method*:
+    
+  .. code-block:: bash
+    
+     aws ec2 register-image \
+     --name "My-Clear-Linux-32400-AMI" \
+     --description "My Clear Linux 32400 AMI" \
+     --architecture x86_64 \
+     --virtualization-type hvm \
+     --ena-support \
+     --root-device-name "/dev/sda1" \
+     --block-device-mappings "[ 
+       { 
+         \”Deviceame\": \"/dev/sda1\", 
+         \"Ebs\": {
+           \"SnapshotId\": \"$snapshot_id\" 
+         } 
+       } 
+     ]"
+
+* *GUI Method*: 
+
+  #. Go to :guilabel:`Services`, :guilabel:`Compute`, and select 
+     :guilabel:`EC2`.
+     See Figure 22. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-22.png
+      :scale: 100%
+      :alt: AWS Services - EC2
+
+      Figure 22: AWS Services - EC2
+    
+  #. Click :guilabel:`Snapshots`.
+     See Figure 23. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-23.png
+      :scale: 100%
+      :alt: AWS Services - Snapshots
+
+      Figure 23: AWS Services - Snapshots
+
+  #. Locate the snaphot using the `Snapshot ID`.
+     See Figure 24.
+
+   .. figure:: ../../_figures/aws/import-clr-aws-24.png
+      :scale: 100%
+      :alt: AWS Services - Snapshots
+
+      Figure 24: AWS Services - Snapshots
+    
+  #. Right-click it and select :guilabel:`Create Image`.
+
+  #. Configure as follows:
+ 
+     * Enter the name in the :guilabel:`Name` field
+     * Enter the description in the :guilabel:`Description` field
+     * Set the :guilabel:`Architecture` as `x86_64`
+     * Set the :guilabel:`Virtualization type` as `Hardware-assisted virtualization`
+     * Set the :guilabel:`Root device name` as `/dev/sda1`
+
+     See Figure 25.
+
+     .. figure:: ../../_figures/aws/import-clr-aws-25.png
+        :scale: 100%
+        :alt: AWS Services - Snapshots
+
+        Figure 25: AWS Services - Snapshots
+    
+  #. Click :guilabel:`Create`.
+
+Launch an instance
+******************
+
+#. Go to :guilabel:`Services`, :guilabel:`Compute`, and select 
+   :guilabel:`EC2`.
+   See Figure 26. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-26.png
+      :scale: 100%
+      :alt: AWS Services - EC2
+
+      Figure 26: AWS Services - EC2
+    
+#. Click the :guilabel:`Launch Instance` dropdown and select 
+   :guilabel:`Launch Instance`.
+   See Figure 27. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-27.png
+      :scale: 100%
+      :alt: AWS Services - Launch instance
+
+      Figure 27: AWS Services - Launch instance
+
+#. On the left navigation bar, select :guilabel:`My AMIs`.
+   See Figure 28. 
+
+   .. figure:: ../../_figures/aws/import-clr-aws-28.png
+      :scale: 100%
+      :alt: AWS Services - Select AMI
+
+      Figure 28: AWS Services - Select AMI
+
+#. Find your AMI and click :guilabel:`Select`.
+
+#. From here onward, configure the details of your instance as desired 
+   and launch it.
+   
+Connect to your |CL| instance
+*****************************
+
+#. Follow these steps to `connect to your instance`_.
+
+Related topics
+**************
+
+* :ref:`azure`
+* :ref:`gce`
+* :ref:`clr-digitalocean`
+
+.. _Downloads: 
+   https://clearlinux.org/downloads
+.. _aws.yaml: 
+   https://cdn.download.clearlinux.org/current/config/image/aws.yaml
+.. _AWS image post-install script:
+   https://cdn.download.clearlinux.org/current/config/image/aws-disable-root.sh
+.. _Installing the AWS CLI version 2: 
+   https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html
+.. _Configuring the AWS CLI: 
+   https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
+.. _connect to your instance: 
+   https://docs.01.org/clearlinux/latest/get-started/cloud-install/aws-web.html#connect-to-your-clear-linux-os-basic-instance
+.. _Installer YAML Syntax:
+   https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md
+
@@ -1,235 +1,262 @@
 .. _qingcloud:

-|CL-ATTR| on QingCloud\* (如何在青云 QingCloud 上创建 |CL| 虚拟主机)
-#########################################################################
+|CL-ATTR| on QingCloud\*
+###########################

-本教程介绍如何通过青云 QingCloud\* 控制台创建和启动 |CL| 实例以及完成以下任务：
+This tutorial describes how to create and launch a Clear Linux OS instance
+from the QingCloud console.

-#. 在 QingCloud 系统镜像中找到并选择 |CL| 操作系统。
-#. 创建新的公钥和私钥对，以便可以安全地连接到 |CL| 虚拟主机。
-#. 启动新的 |CL| 虚拟主机并连接到该主机。
-#. 删除 |CL| 虚拟主机。
-
-.. contents::
+.. contents:: 
   :local:
   :depth: 1

-必备条件
-************

-本教程假定您已经完成了如下默认配置：
+Prerequisites
+*************

-* 您的环境可以运行 SSH 以访问远程 |CL| 虚拟主机。
-* 您知悉浏览器下载文件的绝对路径。
-* 您已设置了 QingCloud 的用户帐户，并确保该账户为启用状态，并且已登录到 QingCloud 控制台。 要了解有关青云和设置账户的更多信息，请访问青云官网，网址为 https://www.qingcloud.com/。
+This tutorial assumes that you have completed the following configuration steps:

-在 QingCloud 控制台中选择并启动 |CL| 虚拟主机
-**********************************************
+* Your environment can run SSH to access remote Clear Linux OS virtual hosts.
+* You know the absolute path where the browser downloaded the file.
+* You have set up a user account for QingCloud and that the account is
+  enabled and logged in to the QingCloud console. To learn more about
+  QingCloud and setting up an account, please visit QingCloud's official
+  `website <https://www.qingcloud.com>`_.

-#. 在浏览器中在 QingCloud 控制台主菜单中，依次选择 **“计算”** 、 **“主机”**，之后点击图1中所示的 **“创建”** 选项。
+
+Select and start |CL| virtual host with QingCloud console
+*********************************************************
+
+#. Select :guilabel:`计算>主机` (Compute>Host) in the main menu of the
+   QingCloud console and click the :guilabel:`创建` (Create) option.

   .. figure:: /_figures/qingcloud/QingCloud-1.png
      :scale: 50 %
-      :alt: QingCloud 控制台
+      :alt: QingCloud console

-      图1: QingCloud 控制台
-    
-   选择此选项后，页面将跳转到“创建主机”页面。
-
-#. 在创建主机页面，先点击图2中所示的 **“系统”** 选项，再点击最右侧 **|CL|** 图标，并点击 **“下一步”** 按钮。 
+#. On the host creation page, first click the :guilabel:`系统` (System) option,
+   click the |CL| icon on the far right.  Click the :guilabel:`下一步` (Next)
+   button to continue.

   .. figure:: /_figures/qingcloud/QingCloud-2.png
      :scale: 50 %
-      :alt: 选择 |CL| 创建虚拟主机
+      :alt: Select Clear Linux OS to create virtual host

-      图2: 选择 |CL| 创建虚拟主机
+      Select |CL| to create a virtual host

-   之后，您将来到配置选择界面。 
-
-#. 在配置选择界面，您可以看到不同硬件配置类型的虚拟主机，比如调整 CPU 核心数量、内存大小以及硬盘和副本备份策略。这里我们将选择默认配置来进行接下来的演示。
+#. In the configuration selection interface, you can configure the
+   number of CPU cores, memory size, and the storage backup method.
+   For demonstration purposes, we will choose the default configuration.
+   Click the :guilabel:`下一步` (Next) button to go to the network settings
+   interface.

   .. figure:: /_figures/qingcloud/QingCloud-3.png
      :scale: 50 %
-      :alt: 配置选择
+      :alt: Configuration selection

-      图3: 配置选择
+      Configuration selection

-   在点击 “下一步” 按钮之后，您将来到网络设置界面。
-
-#. 在网络设置界面，您可以创建私有的 VPC 网络，也可以快速测试 |CL| 选择基础网络。 这里我们选择 **“基础网络”**。
+#. Select :guilabel:`基础网络` (Basic Network) in the network settings
+   interface.

   .. figure:: /_figures/qingcloud/QingCloud-4.png
      :scale: 50 %
-      :alt: 网络设置
+      :alt: Network settings

-      图4: 网络设置
+      Network Settings

-#. 在基本信息设置界面，您需要输入虚拟主机名称，并设置 SSH 密钥登录方式。
+#. In the basic information setting interface, you need to enter the virtual
+   host name and set the SSH key login method.

-   #. 如果之前没有创建过 SSH 密钥，请点击图5中 **“创建一个”** 按钮以创建 SSH 密钥。
+Create an SSH key (Optional)
+============================

-      .. figure:: /_figures/qingcloud/QingCloud-6.png
-         :scale: 50 %
-         :alt: 创建SSH密钥
+#. If you haven't created an SSH key before, click the :guilabel:`创建一个`
+   (Create one) button to create an SSH key.

-         图5: 创建SSH密钥
+   .. figure:: /_figures/qingcloud/QingCloud-6.png
+      :scale: 50 %
+      :alt: Create SSH key

-      在点击 “创建一个” 按钮之后，页面将跳转到 SSH 密钥创建界面。
+      Create SSH Key

-   #. 在 SSH 密钥创建界面中，您可以依照图6填写密钥的名称以便记忆，并且选择您需要的加密方法，确认无误后即可点击 **“提交”** 按钮。
+#. In the SSH key creation interface, you can fill in the key name, and select
+   encryption method you prefer. After confirming that they are correct, click
+   the :guilabel:`提交` (Submit) button.

-      .. figure:: /_figures/qingcloud/QingCloud-6.png
-         :scale: 50 %
-         :alt: 新建SSH密钥
+   .. figure:: /_figures/qingcloud/QingCloud-6.png
+      :scale: 50 %
+      :alt: New SSH key

-         图6: 新建SSH密钥
+      New SSH Key

-      提交之后，将跳出密钥下载按钮。
+#. After the download button appears, please download the key within 10
+   minutes, and save the key locally for connecting to the virtual host later.

-   #. 出现密钥下载按钮后，请在10分钟之内点击下载按钮完成密钥的下载，并将该密钥妥善保存到本地，以便之后连接虚拟主机使用。
+   .. figure:: /_figures/qingcloud/QingCloud-7.png
+      :scale: 50 %
+      :alt: Download SSH key

-      .. figure:: /_figures/qingcloud/QingCloud-7.png
-         :scale: 50 %
-         :alt: 下载SSH密钥
+      Download SSH Key

-         图7: 下载SSH密钥   
-
-      在关闭下载对话框之后，界面将跳转到之前的 “基本信息设置” 界面
-
-#. 在确保 SSH 密钥已妥善下载保存的情况下，如图8检查虚拟主机的基本信息，确认无误后请点击 **“创建”** 按钮。
+#. After ensuring that the SSH key has been properly downloaded and saved,
+   check the basic information of the virtual host. After confirming that they
+   are correct, click the :guilabel:`创建` (Create) button.

   .. figure:: /_figures/qingcloud/QingCloud-8.png
      :scale: 50 %
-      :alt: 确认信息并创建虚拟主机
+      :alt: Confirm the information and create a virtual host

-      图8: 确认信息并创建虚拟主机
+      Confirm the information and create a virtual host

-   确认后，QingCloud 将会创建 |CL| 虚拟主机，您可以在新的界面中查看当前虚拟主机的状态。
+QingCloud will now create the Clear Linux OS virtual host. You
+can check the state of the virtual host in the new interface.

+Apply for a public IP and add it to the virtual host
+****************************************************

-
-申请公网IP并添加到虚拟主机
-************************************
-   
-#. 由于 QingCloud 不会为使用默认网络创建的虚拟主机自动分配公网IP地址，所以我们需要手动申请，并添加到虚拟主机。如图9点击导航栏左侧的 **“网络与CDN”** 按钮。
+#. Since QingCloud does not automatically assign a public IP address to a
+   virtual host created using the default network, we need to manually apply
+   and add it to the virtual host. Click the :guilabel:`网络与CDN` (Network and
+   CDN) button on the left side of the navigation bar .

   .. figure:: /_figures/qingcloud/QingCloud-9.png
      :scale: 50 %
-      :alt: 网络与CDN
+      :alt: Network and CDN

-      图9: 网络与CDN
+      Network and CDN

-   点击后，您将来到网络与CDN配置界面。
-
-#. 在新页面中，如图10点击左侧 **“公网IP”** 按钮，并点击中间的 **“申请”** 按钮以进行创建公网IP。
+#. In the network and CDN configuration interface, click the :guilabel:`公网IP`
+   (Public IP) button on the left , and click the :guilabel:`申请` (Apply)
+   button in the middle to create a public IP.

   .. figure:: /_figures/qingcloud/QingCloud-10.png
      :scale: 50 %
-      :alt: 申请创建公网IP
+      :alt: Apply for public IP

-      图10: 申请创建公网IP
+      Apply for public IP   

-   点击申请后，将跳出提示栏，仔细阅读后按照图11点击 **“继续申请公网IP”** 按钮。
+   After clicking the apply button, a dialog will pop up. Read it
+   carefully and click the :guilabel:`继续申请公网IP` (Continue to apply for
+   public IP) button.

   .. figure:: /_figures/qingcloud/QingCloud-11.png
      :scale: 50 %
-      :alt: 提示栏确认
+      :alt: Confirmation dialog

-      图11: 提示栏确认
+      Confirmation dialog

-   之后将跳转到申请公网IP界面。
+#. On the public network IP application page, confirm and fill in the
+   relevant information, including the charging mode and bandwidth upper limit
+   (the charge-by-bandwidth mode is used in this tutorial and the 2Mbps
+   bandwidth limit is set). After confirming that they are correct, click
+   :guilabel:`提交` (Submit) button.

-#. 在申请公网IP页面中，如图12确认和填写相关信息，包括计费模式和带宽上限（本教程中使用的是流量计费模式并且设置了2Mbps的带宽上限），确认无误后点击 **“提交”** 按钮。
+   .. figure:: /_figures/qingcloud/QingCloud-12.png
+      :scale: 50 %
+      :alt: Confirmation of Public IP Application
+
+      Confirmation of Public IP Application
+
+#. After that, click the :guilabel:`计算>网卡` (Compute>Network Card) buttons
+   in the navigation bar to come to the network card interface.

   .. figure:: /_figures/qingcloud/QingCloud-13.png
      :scale: 50 %
-      :alt: 确认提交公网IP申请
+      :alt: NIC interface

-      图12: 确认提交公网IP申请
+      Network Interface

-#. 之后如图13通过导航栏点击 **“计算”**、**“网卡”** 按钮来到网卡界面。
-
-   .. figure:: /_figures/qingcloud/QingCloud-13.png
-      :scale: 50 %
-      :alt: 网卡界面
-
-      图13: 网卡界面
-
-#. 在网卡界面，按照图14选中刚刚创建的 Clear Linux OS 主机的网卡，并点击上方 **“更多操作”** 按钮，再点击 **“绑定公网IPv4”** 按钮。
+#. On the network card interface, select the network card of the |CL| host
+   that you just created. Click the :guilabel:`更多操作` (More Actions)
+   button above, and then click the :guilabel:`绑定公网IPv4` (Binding Public
+   Network IPv4) button.

   .. figure:: /_figures/qingcloud/QingCloud-14.png
      :scale: 50 %
-      :alt: 绑定选中
+      :alt: Bind selected

-      图14: 绑定选中
+      Bind selected

-#. 在绑定公网IP确认界面，按照图15选择刚刚申请完成的公网IP地址，并点击下方 **“提交”** 按钮。 等待片刻后，状态将会变成图16中所示。
+#. On the binding public network IP confirmation interface, select the public
+   IP address that has just been applied for, and click the :guilabel:`提交`
+   (Submit) button below . After waiting a moment, the state of the |CL|
+   virtual host will change.

   .. figure:: /_figures/qingcloud/QingCloud-15.png
      :scale: 50 %
-      :alt: 提交绑定
+      :alt: Commit binding

-      图15: 提交绑定
+      Commit binding

   .. figure:: /_figures/qingcloud/QingCloud-16.png
      :scale: 50 %
-      :alt: 公网IP绑定成功
+      :alt: Public network IP binding succeeded

-      图16: 公网IP绑定成功
+      Public network IP binding succeeded

+Connect to |CL| virtual host
+*********************************

-连接到 |CL| 虚拟主机
-*****************************
-
-请您点击导航栏左侧 **“计算”**、**“主机”** 按钮，确认当前虚拟主机处于正在运行状态，且已绑定了公网IP地址。如图17所示。
+Click the :guilabel:`计算>主机` (Compute>Host) buttons on the left side of the
+navigation bar to confirm that the current virtual host is running and has a public IP address.

 .. figure:: /_figures/qingcloud/QingCloud-17.png
   :scale: 50 %
-   :alt: 确认虚拟主机当前处于正常状态
+   :alt: Confirm that the virtual host is currently in a normal state

-   图17: 确认虚拟主机当前处于正常状态
+   Confirm that the virtual host is currently in a normal state

-#. 复制当前 |CL| 虚拟主机的公网IP地址，并使用 SSH 客户端进行连接。 这里我们需要用到之前保存的 SSH 密钥。
-#. 在此教程中，以 MobaXterm 客户端为例演示登录过程。请如图18检查各项。用户名我们选择 **root**，密钥请选择之前下载并保存到本地的 SSH 密钥。
+#. Copy the public IP address of the current |CL| virtual host and
+   connect to it from an SSH client. Here we need to use the previously saved
+   SSH key.
+
+#. In this tutorial, the MobaXterm client is used as an example to demonstrate
+   the login process. Check each item as shown. For the user name, we choose
+   ``root``. For the key, select the SSH key that was downloaded and saved to
+   the local computer .

   .. figure:: /_figures/qingcloud/QingCloud-18.png
      :scale: 50 %
-      :alt: SSH 登录虚拟主机设置
+      :alt: SSH login virtual host settings

-      图18: SSH 登录虚拟主机设置
+      SSH login virtual host settings
+
+#. Click :guilabel:`Login` to log in to the
+   |CL| virtual host after completing the setup process.

-#. 设置成功后，点击登录即可登录到 |CL| 虚拟主机。
-   
   .. figure:: /_figures/qingcloud/QingCloud-19.png
      :scale: 50 %
-      :alt: SSH 登录成功
+      :alt: SSH login successful

-      图19: SSH 登录成功
+      SSH login successful

+Remove |CL| virtual host
+************************

-删除 |CL| 虚拟主机
-*************************
+This section explains how to delete a |CL| virtual host created on QingCloud.

-本章节介绍如何在 QingCloud 上删除所创建的 |CL| 虚拟主机。
+On the left navigation bar select :guilabel:`计算>主机` (Compute>Master), find
+the |CL| host you just created, and click the checkbox next to it. Select
+:guilabel:`更多操作>删除` (More Actions>Delete) to delete the virtual host.

-#. 通过左侧导航栏依次选择 **“计算”**、**“主机”** 后，找到刚刚创建的 Clear Linux OS 主机，如图20所示选中此主机，再点击上方 **“更多操作”** 按钮选择 **“删除”**，即可删除虚拟主机。
+.. figure:: /_figures/qingcloud/QingCloud-20.png
+   :scale: 50 %
+   :alt: Remove Clear Linux OS Virtual Host 

-   .. figure:: /_figures/qingcloud/QingCloud-20.png
-      :scale: 50 %
-      :alt: |CL| 虚拟主机
+   Remove Clear Linux OS Virtual Host

-      图20: 删除 |CL| 虚拟主机
+Delete the applied public IP 
+****************************

+Select :guilabel:`网络与CDN>公网IP` (Network and CDN>Public IP) from the
+navigation bar on the left , and then find the public IP address just applied.
+Select it as shown, then click :guilabel:`更多操作>删除` (More Actions>Delete)
+to delete.

-删除申请的公网IP
-*****************
+.. figure:: /_figures/qingcloud/QingCloud-21.png
+   :scale: 50 %
+   :alt: Delete public network IP address

-本章节介绍如何在 QingCloud 上删除所申请的公网IP地址。
-
-#. 通过左侧导航栏依次选择 **“网络与CDN”**、**“公网IP”** 后，找到刚刚申请的公网IP地址，如图21所示选中此项目，再点击上方 **“更多操作”** 按钮选择 **“删除”**，即可删除。
-
-   .. figure:: /_figures/qingcloud/QingCloud-21.png
-      :scale: 50 %
-      :alt: 删除公网IP地址
-
-      图21: 删除公网IP地址
+   Delete public network IP address
+      
@@ -0,0 +1,79 @@
+.. _container-images:
+
+|CL-ATTR| container images
+##########################
+
+|CL| can run inside of a container on top of any operating system as long as
+it is hosting a containerized environment, such as Docker* or Kubernetes*. A
+|CL| base image is available for standalone use as well as variations of
+popular application images built from the |CL| base image.
+
+Browse all |CL| container images on `the Docker Hub* website
+<https://hub.docker.com/search?q=clearlinux&type=image>`_. Find the
+Dockerfiles used to build |CL| container images `on GitHub
+<https://github.com/clearlinux/dockerfiles>`_.
+
+See the `containers <https://clearlinux.org/downloads/containers>`_ page for
+the benefits of using |CL| containers and using |CL| as a container host.
+
+Container image types
+*********************
+
+|CL| base image
+===============
+
+The `Clear Linux OS base container <https://hub.docker.com/_/clearlinux>`_ is
+an official image on Docker Hub*. The |CL| base container image can be used to
+run a standalone or as a `parent image
+<https://docs.docker.com/glossary/#parent_image>`_ for building other
+container images. 
+
+On a Docker host simply use the command :command:`docker run clearlinux` to
+pull and start a |CL| container. 
+
+
+|CL|-based runtime images
+=========================
+
+|CL| container images for programming languages and their runtimes are
+available on Docker Hub*. These can be used by developers to create and run
+applications using these popular runtimes. 
+
+Below are some popular |CL|-based runtime images:
+
+* `clearlinux/golang <https://hub.docker.com/r/clearlinux/golang>`_
+* `clearlinux/node <https://hub.docker.com/r/clearlinux/node>`_
+* `clearlinux/numpy <https://hub.docker.com/r/clearlinux/numpy>`_
+* `clearlinux/python <https://hub.docker.com/r/clearlinux/python>`_
+* `clearlinux/perl <https://hub.docker.com/r/clearlinux/perl>`_
+* `clearlinux/r-base <https://hub.docker.com/r/clearlinux/r-base>`_
+
+More |CL|-based images can be found on Docker Hub:
+https://hub.docker.com/u/clearlinux.
+
+
+|CL|-based application images
+=============================
+
+|CL| container images for common applications are available on Docker Hub.
+These can be used to create and deploy containerized services.
+
+Below are some popular |CL|-based runtime images:
+
+* `clearlinux/nginx <https://hub.docker.com/r/clearlinux/nginx>`_
+* `clearlinux/mariadb <https://hub.docker.com/r/clearlinux/mariadb>`_
+* `clearlinux/postgres <https://hub.docker.com/r/clearlinux/postgres>`_
+* `clearlinux/redis <https://hub.docker.com/r/clearlinux/redis>`_
+* `clearlinux/tensorflow <https://hub.docker.com/r/clearlinux/tensorflow>`_
+* `clearlinux/wordpress <https://hub.docker.com/r/clearlinux/wordpress>`_
+
+
+More |CL|-based images can be found on Docker Hub:
+https://hub.docker.com/u/clearlinux.
+
+Related topics
+==============
+* :ref:`container-image-new`
+* :ref:`container-image-modify`
+* :ref:`docker`
+* :ref:`kata`
@@ -3,8 +3,9 @@
 Get started
 ###########

-The Get Started section guides you through the requirements and installation of
-|CL-ATTR|. Follow these step-by-step instructions to get started with |CL|, fast.
+The Get Started section guides you through the requirements and installation
+of |CL-ATTR|. Follow these step-by-step instructions to get started with |CL|,
+fast.

 Pre-install
 ***********
@@ -50,10 +51,19 @@ Install in a virtual machine
   ../../guides/maintenance/increase-virtual-disk-size.rst

 Deploy to the cloud
-********************
+*******************

 .. toctree::
   :maxdepth: 1
   :glob:

   cloud-install/*
+
+Containers
+**********
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   containers/*
@@ -3,10 +3,11 @@
 Install using clr-installer and a configuration file
 ####################################################

-This page explains how to install |CL-ATTR| using the clr-installer tool
-with a configuration file. The configuration file (:file:`clr-installer.yaml`)
-can be reused to duplicate the same installation configuration on additional
-machines.
+In addition to the interactive GUI and text-based modes,
+:command:`clr-installer` also supports an unattended mode where you 
+simply provide it a YAML configuration file.  
+
+This guide shows you two examples of how to use its unattended mode.  

 .. contents::
   :local:
@@ -15,67 +16,63 @@ machines.
 Prerequisites
 *************

-Ensure that your target system supports the installation:
+For installation onto bare metal, ensure that your target system 
+supports these requirements:

 * :ref:`system-requirements`
 * :ref:`compatibility-check`

-Process
-*******
+Download and make bootable USB of the live server image
+*******************************************************

-This guide describes two methods for using a configuration file with the
-clr-installer tool. You can use either method to achieve the same goal. Choose
-the method that works best for your setup.
+See :ref:`bootable-usb`.

-If you are installing |CL| for the first time, we recommend Example 1.
+Example 1: Fresh installation onto bare metal
+*********************************************

-To clone an existing |CL| setup on another system, we recommend Example 2.
+This example uses a YAML configuration file to perform a new installation.

-Example 1
-=========
+#. Boot up the |CL| Live Server USB thumb drive.

-This method uses a configuration file template to perform a new installation.
-
-Perform the following steps:
-
-#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
-
-   For example:
-   https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
-
-#. Follow the instructions to :ref:`bootable-usb` based on your OS.
-
-#. Boot up the USB thumb drive.
 #. Select :guilabel:`Clear Linux OS` from the menu.
-#. In the console window, log in as root and set a password.
+
+#. In the console window, log in as `root` and set a password.
+
 #. Verify you have a network connection to the Internet and configure proxy
   settings if you're working behind a firewall.
-#. Download a :file:`live-server.yaml` template.

-   For example:
+#. Download a sample YAML configuration file. For example, if you want to 
+   install |CL| with a desktop GUI, you might want to use :file:`live-desktop.yaml`.
+   Or you can use the :file:`live-server.yaml` if you want to install a non-GUI version
+   of |CL|.

-   .. code-block:: bash
+   * *Desktop:*

-      curl -O https://download.clearlinux.org/releases/30010/clear/config/image/live-server.yaml
+     .. code-block:: bash

-#. Edit the template and change the settings as needed.
+        curl -O https://cdn.download.clearlinux.org/current/config/image/live-desktop.yaml

-   Commonly-changed settings include:
+   * *Server:*

-.. _install-configfile-yaml-begin:
+     .. code-block:: bash

-   #. Under *block-devices*, set “file: "/dev/sda"” or enter your preferred device.
-   #. Under *targetMedia*, set the third partition size to “0” to use the entire disk space.
-   #. Under *bundles*, add additional bundles as needed.
+        curl -O https://cdn.download.clearlinux.org/current/config/image/live-server.yaml
+
+#. Edit the YAML configuration file and change the settings as needed.
+
+   Commonly-changed settings include (refer to the example below):
+
+   a. Under *block-devices* (line 15), set your target media.  For example: ``file: "/dev/sda"``.
+   #. Under *targetMedia* (line 34), set the third partition size to “0” to use the entire disk space.
+   #. Under *bundles* (line 37), add additional bundles as needed.
   #. Delete the *post-install* section unless you have post-installation scripts.
-   #. Under *Version*, set a version number. To use the latest version, set to “0”.
+   #. Under *Version* (line 50), set a version number. To use the latest version, set to “0”.

-   Commonly-changed settings are shown in lines 15, 34, 37, and 51 below.
   See `Installer YAML Syntax`_ for more details.

-   .. code-block:: bash
+   .. code-block:: console
      :linenos:
-      :emphasize-lines: 14,15,34,37,51
+      :emphasize-lines: 14,15,34,37,50

 		#clear-linux-config

@@ -121,7 +118,6 @@ Perform the following steps:
 		telemetry: false
 		iso: true
 		keepImage: true
-		autoUpdate: false

 		keyboard: us
 		language: en_US.UTF-8
@@ -129,56 +125,67 @@ Perform the following steps:

 		version: 30010

-.. _install-configfile-yaml-end:
-
-Start the installation with the command:
-
-.. code-block:: bash
-
-   clr-installer --config live-server.yaml
-
-Example 2
-=========
-
-This method uses a saved configuration file from a previous installation,
-which you can use to easily duplicate the installation on additional machines.
-
-Perform the following steps:
-
-#. Open a console window on a system where |CL| was installed to retrieve a
-   copy of the configuration file.
-
-#. In the console window, log in as root and enter your password.
-
-#. Change directory to :file:`/root` and copy the :file:`clr-installer.yaml`
-   file to a USB thumb drive.
+#. Start the unattended installation using the `--config` option.

   .. code-block:: bash

-   	  cd /root
-   	  cp clr-installer.yaml <USB-thumb-drive>
+      clr-installer --config live-server.yaml

-Start the installation on the target with the following steps:
+#. Reboot your system after installation is completed.

-#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
+Example 2: Replicate a previous installation
+********************************************

-   For example:
-   https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
+This example uses a saved configuration file from a previous installation,
+which you can use to easily clone the installation on additional machines
+, ideally with the same hardware configuration.

-#. Follow the instructions to :ref:`bootable-usb` based on your OS.
+.. warning::
+   
+   Be aware of the following when applying a saved configuration on a new machine:
+   
+   * Make sure the target media on the new machine matches up
+   
+   * The users' credentials will be replicated as well

-#. Boot up the USB thumb drive.
-#. Select :guilabel:`Clear Linux OS` from the menu.
-#. In the console window, log in as root and set a password.
-#. Verify you have a network connection to the Internet and configure proxy
-   settings if you're working behind a firewall.
-#. Plug in and mount the USB thumb drive containing the retrieved
-   :file:`clr-installer.yaml` configuration file.
-#. Start the installation with the command:
+#. On a system where |CL| was installed, open a terminal window.
+
+#. Get root privilege.

   .. code-block:: bash

-      clr-installer --config clr-installer.yaml
+      sudo su
+
+#. Copy the :file:`clr-installer.yaml` from :file:`/root` to a USB thumb drive.
+
+   .. code-block:: bash
+
+      cp /root/clr-installer.yaml <USB-thumb-drive>
+
+#. Install on target system.
+
+   a. Boot up the |CL| Live Server USB thumb drive.
+
+   #. Select :guilabel:`Clear Linux OS` from the menu.
+
+   #. In the console window, log in as `root` and set a password.
+
+   #. Verify you have a network connection to the Internet and configure proxy
+      settings if you're working behind a firewall.
+
+   #. Plug in and mount the USB thumb drive containing the retrieved
+      :file:`clr-installer.yaml` configuration file.
+   
+   #. Doublecheck to make sure the target media in the saved configuration file
+      matches with the target system's. 
+
+   #. Start the installation.
+
+      .. code-block:: bash
+
+         clr-installer --config clr-installer.yaml
+
+   #. Reboot your system after installation is completed.

 References
 **********
@@ -186,7 +193,5 @@ References
 * `Clear Linux Installer`_
 * `Installer YAML Syntax`_

-.. _Downloads: https://clearlinux.org/downloads
 .. _Clear Linux Installer: https://github.com/clearlinux/clr-installer
-
-.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md
+.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md
@@ -100,17 +100,27 @@ Setup nginx web server to host iPXE

   .. code-block:: bash

+      # setup nginx
      sudo mkdir -p /etc/nginx/conf.d
      sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
+      
+      # grant $USER permission to run the web server
+      sudo tee -a /etc/nginx/nginx.conf << EOF
+      user $USER;
+      EOF
+
+      # web server config
      sudo tee -a /etc/nginx/conf.d/${IPXE_APP_NAME}.conf << EOF
      server {
        listen ${IPXE_PORT};
        server_name localhost;
+
        # directory to store ipxe
        location /${IPXE_APP_NAME}/ {
          root ${WEB_ROOT_DIR}/${IPXE_APP_NAME};
          rewrite ^/${IPXE_APP_NAME}(/.*)$ \$1 break;
        }
+
        # directory to store clr-installer configs
        location /${CLR_INSTALLER_CONF_DIR}/ {
          root ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR};
@@ -123,8 +133,7 @@ Setup nginx web server to host iPXE

   .. code-block:: bash

-      sudo systemctl enable nginx
-      sudo systemctl start nginx
+      sudo systemctl enable nginx --now

 Configure iPXE
 **************
@@ -296,7 +296,7 @@ in the **Install |CL| using ISO** tab.  Otherwise, follow the
            files under:

            * Linux distros :file:`/home/username/vmware`
-            * Windows :file:`C:\Users\username\Documents\Virtual Machines`
+            * Windows :file:`C:\\Users\\username\\Documents\\Virtual Machines`

      #. Start the ``VMware Workstation Player`` app.

@@ -0,0 +1,79 @@
+.. _cl-guides:
+
+|CL-ATTR|
+#########
+
+.. note::
+
+   As of 22 May 2019 :file:`mixin` is no longer supported.
+
+.. container:: multicolumns three
+
+   .. container:: column smallcard featurecard
+
+      :ref:`swupd-guide`
+         Learn how to manage software and system updates in |CL|.
+
+   .. container:: column smallcard featurecard
+
+      :ref:`debug`
+         Discover how to use :command:`clr-debug-info` to leverage your
+         network to debug system software.
+
+   .. container:: column smallcard featurecard
+
+      :ref:`telem-guide`
+         Learn how you can opt-in to allow |CL| to collect data to identify
+         and fix bugs.
+
+   .. container:: column smallcard
+      
+      :ref:`autoproxy`
+          Discover how |CL| makes working behind a corporate proxy smoother.
+
+   .. container:: column smallcard
+
+      :ref:`autospec`
+         Learn about :command:`autospec` and how it used to automatically
+         include and maintain open source software in |CL|.
+
+   .. container:: column smallcard
+
+      :ref:`bundles-guide`
+         Find out what a bundle is and why it is an important part of
+         what makes |CL| secure and high performance. 
+
+   .. container:: column smallcard
+
+      :ref:`compatible-kernels`
+         Learn about all of the kernels available as installable bundles.
+
+   .. container:: column smallcard
+
+      :ref:`ister`  
+         Find out how |CL| uses this template-based installer to produce
+         images for each release.
+
+   .. container:: column smallcard
+
+      :ref:`mixer`
+         Learn how the |CL| team generates official update content and
+         releases.
+
+   .. container:: column smallcard
+
+      :ref:`security`
+         Learn how |CL| is designed to ensure the security of updates and
+         software.
+
+   .. container:: column smallcard
+
+      :ref:`stateless`
+         |CL| is stateless is designed to need little to no user
+         configuration.
+
+.. toctree::
+   :glob:
+   :hidden:
+
+   *
@@ -1,92 +0,0 @@
-.. _ister:
-
-ister.py image builder
-######################
-
-The `ister.py`_ tool is a template-based installer used by |CL-ATTR| to produce
-images for each release. The same ister tool is available for use in |CL| to
-create custom images based on an upstream image.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-|CL| is a rolling release and produces an average of 10 releases per week using the
-ister tool. With each release, we produce multiple
-:ref:`image types for different environments <image-types>` and use cases such
-as installers, Hyper-V, KVM, or VMWare.
-
-Each image has a JSON configuration file that is used by ister to generate the 
-image. These JSON configuration files describe the image type, partitions, version,
-and bundles that will be preinstalled by default with the image. For each image
-type we produce, the corresponding JSON configuration file for the image also is
-published.
-
-The :ref:`mixer<mixer>` tool also uses ister to build images for your custom
-mix. Like upstream images, a JSON configuration file is defined for the image,
-which ister uses to generate the image. Refer to the :ref:`mixer<mixer>` guide
-for instructions on using ister to build an image for a custom mix.
-
-Examples
-********
-
-Recreate an upstream image
-==========================
-
-The published configuration files for upstream images may be used to recreate an
-image. Here are some examples:
-
-* Use an older version of |CL| and the image is no longer available (only after
-  March 2017).
-* Customize the partitions of an image.
-* Customize the bundles preinstalled in an image.
-* Run your own post installation script.
-
-
-Follow these steps to recreate an upstream image based on the image's JSON
-configuration file:
-
-#. Install the :command:`os-installer` bundle. Refer to :ref:`swupd-guide` for
-   more information on installing bundles.
-
-#. Download the `ister.py`_ tool and grant it sudo privileges.
-
-#. Download the JSON configuration file for the desired image (located in
-   :file:`config/image/`):
-
-   * `Current release`_
-   * `Previous releases`_ (only after March 2017)
-
-   For a previous release, navigate to `Previous releases`_, select the version
-   you want, and find the JSON configuration file under
-   :file:`/clear/config/image`. For example:
-   ``https://cdn.download.clearlinux.org/releases/15700/clear/config/image/``
-
-#. Download the “PostNonChroot” script (if applicable).
-
-   The JSON configuration file for the image may have an accompanying
-   “PostNonChroot” script that is executed at the end of the image creation
-   process. If it does, download the script and make it executable.
-
-#. Edit the JSON configuration file as needed.
-
-#. If your configuration file has an accompanying "PostNonChroot" script, change
-   the default path of the script to match your path.
-
-#. Generate the new image with the following command:
-
-   .. code-block:: bash
-
-   	sudo ister.py -t [JSON configuration]
-
-Related topics
-**************
-
-* :ref:`mixer`
-
-.. _ister.py: https://github.com/bryteise/ister
-.. _Current release: https://cdn.download.clearlinux.org/current/
-.. _Previous releases: https://cdn.download.clearlinux.org/releases/
@@ -3,10 +3,9 @@
 mixer
 #####

-**mixer** is the tool used by the |CL-ATTR| team to generate official update
-content and releases. The update content generated by mixer is then consumed
-by swupd on a downstream client. The same mixer tool is available as part of
-|CL| to create your own customized update content and releases.
+The |CL-ATTR| team uses **mixer** to generate official update content and 
+releases. The update content generated by mixer is then consumed by swupd on 
+a downstream client. The same mixer tool is available to those who wish to create customized update content and releases.

 .. contents::
   :local:
@@ -20,13 +19,21 @@ mixer uses the following sources as inputs to generate update content:
 * Upstream |CL| bundles with their corresponding RPM packages
 * Locally-defined bundles with their corresponding local RPM packages
 * Locally-defined bundles with upstream RPM packages
+* Locally-defined bundles with non-RPM content

-Using the mixer tool, you select which set of content from these sources
-will be part of your update. You can select content from each of these sources to make a unique combination of functionality for your custom update content, known as a **mix**.
+Using the mixer tool, you select which content from these sources that
+becomes part of your update. Your selection of sources produces a unique 
+combination of functionality for your custom update content, known as 
+a **mix**.

 The update content that mixer generates consists of various pieces of OS
 content, update metadata, as well as a complete image. The OS content
-includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via :command:`swupd`. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
+includes all files in an update, as well as zero- and delta-packs for
+improved update performance. The update metadata, stored as manifests, 
+describes all of the bundle information for the update. Update content 
+produced by mixer is then published to a web server and consumed by clients 
+via :command:`swupd`. Refer to :ref:`swupd <swupd-guide>` for additional 
+information regarding updates and update content.

 How it works
 ************
@@ -45,26 +52,6 @@ Prerequisites
  Add the mixer tool by installing the :command:`mixer` bundle. Refer to
  :ref:`swupd-guide` for more information on installing bundles.

-* Docker\* container
-
-  mixer by default runs all build commands in a Docker container to ensure
-  the correct tool versions are used. This also allows custom mixes to
-  automatically perform downstream format bumps when the upstream releases a
-  format bump. See `Format version`_ for additional information regarding
-  format bumps.
-
-  Refer to `Configure and enable Docker`_ for instruction.
-
-* Docker proxy (optional)
-
-  If you use a proxy server, you must set your proxy environment variables and
-  create a proxy configuration file for the Docker daemon and container.
-
-  Consult your IT department for the correct values if you are behind a
-  corporate proxy.
-
-  Refer to `Configure Docker proxy info`_ for instruction.
-
 * Location to host the update content and images

  In order for :command:`swupd` to make use of your mix, the update content for your mix must be hosted on a web server. Your mix will be configured with an update location URL, which :command:`swupd` will use to pull down updates.
@@ -160,7 +147,7 @@ A mix is created with the following steps:
 #. Create image.

   mixer creates a bootable image from your updated content using
-   the :ref:`ister` tool. In this step you can specify which bundles you want
+   the `clr-installer`_ tool. In this step you can specify which bundles you want
   *preinstalled* in the image. Users can later install other bundles available
   in your mix.

@@ -256,11 +243,13 @@ these include the :command:`native-kernel` bundle that is intended to be
 used on a bare metal system instead of a VM. So we will modify the default
 bundle set to get a smaller kernel image, which will also be faster to load.

-The only bundles available to :command:`swupd` for a given release are those
-that were added to the mix during build time. A mix doesn’t automatically
-inherit upstream bundles.
+.. note:: 
+   
+   The only bundles available to :command:`swupd` for a given release are 
+   those that were added to the mix during build time. A mix doesn’t 
+   automatically inherit all upstream bundles.

-#. Assure that you have run `mixer init`, shown in Example 1.
+#. Ensure that you have run `mixer init`, shown in Example 1.

 #. Update bundles in mix:

@@ -345,61 +334,101 @@ Refresh your web server to see the update content for mix version 20.
 You can also look in ~/mixer/update/www/<mix version> to see the update
 content in your workspace.

-
 Example 4: Build an image
 =========================

 This example shows how to build a bootable image containing the
 :command:`kernel-kvm`, :command:`os-core`, and the :command:`os-core-update`
-bundles from Example 2. Underneath, mixer uses `ister`_ to generate the
-image.
+bundles from `Example 2: Create a simple mix`_. Complete that example before starting this one.  
+
+Underneath, mixer uses `clr-installer`_ to generate the image.

 #. Change directory into your mix.

 #. Configure image.

-   Edit the ister configuration file for your image to include all of the bundles you want pre-installed in the image. If this is the first time creating an image, first get a copy of the
-   :file:`release-image-config.json` template file:
+   Create a YAML configuration file to specify aspects of your image
+   such as image name, target media, bundles, etc.  See `Installer YAML Syntax`_ 
+   for more information on clr-installer configuration YAML syntax.
+
+   For this example, we will download a sample YAML and modify it.

   .. code-block:: bash

-      curl -O https://raw.githubusercontent.com/bryteise/ister/master/release-image-config.json
+      curl -O https://raw.githubusercontent.com/clearlinux/clr-installer/master/scripts/kvm.yaml

-   For this example, make the following revisions
-   :file:`release-image-config.json`:
+   Make the following revisions to :file:`kvm.yaml`:

-   * Set root partition size to "5G"
-   * Replace the "kernel-native" bundle with "kernel-kvm"
-   * Set the version to 10 (as an integer)
+   * Reduce overall image size and root partition size by 5GB.
+   * Remove these bundles from the image: ``editors``, ``network-basic``, 
+     ``openssh-server``, ``sysadmin-basic``
+   * Add ``version: 10`` to tell :command:`mixer` to generate an image based 
+     on mix version 10

   .. note::
-      When creating an image, select a subset of the bundles that are part of your mix. All the bundles that are *not* part of this subset are available for consumers of that image to install afterwards via swupd.

-   .. code-block:: bash
+      When creating an image, it is not necessary to include all of the bundles
+      that are in your entire mix.  Once you have a working image, you can use 
+      :command:`swupd` to add them as needed.  
+
+   Your :file:`kvm.yaml` should look like below:
+
+   .. code-block:: console
      :linenos:
-      :emphasize-lines: 5,11-12
+      :emphasize-lines: 11,26,29-33,44
+      
+      #clear-linux-config

-      {
-       "DestinationType" : "virtual",
-        "PartitionLayout" : [ { "disk" : "release.img", "partition" : 1, "size" : "32M", "type" : "EFI" },
-                                  { "disk" : "release.img", "partition" : 2, "size" : "16M", "type" : "swap" },
-                                  { "disk" : "release.img", "partition" : 3, "size" : "5G", "type" : "linux" } ],
-        "FilesystemTypes" : [   { "disk" : "release.img", "partition" : 1, "type" : "vfat" },
-                                  { "disk" : "release.img", "partition" : 2, "type" : "swap" },
-                                  { "disk" : "release.img", "partition" : 3, "type" : "ext4" } ],
-        "PartitionMountPoints" : [ { "disk" : "release.img", "partition" : 1, "mount" : "/boot" },
-                                       { "disk" : "release.img", "partition" : 3, "mount" : "/" } ],
-        "Version": 10,
-        "Bundles": ["kernel-kvm", "os-core", "os-core-update"]
-       }
+      # switch between aliases if you want to install to an actuall block device
+      # i.e /dev/sda
+      block-devices: [
+         {name: "bdevice", file: "kvm.img"}
+      ]
+
+      targetMedia:
+      - name: ${bdevice}
+        size: "3.54G"
+        type: disk
+        children:
+        - name: ${bdevice}1
+          fstype: vfat
+          mountpoint: /boot
+          size: "512M"
+          type: part
+        - name: ${bdevice}2
+          fstype: swap
+          size: "32M"
+          type: part
+        - name: ${bdevice}3
+          fstype: ext4
+          mountpoint: /
+          size: "3G"
+          type: part
+
+      bundles: [
+          bootloader,
+          os-core,
+          os-core-update,
+        ]
+
+      autoUpdate: false
+      postArchive: false
+      postReboot: false
+      telemetry: false
+
+      keyboard: us
+      language: en_US.UTF-8
+      kernel: kernel-kvm
+
+      version: 10

 #. Build the image.

   .. code-block:: bash

-      sudo mixer build image
+      sudo mixer build image --template $PWD/kvm.yaml

-   The output from this step will be :file:`release.img`, which is a live
+   The output from this step will be :file:`kvm.img`, which is a live
   image.

 Example 5: Deploy updates to target
@@ -430,11 +459,15 @@ mix version 10 to mix version 20.

   .. code-block:: bash

-      sudo ./start_qemu.sh release.img
+      sudo ./start_qemu.sh kvm.img

 #. Log in as root and set a password.

-#. To avoid adding a flag each time, enter:
+#. By default, the :command:`swupd` client is designed to communicate with an
+   HTTPS server. For development purposes, the swupd client can talk to
+   an HTTP server if you add the flag ``allow-insecure-http``.
+
+   To avoid adding a flag each time when invoking :command:`swupd`, enter:

   .. code-block:: bash

@@ -444,67 +477,65 @@ mix version 10 to mix version 20.
      allow_insecure_http=true
      EOF

-   .. note:
-
-      By default, the swupd client is designed to communicate with an
-      *\https* server. For development purposes, the swupd client can talk to
-      an *\http* server if you add the flag :command:`--allow-insecure-http`.
-
 #. Try out your mix.

-   Take a look at the default bundles installed in your mix:
+   a. Show the version and update URLs

-   .. code-block:: bash
+      .. code-block:: bash

-      swupd info
-      swupd bundle-list
+         swupd info

-#. List available bundles on your update server.
+   #. List the bundles installed in your mix:

+      .. code-block:: bash

-   .. code-block:: bash
+         swupd bundle-list

-      swupd bundle-list -a
+   #. List available bundles on your update server.

-#. Now we will add the :command:`editors` bundle that we modified.
+      .. code-block:: bash

-   .. code-block:: bash
+         swupd bundle-list -a

-      swupd bundle-add editors
+   #. Now we will add the :command:`editors` bundle that we modified.

-#. Try to start the :command:`joe` editor.
+      .. code-block:: bash

-   .. code-block:: bash
+         swupd bundle-add editors

-      joe
+   #. Try to start the :command:`joe` editor.

-   It should not appear. We removed it from the original
-   :command:`editors` bundle.
+      .. code-block:: bash

-#. Next we will update from version 10 to 20 to capture the newly
-   available bundles.
+         joe

-   .. code-block:: bash
+      It should not work because we removed it from the original
+      :command:`editors` bundle.

-      swupd check-update
-      swupd update
-      swupd bundle-list -a
+   #. Next we will update from version 10 to 20 to capture the 
+      newly-available bundles.

-#. Now your mix should be at version 20 and curl is available. Try using
-   curl. This will fail because curl is not yet installed:
+      .. code-block:: bash

-   .. code-block:: console
+         swupd check-update
+         swupd update
+         swupd bundle-list -a

-      curl: command not found
-      To install curl use: swupd bundle-add curl
+   #. Now your mix should be at version 20 and :command:`curl` is available. 
+      Try using :command:`curl`. This will fail because it is not yet installed.

-#. Add the new bundle from your update server to your VM. Retry curl.
-   It works!
+      .. code-block:: console

-   .. code-block:: bash
+         curl: command not found
+         To install curl use: swupd bundle-add curl

-      swupd bundle-add curl
-      curl -O https://download.clearlinux.org/image/start_qemu.sh
+   #. Add the new bundle from your update server to your VM. Retry :command:`curl`.
+      It works!
+
+      .. code-block:: bash
+
+         swupd bundle-add curl
+         curl -O https://download.clearlinux.org/image/start_qemu.sh

 #. Shutdown your VM:

@@ -658,8 +689,7 @@ customizations during the update, such as:

 * Change the content of the chroot

-Use the `afb.sh reference script`_ to learn how to do a manual format bump.
-The :file:`afb.sh` script shows an example of how to:
+Follow the `afb.sh reference script`_ to learn how to do a manual format bump. The `afb.sh reference script`_ shows an example of how to:

 * Create a mix

@@ -669,16 +699,6 @@ The :file:`afb.sh` script shows an example of how to:

 * Do a format bump to remove the deprecated bundle

-Read the comments above each line for an explanation of each step as you
-execute commands. Use this same process on your mix if you need to remove a
-bundle and its tracking.
-
-
-
-.. Example: Create a mix with custom RPM
-.. -------------------------------------
-.. TODO future example to show copy into local-rpms...
-
 References
 **********

@@ -702,32 +722,89 @@ content.

   #builder.conf

-   #VERSION 1.0
+   #VERSION 1.2

   [Builder]
-     CERT = "/home/clr/mix/Swupd_Root.pem"
-     SERVER_STATE_DIR = "/home/clr/mix/update"
-     VERSIONS_PATH = "/home/clr/mix"
-     YUM_CONF = "/home/clr/mix/.yum-mix.conf"
+      CERT = "/home/clr/mix/Swupd_Root.pem"
+      SERVER_STATE_DIR = "/home/clr/mix/update"
+      VERSIONS_PATH = "/home/clr/mix"
+      YUM_CONF = "/home/clr/mix/.yum-mix.conf"

   [Swupd]
-     BUNDLE = "os-core-update"
-     CONTENTURL = "<URL where the content will be hosted>"
-     VERSIONURL = "<URL where the version of the mix will be hosted>"
+      BUNDLE = "os-core-update"
+      CONTENTURL = "<URL where the content will be hosted>"
+      VERSIONURL = "<URL where the version of the mix will be hosted>"
+      COMPRESSION = ["external-xz"]
+      UPSTREAM_BUNDLES_URL = "https://github.com/clearlinux/clr-bundles/archive/"

   [Server]
-     DEBUG_INFO_BANNED = "true"
-     DEBUG_INFO_LIB = "/usr/lib/debug"
-     DEBUG_INFO_SRC = "/usr/src/debug"
+      DEBUG_INFO_BANNED = "true"
+      DEBUG_INFO_LIB = "/usr/lib/debug"
+      DEBUG_INFO_SRC = "/usr/src/debug"

   [Mixer]
-     LOCAL_BUNDLE_DIR = "/home/clr/mix/local-bundles"
-     LOCAL_REPO_DIR = ""
-     LOCAL_RPM_DIR = ""
-     DOCKER_IMAGE_PATH = "clearlinux/mixer"
+      LOCAL_BUNDLE_DIR = "/home/clr/mix/local-bundles"
+      LOCAL_REPO_DIR = "/home/clr/mix/local-yum"
+      LOCAL_RPM_DIR = "/home/clr/mix/local-rpms"
+      OS_RELEASE_PATH = ""

-Additional explanation of variables in :file:`builder.conf` is provided in Table
-1.
+Additional explanation of variables in :file:`builder.conf` is provided in 
+Table 1.
+
+.. list-table:: **Table 1**: Variables in builder.conf   
+   :widths: 50, 50
+   :header-rows: 1
+
+   * - **Variable**
+     - **Description**
+
+   * - `CERT` 
+     - Sets the path where mixer stores the certificate file used to sign
+       content for verification. mixer automatically generates the 
+       certificate if you do not provide the path to an existing one, and 
+       signs the :file:`Manifest.MoM` file to provide security for the 
+       updated content you create. 
+
+       chroot-builder uses the certificate file to sign the root :file:`
+       Manifest.MoM` file to provide security for content verification. 
+       swupd uses this certificate to verify the :file:`Manifest.MoM` file's 
+       signature. 
+
+       For now, we strongly recommend that you do not modify this variable, 
+       as swupd expects a certificate with a very specific configuration to sign and verify properly.  
+
+   * - `CONTENTURL` and `VERSIONURL`
+     - Set these variables to the IP address of the web server hosting the
+       update content. 
+
+       VERSIONURL is the IP address where the swupd client 
+       looks to determine if a new version is available. 
+
+       CONTENTURL is the location from which swupd pulls content updates. If 
+       the web server is on the same machine as the SERVER_STATE_DIR 
+       directory, you can create a symlink to the directory in your web 
+       server's document root to easily host the content. 
+
+       These URLs are embedded in the images created by mixer.
+
+   * - `LOCAL_BUNDLE_DIR` 
+     - Sets the path where mixer stores the local bundle definition files. 
+       The bundle definition files include any new, original bundles you 
+       create, along with any edited versions of upstream bundles.  
+
+   * - `SERVER_STATE_DIR`
+     - Sets the path to which mixer outputs content. By default, mixer
+       automatically sets the path.    
+
+   * - `VERSIONS_PATH`
+     - Sets the path for the mix version and upstream version's two state
+       files: :file:`mixversion` and :file:`upstreamversion`. mixer creates 
+       both files for you when you set up the workspace.
+    
+   * - `YUM_CONF`  
+     - Sets the path where mixer automatically generates the  
+       :file:`.yum-mix.conf` file. The yum configuration file points the 
+       chroot-builder to where the RPMs are stored.

 +-------------------------------+----------------------------------------------------------+
 | **Variable**                  | **Explanation**                                          |
@@ -767,9 +844,6 @@ Additional explanation of variables in :file:`builder.conf` is provided in Table
 |                               |                                                          |
 |                               | These URLs are embedded in the images created by mixer.  |
 +-------------------------------+----------------------------------------------------------+
-| `DOCKER_IMAGE_PATH`           | Sets the base name of the docker image that mixer pulls  |
-|                               | down to run builds in the proper container.              |
-+-------------------------------+----------------------------------------------------------+
 | `LOCAL_BUNDLE_DIR`            | Sets the path where mixer stores the local bundle        |
 |                               | definition files. The bundle definition files include    |
 |                               | any new, original bundles you create, along with any     |
@@ -841,13 +915,12 @@ Bundles
 =======

 mixer stores information about the bundles included in a mix in a flat file
-called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is automatically created when the mix is initiated. mixer will refresh the file each time you change the bundles in the mix.
+called :file:`mixbundles`, which is located in the path set by the 
+VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is 
+automatically created when the mix is initiated. mixer will refresh the file 
+each time you change the bundles in the mix.

-Bundles can include other bundles. Nested bundles can themselves include
-other bundles. If you see an unexpected bundle in your mix, it is likely a
-nested bundle in one of the bundles you explicitly added.
-
-A bundle will fill into one of two categories: upstream or local. Upstream
+Bundles belong in one of two categories: upstream or local. Upstream
 bundles are those provided by |CL|. Local bundles are either modified upstream bundles or new local bundles.

 Upstream bundles
@@ -861,8 +934,8 @@ contents of this directory before repopulating it on-the-fly if a new
 version must be downloaded.

 The mixer tool automatically caches the bundles for the |CL| version
-configured in the :file:`upstreamversion` file. mixer also cleans up old
-versions once they are no longer needed.
+configured in the :file:`upstreamversion` file. :command:`mixer` also 
+cleans up old versions once they are no longer needed.

 Local bundles
 -------------
@@ -877,13 +950,62 @@ precedence over any upstream bundles that have the same name. This
 precedence enables you to copy upstream bundles locally, and edit into a
 local variation.

+
+Bundle definition files
+-----------------------
+
+A ``bundle definition`` file consists of a header, followed by a list 
+of packages and directives. The header holds important meta-data, like 
+the TITLE, DESCRIPTION, and STATUS. Other meta-data include TAGS, which 
+define a bundle's function in the ecosystem, and MAINTAINER, which gives 
+contact information. 
+
+Following the header are the directives, shown in Table 2. 
+
+.. list-table:: **Table 2**: Bundle directives
+   :widths: 50,50
+   :header-rows: 1 
+
+   * - **Directive**
+     - **Description**
+
+   * - ``include(<required-bundle-name>)``
+     - Add <required-bundle-name> with this bundle
+
+   * - ``also-add(<optional-bundle-name>)``
+     - Add <optional-bundle-name> unless the option ``--skip-optional`` is used with ``swupd bundle-add``.
+
+   * - ``content(<full/path/to/non-packaged/content>)``
+     - Add the non-packaged content to the bundle. Refer to :ref:`swupd-3rd-party` for usage of this directive. 
+
+Following is `cluster-tools`, an upstream bundle definition file. The
+directives are highlighted, and the rest are packages.
+
+.. code-block:: bash
+   :emphasize-lines: 8-12
+
+   [TITLE]: cluster-tools
+   [DESCRIPTION]: Utilities to manage computer clusters
+   [STATUS]: Active
+   [CAPABILITIES]: HPC
+   [TAGS]: Tools and Utilities
+   [MAINTAINER]: Juro Bystricky <juro.bystricky@intel.com>
+
+   include(curl)
+   include(libglib)
+   include(libX11client)
+   also-add(openmpi)
+   also-add(modules)
+   munge
+   pmix
+   pdsh
+   slurm
+
 Bundle configuration
 --------------------

 mixer provides commands to configure the bundles for a mix, such as to add a
-bundle to a mix, to create a new bundle for a mix, or to remove a bundle from a
-mix. View the `mixer.bundle man page`_ for a full list of commands and more
-information on configuring bundles in a mix.
+bundle to a mix, to create a new bundle for a mix, or to remove a bundle from a mix. View the `mixer.bundle man page`_ for a full list of commands and more information on configuring bundles in a mix.

 Editing an existing local bundle is as simple as opening the bundle definition
 file in your favorite editor, making the desired edits, and saving your changes.
@@ -899,187 +1021,57 @@ file in your favorite editor, making the desired edits, and saving your changes.

 .. rst-class:: content-collapse

-Configure and enable Docker
-===========================
-
-Use these steps to enable Docker for the mixer tool. Make sure to
-`Configure Docker proxy info`_ first if needed.
-
-#. Start the Docker daemon:
-
-   .. code-block:: bash
-
-      sudo systemctl start docker
-      sudo chmod 777 /var/run/docker.sock
-      sudo docker info
-
-#. Add user to the docker group
-
-   .. code-block:: bash
-
-      sudo usermod -G docker -a <username>
-
-Pull Docker container manually (optional)
-----------------------------------------
-
-By default, mixer automatically pulls a Docker container for mixing if one
-does not already exist. If you need to troubleshoot the mixer container, it
-may be useful to manually pull a mixer Docker container.
-
-Versions of the mixer Docker container are available under the tags for the
-`clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
-on Docker Hub. Each version of the mixer Docker container is named after the
-associated |CL| upstream format version. Refer to `Format version`_ for
-additional information on upstream format versions.
-
-Use the following steps to manually pull a mixer Docker container:
-
-#. Find the version of the container you need by viewing the tags for the
-   `clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
-   on Docker Hub.
-
-#. Pull the latest container version:
-
-   .. code-block:: bash
-
-      docker pull clearlinux/mixer:<upstream-format-version>
-
-#. View local docker images:
-
-   .. code-block:: bash
-
-      docker images
-
-.. rst-class:: content-collapse
-
-Configure Docker proxy info
-===========================
-
-If needed, use these steps to configure the Docker proxy information.
-
-#. Create the Docker daemon proxy config directory:
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/systemd/system/docker.service.d
-
-#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and
-   add the following using your own proxy values:
-
-   .. code-block:: console
-
-      [Service]
-      Environment="HTTP_PROXY=<HTTP proxy URL>:<port number>"
-      Environment="HTTPS_PROXY=<HTTPS proxy URL>:<port number>"
-
-#. Reload the Docker daemon:
-
-   .. code-block:: bash
-
-      sudo systemctl daemon-reload
-
-Configure the Docker container proxies, to pass proxy settings to
-containers:
-
-#. Create a directory for your container config:
-
-   .. code-block:: bash
-
-      mkdir ~/.docker
-
-#. Create the config file :file:`~/.docker/config.json` and add the following
-   entries, using your own proxy values:
-
-   .. code-block:: console
-
-      {
-        "proxies":
-        {
-          "default":
-          {
-            "httpProxy": "<proxy-url>:<port>",
-            "httpsProxy": "<proxy-url>:<port>"
-          }
-        }
-      }
-
-#. Set ownership and permission on the docker config directory:
-
-   .. code-block:: bash
-
-      sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
-      sudo chmod g+rwx "$HOME/.docker" -R
-
-Configure proxies to allow mixer to access upstream content from behind
-a firewall.
-
-#. Open your :file:`$HOME/.bashrc` file and add proxy and port values for the
-   following:
-
-   .. code-block:: console
-
-      export http_proxy="<proxy-url>:<port>"
-      export https_proxy="<proxy-url>:<port>"
-      export HTTP_PROXY="<proxy-url>:<port>"
-      export HTTPS_PROXY="<proxy-url>:<port>"
-      export no_proxy="<...>"
-
-#. Log out and log back in for the proxies to take effect.
-
-.. rst-class:: content-collapse
+.. _set-up-nginx-web-server-start:

 Set up a nginx web server for mixer
 ===================================

-A web server is needed to host your update content. In this example, we use
-the nginx web server, which comes with |CL|.
+A web server is needed to host your update content. In this example, 
+the nginx web server is used.

-Set up a nginx web server for mixer with the following steps:
-
-#. Install the :command:`nginx` bundle:
+#. Install the :command:`nginx` bundle.

   .. code-block:: bash

      sudo swupd bundle-add nginx

-#. Make the directory where mixer updates will reside:
+#. Create a symbolic link to the mixer update content directory. 

   .. code-block:: bash

      sudo mkdir -p /var/www

-#. Create a symbolic link between your workspace updates and the updates on
-   the local nginx web server. In this example, `$HOME/mixer` is the
-   workspace for the mix.
-
-   .. code-block:: bash
-
      sudo ln -sf $HOME/mixer/update/www /var/www/mixer

-#. Set up ``nginx`` configuration:
+#. Set up nginx configuration files.

   .. code-block:: bash

      sudo mkdir -p  /etc/nginx/conf.d

-#. Copy the default example configuration file:
+      sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
+
+#. Grant ``$USER`` permission to run the web server.

   .. code-block:: bash

-      sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
+      sudo tee -a /etc/nginx/nginx.conf << EOF
+      user $USER;
+      EOF

-#. Configure the mixer update server. Create and add the following server
-   configuration content to :file:`/etc/nginx/conf.d/mixer.conf` (sudo required):
+#. Configure the mixer update server. 

-   .. code-block:: console
+   .. code-block:: bash

+      sudo tee -a /etc/nginx/conf.d/mixer-server.conf << EOF
      server {
-           server_name localhost;
-           location / {
-                     root /var/www/mixer;
-                     autoindex on;
-           }
+        server_name localhost;
+        location / {
+          root /var/www/mixer;
+          autoindex on;
+        }
      }
+      EOF

 #. Restart the daemon, enable nginx on boot, and start the service.

@@ -1087,13 +1079,13 @@ Set up a nginx web server for mixer with the following steps:

      sudo systemctl daemon-reload

-      sudo systemctl enable nginx
+      sudo systemctl enable nginx --now

-      sudo systemctl start nginx
+#. Verify the web server is running at \http://<IP-address-of-web-server>.
+   If there's no mix content yet, the expected response from nginx will be 
+   a ``404 Not Found``.

-#. Verify the web server is running at \http://<ip-address>,
-   where <ip-address> is the same one that you captured in
-   `Example 1: Mix set up`_.
+.. _set-up-nginx-web-server-end:

 Related topics
 **************
@@ -1101,13 +1093,15 @@ Related topics
 * :ref:`autospec`
 * :ref:`bundles-guide`
 * :ref:`swupd-guide`
+* :ref:`swupd-3rd-party`

-.. _Docker Hub: https://hub.docker.com/r/clearlinux/mixer/tags/
 .. _mixer man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.1.rst
 .. _mixer.init man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.init.1.rst
 .. _mixer.bundle man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.bundle.1.rst
 .. _mixer.build man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.build.1.rst
 .. _releases: https://github.com/clearlinux/clr-bundles/releases
 .. _afb.sh reference script: https://github.com/clearlinux/mixer-tools/blob/master/afb.sh
+.. _clr-installer: https://github.com/clearlinux/clr-installer
+.. _Installer YAML Syntax:
+   https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md

-.. _ister: https://github.com/bryteise/ister
@@ -4,7 +4,7 @@ Stateless
 #########

 In most operating systems, user data, system data, and configuration files
-can become intermingled.
+can become intermingled, which can make them challenging to manage.

 .. figure:: figures/stateless-1.png
   :scale: 45%
@@ -24,7 +24,7 @@ ephemeral or non-persistent.
 File-level separation
 *********************

-To accomplish a stateless design the Linux Filesystem Hierarchy is separated
+To accomplish a stateless design, the |CL| filesystem hierarchy is separated
 between user-owned areas and |CL|-owned areas.

 .. figure:: figures/stateless-2.png
@@ -63,16 +63,17 @@ Default configurations
 ======================

 Software in |CL| provides default configuration values so that it is
-immediately functional, whenever it is appropriate to do so.
+immediately functional, except for some that require additional configuration.

-|CL| distributed software packages may be directly modified to include default
-configuration values or default configuration files may be provided by |CL|
-under :file:`/usr/share/defaults`. These files can be referenced as templates
-for customization.
-
-For example, the default configuration that Apache uses when installed can be
-found at :file:`/usr/share/defaults/httpd/httpd.conf` directory.
+If an upstream software puts default configurations in multiple locations 
+such as :file:`/usr/` and :file:`/etc`, it will be modified by the |CL| 
+distro to comply with the stateless design.  Also, some default configurations 
+may be modified to close security loopholes.  Defaults will reside 
+under :file:`/usr/share/defaults`.  These files can be referenced as 
+templates for customization.

+For example, after installing the `httpd` bundle for Apache web server, its 
+default configurations appear in the :file:`/usr/share/defaults/httpd/` directory.

 Overriding configurations
 =========================
@@ -81,30 +82,36 @@ If a configuration needs to be changed, the appropriate file should be
 modified by the user under :file:`/etc/`. If the configuration file does not
 already exist, it can be created in the appropriate location.

-User defined configuration files should contain the minimal set of desired
+User-defined configuration files should contain the minimal set of desired
 changes and rely on default configuration for the rest.

 For example, a customized Apache configuration can be used instead by:

-#. Create the destination directory for the configuration:
+#. Install the Apache web server bundle.
+
+   .. code-block:: bash
+
+      sudo swupd bundle-add httpd
+
+#. Create the destination directory for the configuration.

   .. code-block:: bash

      sudo mkdir /etc/httpd

-#. Copy the default configuration as a reference template:
+#. Copy the default configuration as a reference template.

   .. code-block:: bash

      sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/

-#. Make any desired modifications to the configurations:
+#. Make any desired modifications to the configurations.

   .. code-block:: bash

      sudoedit /etc/httpd/httpd.conf

-#. Reload the service or reboot the system to pickup any changes:
+#. Reload the service or reboot the system to pickup any changes.

   .. code-block:: bash

@@ -116,7 +123,7 @@ The `stateless man page`_ has application-specific examples.
 System reset
 ************

-Once advantage of the stateless design is that the system defaults can be
+One advantage of the stateless design is that the system defaults can be
 easily restored by simply deleting everything under :file:`/etc/` and
 :file:`/var`.

@@ -128,8 +135,8 @@ just installed:
   sudo rm -rf /etc
   sudo rm -rf /var

-In other Linux distributions, this can be a catastrophic action that renders
-a system unable to boot.
+In other Linux distributions, this can be a catastrophic action that may render
+a system unable to boot and/or inaccessible.

 Additional information
 **********************
@@ -0,0 +1,273 @@
+.. _swupd-3rd-party:
+
+swupd 3rd-party 
+###############
+
+Upstream |CL| offers a plethora of `bundles`_ to choose from.  
+
+For users who want access to additional software outside of the distro, 
+|CL| provides support for 3rd-party bundles.  
+
+There are two components to 3rd-party bundles:
+
+* Use :command:`mixer` to create 3rd-party bundles
+
+* Use the :command:`swupd` subcommand :command:`3rd-party` to manage repos, 
+  consume and manage bundles
+
+Follow this guide to set up a web server to host 3rd-party bundles, 
+build an example 3rd-party bundle, install and manage the bundle on a 
+client system. 
+
+.. contents::
+   :local:
+   :depth: 1
+
+Prerequisite
+*************
+
+* Familiarity with :command:`mixer`
+* Familiarity with :command:`swupd`
+* You must be running |CL| version 32570 or higher
+
+.. include:: ./mixer.rst
+   :start-after: set-up-nginx-web-server-start:
+   :end-before: set-up-nginx-web-server-end:
+
+Create directory to hold 3rd-party app
+**************************************
+
+#. Create a top-level directory to hold all apps.
+	
+   .. code-block:: bash
+      
+      mkdir ~/my-3rd-party-apps && pushd $_
+
+#. Create a directory for each app and put the content of your software in it.  
+
+   In this example, the `helloclear.sh` app simply prints
+   "Hello Clear!" when invoked.  
+
+   .. code-block:: bash
+
+      # make helloclear directory
+      mkdir -p helloclear/usr/bin && pushd $_
+
+      # create helloclear.sh script
+      cat > helloclear.sh << EOF
+      #!/bin/bash
+      echo "Hello Clear!"
+      EOF
+
+      # make script executable
+      chmod +x helloclear.sh
+
+      popd
+
+   .. note:: 
+      
+      * You can put whatever you want in your app's directory. All of the content 
+        within each directory will get copied onto the client system under 
+        :file:`/opt/3rd-party/bundles/<repo-name>/`.
+
+      * To use a 3rd-party RPM, it is recommended to extract the content of the RPM 
+        into a directory.  Use :command:`rpm2cpio <RPM>| sudo cpio -idv`.
+       
+Create bundle of 3rd-party app with mixer
+*****************************************
+
+Next, use :command:`mixer` to create a bundle for each of the apps from the previous 
+section.  
+
+#. Install the mixer tool.
+   
+   .. code-block:: bash
+
+      sudo swupd bundle-add mixer
+
+#. Create a mixer workspace.
+   
+   .. code-block:: bash
+
+      mkdir ~/mixer && cd $_
+
+#. Initialize a mix without any default bundles.
+   
+   .. code-block:: bash
+
+      mixer init --no-default-bundles
+
+#. Configure :file:`builder.conf` to set the default bundle, CONTENTURL, and VERSIONURL.  
+   For the "URL"s in this example, it will be IP address of the web server that was
+   set up earlier.
+   Substitute <IP-address-of-web-server> with the IP address of your host.  
+
+   .. code-block:: bash
+      
+      mixer config set Swupd.BUNDLE "os-core"
+      mixer config set Swupd.CONTENTURL "http://<IP-address-of-web-server>"
+      mixer config set Swupd.VERSIONURL "http://<IP-address-of-web-server>"
+
+#. Create an empty local `os-core` bundle.  :command:`swupd` client expects the 
+   `os-core` bundle to exist in a mix even if it’s empty.
+
+   .. code-block:: bash
+      
+      mixer bundle create os-core --local
+
+#. Using the `helloclear` app as an example, create the `helloclear` bundle  
+   and use the `content()` directive with the path to the `helloclear` directory in
+   the bundle definition.
+
+   Refer to `bundle definition`_ for addition information on how to define a bundle.
+
+   .. code-block:: bash
+      
+      mixer bundle create helloclear --local
+      echo "content($HOME/my-3rd-party-apps/helloclear/)" >> local-bundles/helloclear
+
+#. Add both bundles to the mix.
+
+   .. code-block:: bash
+      
+      mixer bundle add os-core
+      mixer bundle add helloclear
+
+#. Build the bundles and generate the update content.
+
+   .. code-block:: bash
+      
+      sudo mixer build bundles
+      sudo mixer build update
+
+Install and manage 3rd-party bundle on client system
+****************************************************
+
+Finally, use the :command:`swupd` client tool to install and 
+manage the bundle created with :command:`mixer` earlier.
+All installed 3rd-party bundles reside in :file:`/opt/3rd-party/bundles/<repo-name>/`.
+
+#. First, add a repo link to the web server.
+   The `os-core` bundle will be added automatically when adding a repo.  
+   It contains items that mixer injected into the mix such as version information, 
+   format, CONTENTURL, VERSIONURL, and certificate.
+    
+   .. code-block:: bash
+
+      sudo swupd 3rd-party add my-3rd-party-repo \
+      http://<IP-address-of-web-server> --allow-insecure-http
+
+   .. note::
+      
+      By default, the :command:`swupd` client is designed to communicate 
+      with an HTTPS server. For development purposes, the swupd client 
+      can talk to an HTTP server if you add the flag ``--allow-insecure-http``.
+
+      To avoid adding this flag each time when invoking :command:`swupd`, enter:
+
+      .. code-block:: bash
+
+         sudo mkdir -p /etc/swupd
+
+         sudo tee -a /etc/swupd/config << EOF
+         [GLOBAL]
+         allow-insecure-http=true
+         EOF
+
+#. Query the list of bundles from the repo.
+   
+   .. code-block:: bash
+
+      sudo swupd 3rd-party bundle-list -a 
+
+#. Add the `helloclear` bundle.
+   
+   .. code-block:: bash
+
+      sudo swupd 3rd-party bundle-add helloclear
+
+#. List installed 3rd-party bundles.
+
+   .. code-block:: bash
+
+      sudo swupd 3rd-party bundle-list
+
+#. Look in :file:`/opt/3rd-party` to confirm they were installed there.  
+   
+   .. code-block:: bash
+
+      tree /opt/3rd-party
+
+   Example out:
+   
+   .. code-block:: console
+
+      /opt/3rd-party/
+      ├── bin
+      │   └── helloclear.sh
+      ├── bundles
+      │   └── my-3rd-party-repo
+      │       └── usr
+      │           ├── bin
+      │           │   └── helloclear.sh
+      │           ├── lib
+      │           │   └── os-release
+      │           └── share
+      │               ├── clear
+      │               │   ├── bundles
+      │               │   │   ├── helloclear
+      │               │   │   └── os-core
+      │               │   ├── update-ca
+      │               │   │   └── Swupd_Root.pem
+      │               │   ├── version
+      │               │   └── versionstamp
+      │               └── defaults
+      │                   └── swupd
+      │                       ├── contenturl
+      │                       ├── format
+      │                       └── versionurl
+      └── repo.ini
+
+      12 directories, 12 files
+
+Create more bundles and add to client
+*************************************
+
+From here on, to add new bundles to your mix, follow these steps:
+
+#. Follow the steps above to add a new directory for each app and put content into it.
+
+#. In the mixer workspace, run :command:`mixer versions update`.
+
+#. Follow the remaining mixer process to add and build bundles.  
+
+On the client side:
+
+#. Run :command:`sudo swupd 3rd-party update` to update to the latest version of your mix.
+
+#. Now, you can see and add the new bundles.
+
+Some limitations of 3rd-party bundles
+*************************************
+
+#. You cannot upload your bundles to a shared community repo because bundles
+   are tied to your particular mix with its own certificate. 
+   You have to host your own and share your repo.
+
+#. As with upstream bundles, 3rd-party bundles installation is simply the unpacking 
+   of files onto your system.  It cannot perform pre or post-installation actions such as 
+   adding a favorite shortcut to the Gnome desktop dock, for example.
+
+Related topics
+**************
+
+* :ref:`autospec`
+* :ref:`mixer`
+* :ref:`bundles`
+* :ref:`swupd-guide`
+
+.. _bundles: 
+   https://clearlinux.org/software
+.. _bundle definition:
+   https://docs.01.org/clearlinux/latest/guides/clear/mixer.html#id16
+
--- a/Show More
+++ b/Show More