Added fix for swupd bundle-add Error

Signed-off-by: Anthony Pray anthony.s.pray@intel.com
When using the docker image you may see error
"Failed to install x of x"
ruining  "swupd clean" will fix the problems.

.github/workflows/check.yml

@@ -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
+        

.github/workflows/main.yml

@@ -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

.github/workflows/publish.yml

@@ -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

requirements.txt

@@ -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

source/FAQ/index.rst

@@ -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,8 +189,10 @@ 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
 
@@ -159,13 +208,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 +224,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>`_.
 
 |
 

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css

@@ -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 {
@@ -493,6 +496,7 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
 
 .column.featurecard {
   background: #CCE9F5;
+  width: 300px;
 }
 
 .column.verticalcard {

source/get-started/bare-metal-install-desktop.rst

@@ -84,6 +84,8 @@ Ensure a network connection exists before launching the Software application.
    intended only for exploration. Do not attempt to install applications during
    exploration.
 
+.. _install-clr-desktop-start:
+
 Launch the |CL| installer
 =========================
 
@@ -378,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
@@ -636,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.*

source/get-started/bare-metal-install-server.rst

@@ -73,6 +73,8 @@ Follow these steps to install |CL| on the target system:
 
 #. With :guilabel:`Clear Linux OS` highlighted, select :kbd:`Enter`.
 
+.. _install-clr-server-start:
+
 Launch the |CL| Installer
 *************************
 
@@ -87,7 +89,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
@@ -125,8 +127,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`
@@ -158,8 +159,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
@@ -354,7 +353,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.
 
@@ -747,6 +746,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
 ===================
 
@@ -760,11 +784,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.
 
@@ -781,15 +805,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.
 
@@ -808,36 +832,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`_.
 
@@ -870,9 +869,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.
@@ -922,7 +921,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.*
@@ -952,7 +951,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:
 

source/get-started/bootable-usb.rst

@@ -1,29 +1,17 @@
 .. _bootable-usb:
 
-Create a bootable USB drive
-###########################
+Create a bootable USB drive using Etcher\*
+##########################################
 
-Follow the instructions applicable to your system to create a bootable
-|CL-ATTR| USB drive:
-
-* :ref:`bootable-usb-linux`
-* :ref:`bootable-usb-mac`
-* :ref:`bootable-usb-windows`
+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
-
-.. _bootable-usb-linux:
-
-Create a bootable USB drive on Linux\*
-**************************************
-
-* Make sure you completed all `Prerequisites`_.
-
-* :ref:`verify-linux` on Linux.
+* Download and install the `Etcher`_ version per your operating system.
 
 Burn the |CL| image onto a USB drive
 ====================================
@@ -33,184 +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.
 
-#. Open a terminal window.
+#. Launch Etcher.
+
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_Start.PNG
+      :scale: 100%
+      :alt: Start screen
+         
+      Figure 1: Start screen
+ 
+#. Press :guilabel:`Select Image`.
 
 #. Change directory to where the image resides.
 
+#. Select the image and click :guilabel:`Open`.
+
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_ImageSelect.PNG
+      :scale: 100%
+      :alt: In Open, select the image
+         
+      Figure 2: In Open, select the image
+
 #. Plug in the USB drive.
 
-#. Identify the USB drive using the :command:`lsblk` command with these options:
-   ``-po NAME,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINT,VENDOR,MODEL``. This shows all
-   drives attached to the system, including the primary hard disk. 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.
+#. Identify the USB drive or click :guilabel:`Change` to select a 
+   different USB.
+    
+   .. note::
 
-   .. code-block:: bash
+      This shows all USB drives attached to the system.
 
-      lsblk -po NAME,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINT,VENDOR,MODEL
+   .. rst-class:: dropshadow
 
-   Example output:
+   .. figure:: /_figures/bootable-usb/balenaEtcher_DriveSlect.PNG
+      :scale: 100%
+      :alt: USB drives attached
+         
+      Figure 3: USB drives attached
 
-   .. code-block:: console
+#. Select the proper device and press :guilabel:`Continue`.
 
-      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
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_ReadyToFlash.PNG
+      :scale: 100%
+      :alt: USB Flash Device selected
+      
+      Figure 4: USB Flash Device selected
+
+#. When ready press the :guilabel:`Flash!` Button. 
+   The dialog shows :guilabel:`Flashing` while in progress.
+
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_StartingToFlash.PNG
+      :scale: 100%
+      :alt: Starting to flash
+
+      Figure 5: Starting to flash
+
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_Flashing.PNG
+      :scale: 100%
+      :alt:  Flashing, percentage complete
+      
+      Figure 6: Flashing, percentage complete
+
+#. :guilabel:`Flash complete!` shows when the process is finished.
+
+   .. rst-class:: dropshadow
+
+   .. figure:: /_figures/bootable-usb/balenaEtcher_Done.PNG
+      :scale: 100%
+      :alt: Flash Complete!
+      
+      Figure 7: Flash Complete!
 
    .. note::
 
-      Some Linux distros may automatically mount a USB drive when it is plugged in.
+      The process may take more than a few minutes. When the process completes, close BalenaEtcher.
+      
+Advanced: Linux CLI
+===================
 
-#. If the USB drive you want to use is mounted, it must be umounted before
-   burning an image onto it.  Use the :command:`umount` command followed by
-   the device identifier/partition. For example, to unmount all of the 
-   ``/dev/sdc`` partitions:
+#. Open a Terminal window.
 
-   .. code-block:: bash
+#. Change directory to where the image resides. 
 
-      sudo umount /dev/sdc*
+#. Plug in the USB drive.  
 
-#. Burn the image onto the USB drive. This example burns an image onto ``/dev/sdc``.  
-   The device name of the USB may vary.
+#. 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
 
-.. caution::
-
-   Not fully unmounting the USB drive before burning an image could cause
-   file system checksum errors in it. If this happens, burn the image again,
-   ensuring all the USB drive partitions are unmounted first.
-
-.. _bootable-usb-mac:
-
-Create a bootable USB drive on macOS\*
-**************************************
-
-* Make sure you completed all `Prerequisites`_.
-
-* :ref:`verify-mac` on macOS.
-
-Burn the |CL| image onto a USB drive
-====================================
+Eject the |CL| image USB drive
+==============================
 
 .. caution::
 
-   Burning an image formats the USB drive and destroys all pre-existing
-   content.  Back up your data before proceeding.
+   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.
 
-#. Open a Terminal window.
+#. Unmount the USB per your OS instructions. 
 
-#. Change directory to where the image resides.
-
-#. Plug in a USB drive and get its identifier:
-
-   .. code-block:: bash
-
-      diskutil list
-
-   This lists available disks and their partitions, as shown in Figure 1.
-
-   .. figure:: /_figures/bootable-usb/bootable-usb-mac-01.png
-      :scale: 100 %
-      :alt: Get USB drive identifier
-
-      Figure 1: macOS - Get USB drive identifier
-
-#. Unmount the USB drive identified in the previous step. For example, to unmount /dev/disk2. The device name of the USB may vary.
-
-   .. code-block:: bash
-
-      diskutil umountDisk /dev/disk2
-
-#. Burn the image onto the drive using the :command:`dd` command.
-   This example uses `./`, your current directory, and it shows how to burn
-   an image onto `/dev/disk2`:
-
-   .. code-block:: bash
-
-      sudo dd if=./clear-[version number]-live-[desktop | server].iso of=/dev/disk2 bs=4m
-
-   To accelerate the imaging process, add an ‘r’ before the device identifier. Example: `sudo dd if=./clear-30800-live-server.iso of=/dev/rdisk2 bs=4m`.
-
-   Press :kbd:`<CTRL>-T` to check imaging progress.
-
-#. Eject the USB drive.
-
-   .. code-block:: bash
-
-      diskutil eject /dev/disk2
-
-.. _bootable-usb-windows:
-
-Create a bootable USB drive on Windows
-**************************************
-
-* Make sure you completed all `Prerequisites`_.
-
-* :ref:`verify-windows` on Windows\* OS.
-
-Burn the |CL| image onto a USB drive
-====================================
-
-.. caution::
-
-   Burning an image formats the USB drive and destroys all pre-existing
-   content.  Back up your data before proceeding.
-
-#. Download the `Rufus`_ utility to burn the image onto a USB drive.
-   We use Rufus 3.5 for this example.
-   **Only use the latest version of Rufus**.
-
-#. Plug in the USB drive.
-
-#. Launch Rufus.
-
-#. Under `Device`, select the USB drive.
-
-#. Under `Boot selection`, click the :guilabel:`SELECT` button.
-
-   .. note::
-
-      For other image tools, verify the `Volume label` is set to :guilabel:`CLR_ISO` **Do not change the label as installer relies on it.**
-
-#. In the dialog, navigate to where the |CL| ISO image was downloaded and select it.
-
-#. Click the :guilabel:`START` button. See Figure 2.
-
-   .. figure:: /_figures/bootable-usb/bootable-usb-windows-02.png
-      :scale: 80 %
-      :alt: Rufus utility
-
-      Figure 2: Rufus utility
-
-#. When the dialogue appears, select
-   :guilabel:`Write in ISO image mode (Recommended)`. See Figure 3.
-
-   .. figure:: /_figures/bootable-usb/bootable-usb-windows-03.png
-      :scale: 80 %
-      :alt: ISOHybrid image detected
-
-      Figure 3: ISOHybrid image detected
-
-#. Click :guilabel:`OK`.
-
-#. The process make take more than a few minutes. When the process completes,
-   close Rufus.
-
-#. Select the Windows taskbar menu for USB and select
-   :guilabel:`Eject <drive name>`.
-
-.. _Rufus: https://rufus.ie/
+#. Then eject the USB. 
+   
 .. _Downloads: https://clearlinux.org/downloads
+.. _Etcher: https://www.balena.io/etcher/

source/get-started/cloud-install/qingcloud.rst

@@ -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
+      

source/get-started/containers/container-images.rst

@@ -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`

source/get-started/index.rst

@@ -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/*

source/get-started/virtual-machine-install/vmw-player.rst

@@ -3,7 +3,9 @@
 |CL-ATTR| on VMware\* Workstation Player
 ########################################
 
-This page explains how to create a new VMware Workstation Player hypervisor and use one of two images: the |CL| Desktop installer iso, or the |CL| Pre-configured VMWare image.
+This guide explains how to set up the VMware Workstation Player 15.5.1
+hypervisor and instantiate a VM instance of |CL| by installing it using 
+an ISO or using a pre-built image.
 
 .. contents::
    :local:
@@ -23,9 +25,9 @@ it, see :ref:`vmware-esxi-install-cl`.
 
 .. note::
 
-   The screenshots on this document show the Windows version of the
-   VMware Workstation 15 Player. The menus and prompts are similar to those
-   in other versions and for the Linux OS save some minor wording 
+   The screenshots in this document show the Windows version of the
+   VMware Workstation Player 15.5.1. The menus and prompts are similar to those
+   in other versions and for the Linux version, save some minor wording 
    differences.
 
 Install the VMware Workstation Player hypervisor
@@ -38,41 +40,38 @@ Install the VMware Workstation Player hypervisor
 #. `VMware Workstation Player`_ is available for Windows and Linux.
    Download your preferred version.
 
-   .. note::
-
-      By default, selecting download means you receive the latest version
-      of this application. Commands may differ based on the version.
-
 #. Install VMware Workstation Player by following the instructions
-   appropriate for your system OS:
+   appropriate for your system's OS:
 
    * On supported Linux distros:
 
-     #. Enable a GUI desktop.
+     a. Ensure your Linux distro is running a GUI desktop.
      #. Start a terminal emulator.
      #. Start the installer by issuing the command below and follow the
         guided steps.
 
         .. code-block:: console
 
-           sudo sh ./VMware-Player-[version number].x86_64.bundle
+           sudo sh ./VMware-Player-<version number>.x86_64.bundle
 
    * On Windows:
 
-     #. Start the installer.
+     a. Start the installer.
      #. Follow the setup wizard.
 
 For additional help, see the `VMware Workstation Player Documentation`_.
 
-Create and configure a new VM
-*****************************
+Create a blank VM
+*****************
 
 #. Start the ``VMware Workstation Player`` app.
 
 #. On the home screen, click :guilabel:`Create a New Virtual Machine`. See
    Figure 1.
 
-   .. figure:: /_figures/vmw-player/vmw-player-01.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-01.png
       :scale: 100%
       :alt: VMware Workstation Player - Create a new virtual machine
 
@@ -81,7 +80,9 @@ Create and configure a new VM
 
 #. Select :guilabel:`I will install the operating system later`.
 
-   .. figure:: /_figures/vmw-player/vmw-player-02.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-02.png
       :scale: 100%
       :alt: I will install the operating system later.
 
@@ -89,11 +90,13 @@ Create and configure a new VM
 
 #. Click the :guilabel:`Next` button.
 
-#. On the :guilabel:`Select a Guest Operating System`, set the
+#. On the :guilabel:`Select a Guest Operating System` window, set the
    :guilabel:`Guest operating system` setting to :guilabel:`Linux`. See
    Figure 3.
 
-   .. figure:: /_figures/vmw-player/vmw-player-03.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-03.png
       :scale: 100%
       :alt: VMware Workstation Player - Select guest operating system type
 
@@ -108,7 +111,9 @@ Create and configure a new VM
 #. On the :guilabel:`Name the Virtual Machine` screen, name the new VM. See
    Figure 4.
 
-   .. figure:: /_figures/vmw-player/vmw-player-04.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-04.png
       :scale: 100%
       :alt: VMware Workstation Player - Name virtual machine
 
@@ -117,9 +122,12 @@ Create and configure a new VM
 #. Click the :guilabel:`Next` button.
 
 #. On the :guilabel:`Specify Disk Capacity` screen, set the VM's maximum disk
-   size. See Figure 5.
+   size. If you're planning to use a pre-built image, just use the default
+   size for now. See Figure 5.
 
-   .. figure:: /_figures/vmw-player/vmw-player-05.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-05.png
       :scale: 100%
       :alt: VMware Workstation Player - Set disk capacity
 
@@ -135,15 +143,19 @@ Create and configure a new VM
 #. On the :guilabel:`Ready to Create Virtual Machine` screen, click the
    :guilabel:`Customize Hardware...` button. See Figure 6.
 
-   .. figure:: /_figures/vmw-player/vmw-player-06.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-06.png
       :scale: 100%
       :alt: VMware Workstation Player - Customize hardware
 
       Figure 6: VMware Workstation Player - Customize hardware
 
-#. Select :guilabel:`Memory` and set the size to 2GB. See Figure 7.
+#. Select :guilabel:`Memory` and set a desired value. See Figure 7.
 
-   .. figure:: /_figures/vmw-player/vmw-player-07.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-07.png
       :scale: 100%
       :alt: VMware Workstation Player - Set memory size
 
@@ -151,7 +163,7 @@ Create and configure a new VM
 
    .. note::
 
-      The |CL| installer ISO needs a minimum of 2GB of RAM.
+      The |CL| live installer ISO needs a minimum of 1GB of RAM.
       After completing installation, |CL| can run on as little as
       128MB of RAM. Thus, you can reduce the memory size if needed.
       See :ref:`system-requirements` for more details.
@@ -159,7 +171,9 @@ Create and configure a new VM
 #. Under the :guilabel:`Device` list, select :guilabel:`Processors`. See
    Figure 8.
 
-   .. figure:: /_figures/vmw-player/vmw-player-08.png
+   .. rst-class:: dropshadow
+
+   .. figure:: ../../_figures/vmw-player/vmw-player-08.png
       :scale: 100%
       :alt: VMware Workstation Player - Set virtualization engine option
 
@@ -167,10 +181,10 @@ Create and configure a new VM
       option
 
 #. Under :guilabel:`Processors` and :guilabel:`Number of processor cores`, 
-   enter 4. 
+   enter the desired number of cores. 
 
 #. Under the :guilabel:`Virtualization engine` section,
-   check :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI`.
+   check the :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI` box.
 
 #. Click the :guilabel:`Close` button.
 
@@ -179,17 +193,9 @@ Create and configure a new VM
 Enable UEFI boot support
 ************************
 
-|CL| needs UEFI support to boot. To enable UEFI:
+|CL| needs UEFI support to boot and work properly. To enable it:
 
-#. Power off the VM. click the :guilabel:`Player` menu. See Figure 9.
-
-   .. figure:: /_figures/vmw-player/vmw-player-09.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Power off virtual machine
-
-      Figure 9: VMware Workstation Player - Power off virtual machine
-
-#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`.
+#. Close the ``VMware Workstation Player`` app.
 
 #. Add the following line to the end of your VM's :file:`.vmx` file.
 
@@ -201,189 +207,198 @@ Enable UEFI boot support
 
       Depending on the OS, you can typically find the VMware VM files under:
 
-      * On Linux distros: :file:`/home/username/vmware`
-      * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines`
-
-Download the latest |CL| image
-******************************
-
-Download the appropriate image per the tab below. We also provide 
-additional information about :ref:`image-types` and instructions on how to 
-:ref:`download-verify-decompress`.
-
-Attach the appropriate image
-============================
-   
-   .. tabs::
-
-      .. tab:: |CL| Desktop 
-
-         This option provides a live-desktop iso installer. 
-
-         #. Navigate to the `downloads`_ page and download the |CL| Desktop.
-            After the download is complete, you will attach this image.
-
-         #. On the :guilabel:`VMware Workstation 15 Player`, right-click the 
-            new VM, created in `Create and configure a new VM`_. 
-
-         #. From the pop-up menu, select :guilabel:`Settings`. 
-
-         #. From :guilabel:`Virtual Machine settings`, 
-            under :guilabel:`Hardware`, select ``CD/DVD``.
-
-         #. Under :guilabel:`Connection` at right, select 
-            :guilabel:`Use ISO image file`. 
-
-         #. Click :guilabel:`Browse` and select the decompressed 
-            |CL| installer ISO. See Figure 10.
-            
-            .. figure:: /_figures/vmw-player/vmw-player-10.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Select |CL| installer ISO
-
-               Figure 10: VMware Workstation Player - Select |CL| installer
-               ISO   
-
-         #. Follow the guide :ref:`install-on-target-start` to complete the
-            installation of |CL|.
-
-         #. After the installation completes, reboot the VM. This reboot
-            restarts the |CL| installer.
-
-         #. To enable the mouse pointer so you access VMware Workstation
-            Player's menus, press :kbd:`<CTRL>` + :kbd:`<ALT>` on the keyboard.
-
-         #. To disconnect the CD/DVD to stop it from booting the |CL|
-            installer ISO again, click the :guilabel:`Player` menu. See
-            Figure below.
-
-            .. figure:: /_figures/vmw-player/vmw-player-11.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Edit CD/DVD settings
-
-               Figure 11: VMware Workstation Player - Edit CD/DVD settings
-
-         #. Go to :menuselection:`Removable Devices-->CD/DVD 
-            (IDE)-->Disconnect`.
-
-         #. Click the :guilabel:`OK` button.
-
-         #. Continue below. 
-
-      .. tab:: |CL| Pre-configured VMWare image
-
-         #. Navigate to the `downloads`_ page and select the ``VMware`` 
-            image. Look for :file:`clear-[version number]-vmware.vmdk.xz`. 
-
-         #. Move the downloaded and decompressed pre-configured |CL| VMware
-            image file :file:`clear-[version number]-basic.vmdk` to the
-            directory where your newly-created VM resides.
-
-            .. note::
-
-               Depending on the OS, you can typically find the VMware VM
-               files under:
-
-               * Linux distros :file:`/home/username/vmware`
-               * Windows :file:`C:\Users\username\Documents\Virtual Machines`
-
-         #. On the :guilabel:`VMware Workstation 15 Player`, right-click the 
-            new VM, created in `Create and configure a new VM`_. 
-
-         #. From the pop-up menu, select :guilabel:`Settings`. 
-
-         #. Under :guilabel:`Hardware` and :guilabel:`Device` list, select 
-            :guilabel:`Hard Disk (SCSI)`. See figure 12.
-
-            .. figure:: /_figures/vmw-player/vmw-player-preconf-12.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Remove hard drive
-
-               Figure 12: VMware Workstation Player - Remove hard drive
-
-         #. Click the :guilabel:`Remove` button.
-
-         #. To add a new hard disk and attach the pre-configured |CL| 
-            VMware image, click the :guilabel:`Add` button. See Figure 13.
-
-            .. figure:: /_figures/vmw-player/vmw-player-preconf-13.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Add new hard drive
-
-               Figure 13: VMware Workstation Player - Add new hard drive
-
-         #. Under the :guilabel:`Hardware types` section, select 
-            :guilabel:`Hard Disk`.
-
-         #. Click the :guilabel:`Next` button.
-
-         #. Select your preferred :guilabel:`Virtual disk type`. 
-            See figure 14.
-
-            .. figure:: /_figures/vmw-player/vmw-player-preconf-14.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Select virtual disk type
-
-            Figure 14: VMware Workstation Player - Select virtual disk type
-
-         #. Select the :guilabel:`Use an existing virtual disk` option. 
-            See figure 15.
-
-            .. figure:: /_figures/vmw-player/vmw-player-preconf-15.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Use existing virtual disk
-
-               Figure 15: VMware Workstation Player - Use existing virtual disk
-
-         #. Click the :guilabel:`Browse` button and select the
-            pre-configured |CL| VMware image file. See figure 16.
-
-            .. figure:: ../../_figures/vmw-player/vmw-player-preconf-16.png
-               :scale: 100%
-               :alt: VMware Workstation Player - Select ready-made VMware |CL|
-
-               Figure 16: VMware Workstation Player - Select ready-made VMware |CL| image file
-
-         #. Click the :guilabel:`Finish` button.
-
-            .. note::
-
-               When asked to convert the existing virtual disk to a newer format, selecting either option works.
-
-Install |CL| into the new VM
-****************************
-
-#. Select the newly-created VM and click the :guilabel:`Play virtual machine`
-   button. See Figure below.
-
-   .. figure:: /_figures/vmw-player/vmw-player-17.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Power on virtual machine
-
-      Figure 17: VMware Workstation Player - Power on virtual machine
+        * On Linux distros: :file:`/home/username/vmware`
+        * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines`
       
-Install open-vm-tools
-*********************
+Instantiate |CL| 
+****************
 
-Optional: You may want to install the `open-vm-tools` in your virtual
-machine. The Open Virtual Machine Tools (open-vm-tools) are the open source
-implementation of VMware Tools for Linux\* guest operating systems.
+If you want to install |CL| from scratch, following the instructions
+in the **Install |CL| using ISO** tab.  Otherwise, follow the 
+**Use |CL| pre-built VMware image** tab to use our pre-built image.
+ 
+.. tabs::
 
-#. Power on your |CL| virtual machine. On the 
-:guilabel:`VMware Workstation Player` home screen, select your VM. 
-See Figure 10.
+   .. tab:: Install |CL| using ISO 
 
-#. Click :guilabel:`Play virtual machine`.
+      #. Navigate to the |CL| `Downloads`_ page and download either the ``Server``
+         or ``Desktop`` ISO image.  After the download is complete, you will 
+         attach this image.
 
-#. In |CL| you can install the bundle, and enable the tools, in your VM.
+      #. Start the ``VMware Workstation Player`` app.
 
-   .. code-block:: bash
+      #. Select the VM that was created in section `Create a blank VM`_. 
+         See Figure 9.
 
-      sudo swupd bundle-add os-cloudguest-vmware
-      sudo systemctl enable --now open-vm-tools
+      #. Click :guilabel:`Edit virtual machine settings`.
 
-More information is available on the `VMWare Tools Product Documentation`_
-site.
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-09.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Edit virtual machine settings
+
+            Figure 09: VMware Workstation Player - Edit virtual machine settings
+
+      #. In the :guilabel:`Virtual Machine settings` window, 
+         under :guilabel:`Hardware`, select guilabel:`CD/DVD (IDE)`.
+         See Figure 10.
+
+      #. Under :guilabel:`Connection` at the right, select 
+         :guilabel:`Use ISO image file`. 
+
+      #. Click :guilabel:`Browse` and select the 
+         |CL| installer ISO. 
+            
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-10.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Select |CL| installer ISO
+
+            Figure 10: VMware Workstation Player - Select |CL| installer ISO   
+
+      #. Click :guilabel:`OK` to close the :guilabel:`Virtual Machine settings`
+         window.
+
+      #. Start the VM by clicking :guilabel:`Play virtual machine`.
+
+      #. Follow one of these guides to complete the installation of |CL|. 
+         
+         * *Desktop* version: :ref:`install-clr-desktop-start` 
+         * *Server* version: :ref:`install-clr-server-start` 
+
+      #. Reboot the VM after the installation completes.
+
+      #. Install the ``os-cloudguest-vmware`` bundle, the open source
+         VMware Tools for Linux\* guest operating systems, which enables
+         new features and improves general performance.
+
+         .. code-block:: bash
+
+            sudo swupd bundle-add os-cloudguest-vmware
+            sudo systemctl enable --now open-vm-tools
+
+         More information is available on the `VMWare Tools Product Documentation`_
+         site.
+
+   .. tab:: Use |CL| pre-built VMWare image
+
+      #. Navigate to the |CL| `Downloads`_ page and download the ``VMware`` 
+         image. 
+
+      #. Decompress the downloaded file and move it to the
+         directory where your newly-created VM files reside.
+
+         .. note::
+
+            Depending on the OS, you can typically find the VMware VM
+            files under:
+
+            * Linux distros :file:`/home/username/vmware`
+            * Windows :file:`C:\\Users\\username\\Documents\\Virtual Machines`
+
+      #. Start the ``VMware Workstation Player`` app.
+
+      #. Select the VM that was created in section `Create a blank VM`_. 
+         See Figure 9.
+
+      #. Click :guilabel:`Edit virtual machine settings`.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-09.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Edit virtual machine settings
+
+            Figure 9: VMware Workstation Player - Edit virtual machine settings
+
+      #. Under :guilabel:`Hardware` and :guilabel:`Device` list, select 
+         :guilabel:`Hard Disk (SCSI)`. See Figure 11.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-11.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Remove hard drive
+
+            Figure 11: VMware Workstation Player - Remove hard drive
+
+      #. Click the :guilabel:`Remove` button.
+
+      #. To add a new hard disk and attach the pre-built |CL| 
+         VMware image, click the :guilabel:`Add` button. See Figure 12.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-12.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Add new device
+
+            Figure 12: VMware Workstation Player - Add new device
+
+      #. Under the :guilabel:`Hardware types` section, select 
+         :guilabel:`Hard Disk`. See Figure 13.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-13.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Add hard drive
+
+            Figure 13: VMware Workstation Player - Add hard drive
+
+      #. Click the :guilabel:`Next` button.
+
+      #. Select your preferred :guilabel:`Virtual disk type`. 
+         See Figure 14.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-14.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Select virtual disk type
+
+         Figure 14: VMware Workstation Player - Select virtual disk type
+
+      #. Select the :guilabel:`Use an existing virtual disk` option. 
+         See Figure 15.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-15.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Use existing virtual disk
+
+            Figure 15: VMware Workstation Player - Use existing virtual disk
+
+      #. Click the :guilabel:`Browse` button and select the
+         pre-built |CL| VMware image file. See Figure 16.
+
+         .. rst-class:: dropshadow
+
+         .. figure:: ../../_figures/vmw-player/vmw-player-16.png
+            :scale: 100%
+            :alt: VMware Workstation Player - Select pre-built VMware |CL| image file
+
+            Figure 16: VMware Workstation Player - Select pre-built VMware |CL| 
+            image file
+
+      #. Click the :guilabel:`Finish` button.
+
+         .. note::
+
+            When asked to convert the existing virtual disk to a newer format, 
+            selecting either option works.
+
+      #. Click the :guilabel:`OK` button. 
+
+      #. Start the VM by clicking :guilabel:`Play virtual machine`.
+ 
+         .. note::
+
+            If you need to increase the disk size of the pre-built |CL| image, see
+            :ref:`increase-virtual-disk-size`.
 
 Related topics
 **************
@@ -400,6 +415,6 @@ For other guides on using the VMWare Player and ESXi, see:
 .. _VMware Workstation Player Documentation:
    https://docs.vmware.com/en/VMware-Workstation-Player/index.html
 
-.. _downloads: https://clearlinux.org/downloads
+.. _Downloads: https://clearlinux.org/downloads
 
 .. _VMWare Tools Product Documentation: https://docs.vmware.com/en/VMware-Tools/10.1.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html

source/guides/clear/mixer.rst

@@ -345,61 +345,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 +470,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 +488,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 +700,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,15 +710,10 @@ 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...
+.. 
+  Example: Create a mix with custom RPM
+..
+  TODO future example to show copy into local-rpms...
 
 References
 **********
@@ -1109,5 +1145,7 @@ Related topics
 .. _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

source/guides/clear/swupd.rst

@@ -318,7 +318,7 @@ swupd update <version number>
 swupd bundle-list [--all]
    Lists installed bundles.
 
-swupd bundle <search term>
+swupd search <term>
    Finds a bundle that contains your search term.
 
 swupd bundle-add <bundle name>
@@ -350,4 +350,4 @@ Related topics
 
 .. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles
 
-.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles
+.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles

source/guides/maintenance/configure-hugepages.rst

@@ -0,0 +1,74 @@
+.. _enable-huge-pages:
+
+Configure Huge Pages
+########################
+
+In |CL| hugepages are enabled by default. The default hugepage size is 2MB. 
+The total number of hugepages is set to 0 by default. This guide shows you how
+to add hugepages to the system and how to change the default hugepage size. 
+
+#. To check the enabled state, run the following command.
+
+   .. code-block:: bash
+   
+      cat /sys/kernel/mm/transparent_hugepage/enabled
+
+   The output will look like
+ 
+   .. code-block:: console
+
+      [always] madvise never
+
+   .. note::
+      
+      The active option is enclosed in brackets. In this case, always is active, 
+      which means hugepages are enabled for every process. The `madvise` 
+      option means that hugepages are enabled for processes that explicitely 
+      call `madvise`_. 
+
+#. To check the size of hugepages, run the below command.
+
+   .. code-block:: bash
+
+      cat /proc/meminfo | grep Huge
+
+   The output should look similar to the following. Although hugepages is 
+   enabled, there are no hugepages available to allocate.
+
+   .. code-block:: console
+
+      AnonHugePages:    624640 kB
+      ShmemHugePages:        0 kB
+      FileHugePages:         0 kB
+      HugePages_Total:       0
+      HugePages_Free:        0
+      HugePages_Rsvd:        0
+      HugePages_Surp:        0
+      Hugepagesize:       2048 kB
+      Hugetlb:               0 kB
+
+#. If you need 1GB (1,048,576 bytes) of hugepages enabled, then `HugePages_Total`
+   should be set to 512. Enable it temporarily using the following.
+
+   .. code-block:: bash
+
+      echo 512 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+   To view the change, run the command in the previous setp again.
+
+#. Changing hugepages from the default 2MB to 1GB must be done at system boot
+   through kernel boot parameters. In this example, we configure the size and 
+   number of allocatable huge pages at boot.
+
+   .. code-block:: bash
+    
+      sudo mkdir -p /etc/kernel/cmdline.d
+      cat << EOF | sudo tee -a /etc/kernel/cmdline.d/hugepages.conf
+      default_hugepagesz=1G
+      hugepagesz=1G
+      hugepages=10
+      EOF
+      sudo clr-boot-manager update
+      sudo reboot
+
+   .. _madvise: https://linux.die.net/man/2/madvise

source/guides/maintenance/cpu-performance.rst

@@ -13,12 +13,12 @@ Overview
 ********
 
 Modern x86 :abbr:`CPUs (central processing units)` employ a number of features
-and technologies to balance performance, energy, and thermal efficiencies.
+to balance performance, energy, and thermal efficiency.
 
-By default, |CL| prioritizes maximum CPU performance with the philosophy that
+By default, |CL| prioritizes maximum CPU performance, assuming that
 the faster the program finishes execution, the faster the CPU can return to a
-low energy idle state. It is important to understand and evaluate all of these
-technologies when troubleshooting or considering changing the defaults.
+low energy idle state. It is important to understand and evaluate the impact
+of each feature when troubleshooting or considering changing the defaults.
 
 .. contents::
    :local:
@@ -29,26 +29,22 @@ CPU power saving mechanisms
 
 C-states and P-states are both CPU power saving mechanisms that are entered
 under different operating conditions. The tradeoff is a slightly longer time
-to exit these states when the CPU is needed once again.
+to exit these states when the CPU is needed.
 
 .. _c-states-section:
 
 C-states (idle states)
 ======================
 
-C-states are hardware sleep states that are entered when it is determined that
-the CPU is idle and not executing instructions.
+Hardware enters a C-state when the CPU is idle and not executing instructions.
+C-states decrease power utilization by reducing clock frequency,
+voltages, and features in each state. Although C-states can typically be
+limited or disabled in a system's UEFI or BIOS configuration, these settings
+are overridden when the `intel_idle driver`_ is in use.
 
-C-states aim to reduce power utilization by increasingly reducing clock
-frequency, voltages, and features in each state.
+To view the current ``cpuidle`` driver run this command in a terminal:
 
-Although C-states can typically be limited or disabled in a system's UEFI or
-BIOS configuration, these settings are overridden when the `intel_idle driver`_
-is in use.
-
-To view the current cpuidle driver run this command in a terminal:
-
-.. code:: bash
+.. code-block:: bash
 
    cat /sys/devices/system/cpu/cpuidle/current_driver
 
@@ -58,95 +54,87 @@ or completely disabled with :command:`idle=poll`.
 
 .. note::
 
-   * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1`
-     by the kernel to be a valid value.
+   *  :command:`processor.max_cstate=0` is changed to a valid value by the
+      kernel: :command:`processor.max_cstate=1`.
 
-   * :command:`intel_idle.max_cstate=0` disables the Intel Idle driver, not set
-     it to C-state 0.
+   *  :command:`intel_idle.max_cstate=0` disables the Intel Idle driver rather
+      than set it to C-state 0.
 
 .. _p-states-section:
 
 P-states (performance states)
 =============================
 
-P-states, also known as *Intel SpeedStep® technology* on Intel processors or
-*Cool'n'Quiet* on AMD processors, are states entered while the CPU is active and
-executing instructions.
-
-P-states aim to reduce power utilization by adjusting CPU clock frequency and
-voltages based on CPU demand.
-
-P-states can typically be limited or disabled in a system's firmware (UEFI/BIOS).
+The CPU can enter a P-state, also known as Intel SpeedStep® technology on
+Intel processors or AMD\* Cool'n'Quiet\* technology, while it is active
+and executing instructions. P-states reduce power utilization by adjusting CPU
+clock frequency and voltages based on CPU demand. P-states can typically be
+limited or disabled in a system's firmware (UEFI/BIOS).
 
 Turbo boost
 -----------
 
-`Intel® Turbo Boost Technology`_, found on some modern Intel CPUs, allows core(s) on
-a processor to temporarily operate at a higher than rated CPU clock frequency
-to accommodate demanding workloads if the CPU is under defined power and
-thermal thresholds.
+`Intel® Turbo Boost Technology`_, found on some modern Intel CPUs, allows
+cores on a processor to temporarily operate at a higher than rated CPU clock
+frequency to accommodate demanding workloads if the CPU is under defined power
+and thermal thresholds. Intel Turbo Boost Technology is an extension of
+P-states, so it can be impacted by limiting C-states or P-states.
 
-Turbo boost is an extension of P-states. As such, changing or limiting
-C-states or P-states impact the ability of a process to enter Turbo boost.
+Intel Turbo Boost Technology can be disabled in a system's UEFI/BIOS or in
+|CL|:
 
-Turbo boost can be disabled in a system's UEFI or BIOS. Turbo boost can also
-be disabled within |CL| with the command:
-
-.. code:: bash
+.. code-block:: bash
 
    echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo
 
 Linux CPU clock frequency scaling
 *********************************
 
-The CPUFreq subsystem in Linux allows the OS to control :ref:`C-states
-<c-states-section>` and :ref:`P-states <P-states-section>`
+The ``CPUFreq`` subsystem in Linux allows the OS to control
+:ref:`C-states <c-states-section>` and :ref:`P-states <P-states-section>`
 via CPU drivers and governors that provide algorithms that define how and when
 to enter these states.
 
 Scaling driver
 ==============
 
-Linux uses the `Intel P-state driver`_, :command:`intel_pstate`, for modern Intel
-processors from the Sandy Bridge generation or newer. Other processors may
-default to the :command:`acpi-cpufreq*` driver which reads values from the systems
-UEFI or BIOS.
+Linux uses the `Intel P-state driver`_, :command:`intel_pstate`, for
+modern Intel processors from the Sandy Bridge generation or newer. Other
+processors may default to the :command:`acpi-cpufreq` driver which reads
+values from the systems UEFI or BIOS.
 
-To view the current CPU frequency scaling driver run this command in a terminal:
+To view the current CPU frequency scaling driver, run this command in a
+terminal:
 
-.. code:: bash
+.. code-block:: bash
 
    cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_driver
 
 Scaling governor
 ================
 
-|CL| sets the CPU governor to *performance* which calls for the CPU to operate
-at maximum clock frequency. In other words, P-state P0. While this may sound
-wasteful at first, it is important to remember that power utilization does not
-increase significantly simply because of a locked clock frequency without a
-workload.
+|CL| sets the CPU governor to ``performance`` which calls for the CPU to
+operate at maximum clock frequency. In other words, P-state P0. While this may
+sound wasteful at first, it is important to remember that power utilization
+does not increase significantly simply because of a locked clock frequency
+without a workload.
 
-To view the current CPU frequency scaling governor run this command in a terminal:
+To view the current CPU frequency scaling governor, run this command in a
+terminal:
 
-.. code:: bash
+.. code-block:: bash
 
    cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
 
-To change the CPU frequency scaling governor:
+Each core will report its own status. Your output should look similar to this
+example with four cores:
 
-#. Disable |CL| enforcement of certain power and performance settings:
+.. code-block:: console
 
-   .. code:: bash
-
-      sudo systemctl mask clr-power.timer
-
-#. Change the governor. In the example below, the governor is set to
-   *performance*:
-
-   .. code:: bash
-
-      echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+   performance
+   performance
+   performance
+   performance
 
 The list of all governors can be found in the Linux kernel documentation on
 `CPUFreq Governors`_.
@@ -155,34 +143,49 @@ The list of all governors can be found in the Linux kernel documentation on
 
    The intel_pstate driver only supports *performance* and *powersave* governors.
 
+There are 2 ways to change the CPU frequency scaling governor:
+
+#. Disable |CL| enforcement of certain power and performance settings:
+
+   .. code-block:: bash
+
+      sudo systemctl mask clr-power.timer
+
+#. Change the governor value in :file:`/sys/devices`. In the example below,
+   the governor is set to *performance*:
+
+   .. code-block:: bash
+
+      echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+
 Thermal management
 ******************
 
-`thermald`_ is a Linux thermal management daemon used to prevent the
-overheating of platforms. When temperature thresholds are exceeded, thermald
-forces a C-state by inserting CPU sleep cycles and adjusts available cooling
-methods. This can be especially desirable for laptops.
+`thermald`_ is a Linux thermal management daemon used to prevent platforms 
+from overheating. :command:`thermald` forces a C-state by inserting CPU sleep
+cycles and adjusting any available cooling methods. This can be especially
+desirable for laptops.
 
-By default, thermald is disabled in |CL| and starts automatically if battery
-power is detected. thermald can be manually enabled using the systemd service
-by running the command:
+:command:`thermald` is disabled by default in |CL| and starts automatically
+if it detects battery power. Enable :command:`thermald` manually by using
+the systemd service by running the command:
 
-.. code:: bash
+.. code-block:: bash
 
    sudo systemctl enable --now thermald
 
-For more information, see the thermald man page:
+For more information, see the :command:`thermald` man page:
 
-.. code:: bash
+.. code-block:: bash
 
    man thermald
 
 `ThermalMonitor`_ is a GUI application that can visually graph and log
-temperatures from thermald. To use ThermalMonitor, add the
+temperatures from :command:`thermald`. To use ThermalMonitor, add the
 :command:`desktop-apps-extras` bundle and add your user account to the power
 group:
 
-.. code:: bash
+.. code-block:: bash
 
    sudo swupd bundle-add desktop-apps-extras
    sudo usermod -a -G power <USER>
@@ -197,48 +200,64 @@ Enhanced thermal configuration
 ===============================
 
 Better thermal control and performance can be achieved by providing platform
-specific configuration to thermald.
+specific configuration to :command:`thermald`.
 
-`Linux DPTF Extract Utility`_ is a companion tool to thermald, This tool can
-make use of :abbr:`Intel® Dynamic Platform and Thermal Framework (`Intel DPTF)`
-technology, and convert to the thermal_conf.xml configuration format used
-by thermald. It's a closed-source project, and unable to be packaged as bundle
-in Clear Linux OS, so we need to follow below steps to generate configuration.
+`Linux DPTF Extract Utility`_ is a companion tool to :command:`thermald`,
+This tool uses Intel® 
+:abbr:`DPTF (Dynamic Platform and Thermal Framework)` technology and
+can convert to the :file:`thermal_conf.xml` configuration format used by
+:command:`thermald`. Closed-source projects, like this one, cannot be packaged
+as a bundle in |CL|, so you must install it manually:
 
-Intel DPTF requires BIOS support, it's typically used by laptops.
-The first step is to make sure your machine's BIOS has DPTF feature
-and is enabled.
+#. Make sure your machine's BIOS has DPTF feature and is enabled. It will usually be in the :guilabel:`Advanced` or :guilabel:`Advanced>Power` section of the BIOS. 
 
-Then generate thermal configuration as below:
+   .. figure:: /_figures/cpu-perf-guide/dptf_bios.png
 
-.. code:: bash
+   .. note:: 
 
-   sudo swupd bundle-add acpica-unix2  # install acpi tools
-   git clone https://github.com/intel/dptfxtract.git
-   cd dptfxtract
-   sudo acpidump > acpi.out
-   acpixtract -a acpi.out
-   sudo ./dptfxtract *.dat
+      Intel DPTF requires BIOS support and is typically only available on
+      laptops.
 
-thermald configuration files will be generated and saved to
-:command:`/etc/thermal/` folder. Restart thermald service to take effect.
+#. Generate thermal configuration. :command:`thermald` configuration files
+   will be generated and saved to :file:`/etc/thermal/` folder. 
 
-.. code:: bash
+   .. code-block:: bash
 
-   sudo systemctl restart thermald.service
+      sudo swupd bundle-add acpica-unix2  # install acpi tools
+      git clone https://github.com/intel/dptfxtract.git
+      cd dptfxtract
+      sudo acpidump > acpi.out
+      acpixtract -a acpi.out
+      sudo ./dptfxtract *.dat
 
-check whether the configuration is in used.
+#. Restart :command:`thermald` service to take effect.
 
-.. code:: bash
+   .. code-block:: bash
 
-   sudo systemctl status thermald.service
+      sudo systemctl restart thermald.service
 
-if the output contains below line, it means configuration already applied:
+#. Check whether the configuration is in use.
 
-.. code:: bash
+   .. code-block:: bash
+
+      sudo systemctl status thermald.service
+
+The following output means the configuration has already been applied:
+
+.. code-block:: console
 
    thermald[*]: [WARN]Using generated /etc/thermald/thermal-conf.xml.auto
 
+.. admonition:: Disclaimer
+
+   Intel® Turbo Boost Technology requires a PC with a processor with Intel
+   Turbo Boost Technology capability. Intel Turbo Boost Technology performance
+   varies depending on hardware, software and overall system configuration.
+   Check with your PC manufacturer on whether your system delivers Intel Turbo
+   Boost Technology. For more information, see http://www.intel.com/technology/turboboost
+
+   Intel SpeedStep is a trademark of Intel Corporation or its subsidiaries.
+
 
 .. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt
 

source/guides/network/time.rst

@@ -45,7 +45,7 @@ the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached.
 
    .. code-block:: bash
 
-      timedatectl set-ntp true
+      sudo timedatectl set-ntp true
 
 .. note::
 

source/guides/stacks/dlrs.rst

@@ -107,6 +107,9 @@ bundle. To start Docker, enter:
 To ensure that Kubernetes is correctly installed and configured, follow the
 instructions in :ref:`kubernetes`.
 
+.. warning::
+
+   Note that although the DLRS images and dockerfiles may be modified for your needs, there are some modifications that may cause unexpected or undesirable results.  For example, using the Clear Linux :command:`swupd bundle-add` command to add packages to a Clear Linux based container may overwrite the DLRS core components.  Please use care when modifying the contents of the containers. If recaving Errors using the Clear Linux :command:`swupd bundle-add` command try running the Clear Linux :command:`swupd clean` command first.
 
 
 Kubectl
@@ -376,6 +379,143 @@ Submitting PyTorch Jobs
 
 We provide `DLRS PytorchJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the container(s) that will run training workloads in your Kubernetes cluster.
 
+Working with Horovod* and OpenMPI*
+**********************************
+
+`Horovod`_ is a distributed training framework for TensorFlow, Keras, and PyTorch. The `OpenMPI Project`_ is an open source Message Passing Interface implementation. Running Horovod on OpenMPI will let us enable distributed training on DLRS.
+
+The following deployment uses `Kubeflow OpenMPI instructions`_, meaning you can replace the following variables to have a working Kubernetes cluster with openmpi workers for distributed training.
+
+To begin, refer to the instructions above to set up a Kubernetes cluster on Clear Linux. You will need to build and push the DLRS docker image with Horovod and OpenMPI enabled, modifying the dockerfile to build your image
+
+Building the Image
+==================
+
+#. DLRS is part of the `Intel stacks GitHub repository`_.  Clone the stacks repository.
+
+   .. code-block:: bash
+
+      git clone https://github.com/intel/stacks.git
+
+#. Create the ssh-entrypoint.sh script by copying the following into a file in the stacks/dlrs/clearlinux/tensorflow/mkl directory
+
+   .. code-block:: console
+
+      #! /usr/bin/env bash
+      set -o errexit
+
+      mkdir -p /etc/ssh /var/run/sshd
+
+      # Allow OpenSSH to talk to containers without asking for confirmation
+      cat << EOF > /etc/ssh/ssh_config
+      StrictHostKeyChecking no
+      Port 2022
+      UserKnownHostsFile=/dev/null
+      PasswordAuthentication no
+      EOF
+
+      /usr/sbin/ssh-keygen -A
+
+#. Inside the stacks/dlrs/clearlinux/tensorflow/mkl directory, modify the Dockerfile.builder file to add the openssh-server to the container.
+
+    .. code-block:: console
+
+       # update os and add required bundles
+       RUN swupd bundle-add git curl wget \
+           java-basic sysadmin-basic package-utils \
+           devpkg-zlib go-basic devpkg-tbb openssh-server
+
+#. To execute the ssh-entrypoint.sh in the container, add these lines to the Dockerfile.builder file
+
+   .. code-block:: console
+
+      COPY ssh-entrypoint.sh /bin/ssh-entrypoint.sh
+      RUN chmod +x /bin/ssh-entrypoint.sh
+      RUN ssh-entrypoint.sh
+
+   .. note::
+
+     The ssh-entrypoint.sh script will generate ssh host keys for the docker image, but they will be the same every time the image is built.
+
+
+#. Build the container with
+
+   .. code-block:: bash
+
+      make
+
+   .. note::
+
+      More detail on building the container can be found on the `Intel stacks GitHub repository`_
+
+Using the new image with Horovod and OpenMPI
+============================================
+
+To use the new image we will follow the `Kubeflow OpenMPI instructions`_. You will not need to follow the Installation section, as we have just completed that for the DLRS container.
+
+#. Generate and deploy Kubeflow's openmpi component.
+
+   .. code-block:: console
+
+      Create a namespace for kubeflow deployment.
+      kubectl delete namespace kubeflow
+      NAMESPACE=kubeflow
+      kubectl create namespace ${NAMESPACE}
+
+      # Generate one-time ssh keys used by Open MPI.
+      SECRET=openmpi-secret
+      mkdir -p .tmp
+      yes | ssh-keygen -N "" -f .tmp/id_rsa -C ""
+      kubectl delete secret ${SECRET} -n ${NAMESPACE} || true
+      kubectl create secret generic ${SECRET} -n ${NAMESPACE} --from-file=id_rsa=.tmp/id_rsa --from-file=id_rsa.pub=.tmp/id_rsa.pub --from-file=authorized_keys=.tmp/id_rsa.pub
+
+      # Which version of Kubeflow to use.
+      # For a list of releases refer to:
+      # https://github.com/kubeflow/kubeflow/releases
+      VERSION=master
+
+      # Initialize a ksonnet app. Set the namespace for its default environment.
+      APP_NAME=openmpi
+      ks init ${APP_NAME}
+      cd ${APP_NAME}
+      ks env set default --namespace ${NAMESPACE}
+
+      # Install Kubeflow components.
+      ks registry add kubeflow github.com/kubeflow/kubeflow/tree/${VERSION}/kubeflow
+      ks pkg install kubeflow/openmpi@${VERSION}
+
+      # See the list of supported parameters.
+
+      # Generate openmpi components.
+      COMPONENT=openmpi
+      IMAGE=<image name>
+
+#. Run openmpi workers in containers
+
+   .. code-block:: console
+
+      WORKERS=<set number of workers>
+      MEMORY=<memory>
+      GPU=0
+
+      # We should create a hostfile with the names of each node in the k8s cluster
+      EXEC="mpiexec --allow-run-as-root -np ${WORKERS} --hostfile /kubeflow/openmpi/assets/hostfile -bind-to none -map-by slot sh -c 'python <path_to_benchmarks_scripts> --device=cpu --data_format=NHWC --model=alexnet --variable_update=horovod --horovod_device=cpu'"
+
+      ks generate openmpi ${COMPONENT} --image ${IMAGE} --secret ${SECRET} --workers ${WORKERS} --gpu ${GPU} --exec "${EXEC}" --memory "${MEMORY}"
+
+      # Deploy to your cluster.
+      ks apply default
+      WORKERS=<set number of workers>
+      MEMORY=<memory>
+      GPU=0
+
+      # We should create a hostfile with the names of each node in the k8s cluster
+      EXEC="mpiexec --allow-run-as-root -np ${WORKERS} --hostfile /kubeflow/openmpi/assets/hostfile -bind-to none -map-by slot sh -c 'python <path_to_benchmarks_scripts> --device=cpu --data_format=NHWC --model=alexnet --variable_update=horovod --horovod_device=cpu'"
+
+      ks generate openmpi ${COMPONENT} --image ${IMAGE} --secret ${SECRET} --workers ${WORKERS} --gpu ${GPU} --exec "${EXEC}" --memory "${MEMORY}"
+
+      # Deploy to your cluster.
+      ks apply default
 
 
 
@@ -955,3 +1095,11 @@ Related topics
 .. _Source to Image (s2i): https://docs.seldon.io/projects/seldon-core/en/latest/wrappers/s2i.html
 
 .. _Deep Learning Reference Stack website: https://clearlinux.org/stacks/deep-learning
+
+.. _Horovod: https://github.com/horovod/horovod
+
+.. _OpenMPI Project: https://www.open-mpi.org
+
+.. _Kubeflow OpenMPI instructions: https://github.com/kubeflow/mpi-operator/blob/master/README.md
+
+.. _Intel stacks GitHub repository: https://github.com/intel/stacks.git

source/tutorials/kata.rst

@@ -27,7 +27,7 @@ the :ref:`bare metal installation tutorial<bare-metal-install-desktop>`.
 If you have Clear Containers installed on your |CL| system, then follow the
 :ref:`migrate Clear Containers to Kata Containers tutorial<kata_migration>`.
 
-Before you install any new packages, update |CL| with the following command:
+Update |CL| with the following command:
 
 .. code-block:: bash
 
@@ -37,89 +37,98 @@ Install Kata Containers
 ***********************
 
 Kata Containers is included in the :file:`containers-virt` bundle.
-To install the framework, enter the following command:
+To install the framework:
 
-.. code-block:: bash
+#. Install the containers-virt bundle:
 
-   sudo swupd bundle-add containers-virt
+   .. code-block:: bash
 
-Restart the Docker\* and Kata Containers systemd services.
+      sudo swupd bundle-add containers-virt
 
-.. code-block:: bash
+#. Reload and restart the Docker\* systemd service.
 
-   sudo systemctl daemon-reload
-   sudo systemctl restart docker
+   .. code-block:: bash
+
+      sudo systemctl daemon-reload
+      sudo systemctl restart docker
 
 Run Kata Containers
 *******************
 
+To use kata as the runtime for an individual container, add
+:command:`--runtime=kata-runtime` to the :command:`docker run` command. For
+example:
+
 .. code-block:: bash
 
-   sudo docker run -ti busybox sh
+   sudo docker run --runtime=kata-runtime -ti busybox sh
 
-.. note::
 
-   If you use a proxy server and your proxy environment variables are already
-   set, run the following commands as a shell script to configure Docker:
+To use kata as the default runtime for all Docker containers:
+
+#. Set the default runtime for the Docker daemon:
+
+   .. note:: 
+
+      The method below uses a systemd drop-in configuration to add a
+      command-line (CLI) parameter to the Docker daemon for setting the
+      *default-runtime*. Alternatively, the default runtime can be set in the
+      `Docker daemon configuration file
+      <https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file>`_.
+      The Docker daemon will not start if the *default-runtime* configuration
+      in set multiple locations.
 
    .. code-block:: bash
 
-      docker_service_dir="/etc/systemd/system/docker.service.d/"
-      sudo mkdir -p "$docker_service_dir"
-      cat <<EOF | sudo tee "$docker_service_dir/proxy.conf"
+      sudo mkdir -p /etc/systemd/system/docker.service.d/
+
+      cat <<EOF | sudo tee /etc/systemd/system/docker.service.d/50-runtime.conf
       [Service]
-      Environment="HTTP_PROXY=$http_proxy"
-      Environment="HTTPS_PROXY=$https_proxy"
+      Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime kata-runtime"
       EOF
-      echo "Reloading unit files and starting docker service"
+
+#. Reload and restart the Docker\* systemd service.
+
+   .. code-block:: bash
+
       sudo systemctl daemon-reload
       sudo systemctl restart docker
-      sudo docker info
 
-**Congratulations!**
+#. Verify the default runtime reported by docker is **kata-runtime**.
 
-You've successfully installed and set up Kata Containers on |CL|.
+   .. code-block:: bash
 
-More information about Docker
-*****************************
+      sudo docker info | grep "Default Runtime"
+         Default Runtime: kata-runtime
 
-Docker on |CL| provides a :file:`docker.service` file to start the Docker
-daemon. The daemon will use runc or kata-runtime depending on the
-environment:
-
-*  If you are running |CL| on bare metal or on a VM with Nested
-   Virtualization activated, Docker uses kata-runtime as the
-   default runtime.
-*  If you are running |CL| on a VM without Nested Virtualization,
-   Docker uses runc as the default runtime.
-
-You do not need to manually configure the runtime for Docker, because
-it automatically uses the runtime supported by the system.
 
 Troubleshooting
 ===============
 
+- If you are behind a HTTP proxy server, in a corporate setting for
+  example, please refer to the `Docker proxy instructions`_.
+
 - To change the Docker storage driver, see
   :ref:`additional-docker-configuration`.
 
-- For some |CL| versions before 27000, you may need to manually
-  configure Docker\* to use Kata Containers by default.
+- To check the version of |CL| on your system, enter: :command:`sudo swupd
+  info`.
 
-  To do so, enter:
+- |CL| versions before 27000 require manually configure Docker\* to use Kata
+  Containers as shown in this tutorial.
+
+- |CL| versions between 27000 and 31930 had a mechanism to automatically set
+  kata as the default runtime for docker. To disable this mechanism run the
+  commands below:
 
   .. code-block:: bash
-
-     sudo mkdir -p /etc/systemd/system/docker.service.d/
-     cat <<EOF | sudo tee /etc/systemd/system/docker.service.d/50-runtime.conf
-     [Service]
-     Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime kata-runtime"
-     EOF
-
-- To check the version of |CL| on your system, enter:
-
-  .. code-block:: bash
-
-     sudo swupd info
+     
+     sudo systemctl mask docker-set-runtime.service
+     sudo rm /etc/systemd/system/docker.service.d/50-runtime.conf
+     sudo systemctl daemon-reload
+     sudo systemctl restart docker.service
 
 
 .. _Kata Containers: https://katacontainers.io/
+
+.. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy

source/tutorials/multi-boot/dual-boot-win.rst

@@ -35,11 +35,9 @@ For this method, we shrink the Windows 10 OS partition to make space for |CL|.
 
 #. Shrink the size of the partition by at least the following amount:
 
-   * For :ref:`installing the live desktop <bare-metal-install-desktop>`,
-     allow at least 21GB.
+   * For *Desktop* version, allow at least 21GB.
 
-   * For :ref:`installing the live server <bare-metal-install-server>`,
-     allow at least 4GB.
+   * For *Server* version, allow at least 4GB.
 
 
 #. We shrink C by about 21GB, as shown in Figure 2.
@@ -54,20 +52,19 @@ For this method, we shrink the Windows 10 OS partition to make space for |CL|.
 
 #. Shutdown the Windows 10 OS.
 
-#. Follow the instructions to :ref:`bare-metal-install-desktop`.
+#. Follow one of these guides to install |CL|:
 
-#. After booting from the |CL| image, select the icon to
-   launch the installer.
+   * *Desktop* version: :ref:`bare-metal-install-desktop`
+   * *Server* version: :ref:`bare-metal-install-server`
 
-#. Click :guilabel:`Select Installation Media`.
+   a. In the :guilabel:`Required options` tab, choose :guilabel:`Select
+      Installation Media`.
 
-#. Select :guilabel:`Safe Installation`.
+   #. Within that menu, select :guilabel:`Safe Installation`.
 
-#. Go through the remaining steps to install |CL|.
+   #. Go through remaining steps to complete the installation.
 
-#. Shut down your system and remove the USB.
-
-#. Reboot.
+   #. Reboot.
 
 #. During the BIOS POST stage, press :kbd:`F10`, or the proper F-key for your
    system, to launch the :guilabel:`Boot Menu`.
@@ -92,8 +89,8 @@ For this method, we shrink the Windows 10 OS partition to make space for |CL|.
       follow :ref:`Advanced: Use systemd-boot to boot Windows 10 OS and 
       |CL| <advanced-systemd-boot>`.
 
-Method 2: Add another hard disk to your system where you installed |CL|
-***********************************************************************
+Method 2: Add another hard disk to your system where you installed Windows
+**************************************************************************
 
 #. Shutdown your system.
 
@@ -101,22 +98,24 @@ Method 2: Add another hard disk to your system where you installed |CL|
 
 #. Power up your system.
 
-#. Follow the instructions in :ref:`bare-metal-install-desktop`, and launch
-   the |CL| installer.
+#. Follow one of these guides to install |CL|:
 
-#. In the :guilabel:`Required options` tab, choose :guilabel:`Select
-   Installation Media`.
+   * *Desktop* version: :ref:`bare-metal-install-desktop`
+   * *Server* version: :ref:`bare-metal-install-server`
 
-#. Within that menu, select :guilabel:`Destructive Installation`, and
-   select the new hard drive from the device list.
+   a. In the :guilabel:`Required options` tab, choose :guilabel:`Select
+      Installation Media`.
 
-   .. note::
+   #. Within that menu, select :guilabel:`Destructive Installation`, and
+      select the new hard drive from the device list.
 
-      Make sure you don’t select the drive with your Windows 10 OS.
+      .. warning::
 
-#. Go through remaining steps to complete the installation.
+         Make sure you don’t select the drive with your Windows 10 OS.
 
-#. Reboot.
+    #. Go through remaining steps to complete the installation.
+
+    #. Reboot.
 
 #. During the BIOS POST stage, press :kbd:`F10`, or the proper F-key for your
    system, to launch the :guilabel:`Boot Menu`.

source/tutorials/nvidia-cuda.rst

@@ -70,7 +70,7 @@ Refer to the `NVIDIA documentation on CUDA system requirements
 <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#system-requirements>`_
 for the latest kernel and compiler compatibility. 
 
-For example, CUDA 10.1 on a system with the latest Linux kernel requires GCC7,
+For example, CUDA 10.2 on a system with the latest Linux kernel requires GCC8,
 which is older than the default GCC version for |CL|.
 
 Install the compatible version of GCC, if required:
@@ -79,7 +79,7 @@ Install the compatible version of GCC, if required:
 
    .. code:: bash
 
-      sudo swupd bundle-add c-extras-gcc7
+      sudo swupd bundle-add c-extras-gcc8
       
 #. Create the directory :file:`/usr/local/cuda/bin`:
 
@@ -95,8 +95,8 @@ Install the compatible version of GCC, if required:
 
    .. code:: bash
    
-      sudo ln -s /usr/bin/gcc7 /usr/local/cuda/bin/gcc
-      sudo ln -s /usr/bin/g++7 /usr/local/cuda/bin/g++  
+      sudo ln -s /usr/bin/gcc-8 /usr/local/cuda/bin/gcc
+      sudo ln -s /usr/bin/g++-8 /usr/local/cuda/bin/g++  
 
 
 Downloading and Installation
@@ -173,7 +173,6 @@ installed.
       
       sudo ./cuda_<VERSION>_linux.run \
       --toolkit \
-      --samples \
       --installpath=/opt/cuda \
       --no-man-page \
       --override \

source/tutorials/nvidia.rst

@@ -21,9 +21,9 @@ require a manual installation.
    with |CL| updates and must be updated and maintained manually.
 
    For example, the file :file:`/usr/lib/libGL.so` conflicts with the file
-   provided by the mesa package in |CL| and the file NVIDIA provides. If a |CL|
-   update overwrites these files, a reinstallation of the NVIDIA driver might
-   be required.
+   provided by the mesa package in |CL| and the file NVIDIA provides. If a
+   |CL| update or repair overwrites these files, a reinstallation of the
+   NVIDIA driver might be required.
 
 .. contents:: :local:
     :depth: 1
@@ -34,6 +34,13 @@ Prerequisites
 * A |CL| system with a desktop installed
 * An NVIDIA device installed
 
+
+Known issues
+============
+
+Systems with multiple graphics devices, including integrated graphics (iGPU),
+are known to be problematic.
+
 .. note:: NVIDIA Optimus
    
    Some systems come with a hybrid graphics configuration for a balanced power
@@ -50,18 +57,84 @@ Prerequisites
    documentation. As a simple workaround, some systems can disable one of the
    graphics devices or NVIDIA Optimus* in the system firmware.
 
+.. note::
+   The :ref:`Long Term Support (LTS) kernel <compatible-kernels>` variant is
+   more likely to be compatible with proprietary NVIDIA drivers.
+
+**See the** `Troubleshooting`_ **section for more known issues and solutions.**
+
 
 Installation
 ************
 
+Configure workarounds
+=====================
+
+Some workarounds are required for the NVIDIA proprietary drivers to be usable
+and sustainable on |CL|.
+
+
+#. Remove the kernel command-line parameter *intel_iommu=igfx_off* or disable
+   input–output memory management unit (IOMMU), also known as Intel®
+   Virtualization Technology for Directed I/O (VT-d), in your system EFI/BIOS.
+   See `this GitHub report
+   <https://github.com/clearlinux/distribution/issues/1274>`_ and the NVIDIA
+   documentation on `DMA issues
+   <https://download.nvidia.com/XFree86/Linux-x86_64/440.44/README/dma_issues.html>`_
+   for more information.
+
+   The *intel_iommu-igfx_off* kernel parameter can be removed with the
+   commands below: 
+  
+   .. code-block:: bash
+    
+      sudo mkdir -p /etc/kernel/cmdline-removal.d/
+      echo "intel_iommu=igfx_off" | sudo tee /etc/kernel/cmdline-removal.d/intel-iommu.conf
+    
+#. Create a custom systemd unit that overwrites the :file:`libGL` library
+   after every |CL| update with a pointer to the NVIDIA provided copy instead
+   of the version provided by |CL|. These libraries conflict causing the
+   NVIDIA driver to break when |CL| updates mesa. See the NVIDIA documentation
+   on `installed components
+   <https://download.nvidia.com/XFree86/Linux-x86_64/440.44/README/installedcomponents.html>`_
+   for more information.
+
+   a. Create a systemd service unit to overwrite the |CL| provided
+      :file:`libGL.so.1` files with a symlink to the NVIDIA copies.
+  
+      .. code-block:: bash
+
+         sudo tee /etc/systemd/system/fix-nvidia-libGL-trigger.service > /dev/null <<'EOF'
+         [Unit]
+         Description=Fixes libGL symlinks for the NVIDIA proprietary driver
+         BindsTo=update-triggers.target
+
+         [Service]
+         Type=oneshot
+         ExecStart=/usr/bin/ln -sfv /opt/nvidia/lib/libGL.so.1 /usr/lib/libGL.so.1
+         ExecStart=/usr/bin/ln -sfv /opt/nvidia/lib32/libGL.so.1 /usr/lib32/libGL.so.1
+         EOF
+
+   b. Reload the systemd manager configuration to pickup the new serivce.
+  
+      .. code-block:: bash  
+    
+         sudo systemctl daemon-reload
+       
+   c. Add the service as a depndency to the |CL| updates trigger causing the
+      service to run after every update.
+  
+      .. code-block:: bash  
+      
+         sudo systemctl add-wants update-triggers.target fix-nvidia-libGL-trigger.service
+
 Install DKMS
 ============
 
-The :ref:`Dynamic Kernel Module System (DKMS)
-<kernel-modules-dkms>` allows the NVIDIA kernel modules to be automatically
-integrated when kernel updates occur in |CL|.
-
-Install the appropriate DKMS bundle using the instructions below:
+The :ref:`Dynamic Kernel Module System (DKMS) <kernel-modules-dkms>` allows
+the NVIDIA kernel modules to be automatically integrated when kernel updates
+occur in |CL|. Install the appropriate DKMS bundle using the instructions
+below:
 
 .. note::
    The Long Term Support (LTS) kernel variant is more likely to remain
@@ -187,7 +260,7 @@ Install the NVIDIA drivers
       --x-library-path=/opt/nvidia/lib64 \
       --x-sysconfig-path=/etc/X11/xorg.conf.d \
       --documentation-prefix=/opt/nvidia \
-      --application-profile-path=/etc/nvidia \
+      --application-profile-path=/etc/nvidia/nvidia-application-profiles-rc.d \
       --no-precompiled-interface \
       --no-nvidia-modprobe \
       --no-distro-scripts \
@@ -206,22 +279,6 @@ Install the NVIDIA drivers
 
       lsmod | grep ^nvidia
 
-#. Run a |CL| system verification to restore files that the NVIDIA installer
-   likely deleted.
-
-   .. code-block:: bash
-
-      sudo swupd repair --quick --bundles=lib-opengl
-
-   .. warning:: 
-
-      Although a limited version of :command:`swupd repair` is run above,
-      other uses of the :command:`swupd repair` command should be avoided
-      with the proprietary NVIDIA drivers installed.
-
-      The NVIDIA software places some files under the :file:`/usr` subdirectory
-      that are not managed by |CL| and conflict with the |CL| stateless design.
-
 #. Optional: Create a link for the nvidia-settings desktop entry to
    :file:`~/.local/share` so that it appears in the launcher for easy access. 
 
@@ -265,12 +322,22 @@ not in use.
 
 #. Reboot the system and log back in.
 
-#. Trigger a flatpak update that will download the runtime corresponding
+#. Trigger a :command:`flatpak update` to download the runtime corresponding
    with the new NVIDIA drivers for the flatpak apps that require it.
 
+   .. important:: 
+
+      Some flatpak applications won't start after updating the NVIDIA drivers
+      until the flatpak runtime is updated with the corresponding driver
+      version.
+      
    .. code-block:: bash
 
-      flatpak update
+      flatpak update 
+
+
+
+      
 
 Uninstallation
 **************
@@ -278,6 +345,16 @@ Uninstallation
 The NVIDIA drivers and associated software can be uninstalled and nouveau
 driver restored with the instructions in this section.
 
+#. Remove the files created for workarounds.
+
+   .. code-block:: bash
+
+      sudo rm /etc/kernel/cmdline-removal.d/intel-iommu.conf
+      sudo rm /etc/systemd/system/fix-nvidia-libGL-trigger.service
+      sudo rm /etc/systemd/system/update-triggers.target.wants/fix-nvidia-libGL-trigger.service
+      sudo systemctl daemon-reload
+      
+
 #. Remove the :file:`modprobe.d` file that prevents nouveau from loading.
 
    .. code-block:: bash
@@ -320,6 +397,43 @@ Troubleshooting
   installation files into a directory named
   :file:`NVIDIA-Linux-x86_64-<VERSION>`.
 
+* The X server logs under :file:`/var/log/X*` contain useful
+  information about display and driver loading. Check all the files and
+  timestamps when troubleshooting.
+
+* The DKMS build logs under :file:`/var/lib/dkms/nvidia*` contain information
+  about kernel module builds which can be useful if the NVIDIA driver breaks
+  between kernel upgrades.
+
+
+No display or blank screen
+==========================
+
+Check to see if the display has come up on another graphics device, including
+the integrated graphics device.
+
+You might get a black screen or the login screen might not come up after
+installing the NVIDIA drivers until an Xorg configuration has been defined for
+your monitors.
+
+
+"Oh no! Something has gone wrong" GNOME crash
+=============================================
+
+
+.. figure:: /_figures/nvidia/nvidia-gnome-crash.png
+   :alt: NVIDIA driver GNOME crash on Clear Linux OS
+   :align: center
+
+   NVIDIA driver GNOME crash dialogue on Clear Linux OS.
+
+There have been reports of GNOME crashing with an "Oh no! Something has gone
+wrong" error message with NVIDIA drivers installed while other graphics
+devices are enabled.
+
+Try disabling other graphics devices, including integrated graphics, in your
+system's EFI/BIOS. 
+
 
 Brightness control
 ==================

source/tutorials/openfaas.rst

@@ -0,0 +1,387 @@
+.. _openfaas:
+
+OpenFaaS\*
+##########
+
+This tutorial shows how to set up OpenFaaS running on top of a Kubernetes\*
+cluster on |CL|, obtain |CL| based OpenFaaS templates, and develop an example
+function.
+
+.. contents:: :local:
+    :depth: 1
+
+Background
+**********
+
+Functions as a Service (FaaS) is a framework for building serverless functions
+that are ephemeral, automatically scalable, and focused pieces of code running
+within containers to allow developers to focus on application code rather than
+infrastructure nuances.
+
+Many cloud service providers have ready-to-use FaaS offerings which offer a
+high degree of convenience for developers and granular billing based on
+per-second usage. 
+
+If you want an on-premise or self-hosted serverless capability to avoid vendor
+lock-in or simply want more development, OpenFaaS is currently the most
+popular solution in the space based on the number of Github stars on the
+project.
+
+Prerequisites
+*************
+
+For simplicity, this tutorial assumes you have a Kubernetes single node
+cluster with only master node running |CL|.
+
+- For detailed instructions on how to install |CL|, see the :ref:`getting
+  started <get-started>` section.
+
+- For a detailed guide on how to set up Kubernetes, see the documentation on
+  :ref:`Kubernetes <kubernetes>`.
+
+.. note::
+
+  Please note that in this example the `master node was tainted
+  <https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#control-plane-node-isolation>`_
+  to be able to be scheduled, which means containers are able to be deployed
+  to the master node.
+
+  .. code:: bash
+
+     kubectl taint nodes --all node-role.kubernetes.io/master-
+
+
+Deploy OpenFaaS
+***************
+
+#. Install the official command line tool for using OpenFaas, *faas-cli*, by
+   installing the *faas-cli* bundle.
+
+   .. code:: bash
+
+      sudo swupd bundle-add faas-cli
+
+#. Download the `faas-netes <https://github.com/openfaas/faas-netes>`_, the
+   OpenFaaS provider templates that enable Kubernetes for OpenFaaS.
+
+   .. code:: bash
+
+      git clone https://github.com/openfaas/faas-netes.git
+
+#. Set variables for the OpenFaaS admin user and password.
+
+   .. warning:: 
+
+      For simplicity, this tutorial uses a basic authentication with an
+      unecrypted username and password. For production environments, see the
+      OpenFaaS documentation on `Deploying OpenFaas in Production
+      <https://docs.openfaas.com/architecture/production/#advanced-kubernetes-configuration>`_.
+
+   .. code:: bash
+
+      export FAAS_USER=admin
+      export FAAS_PASSWD=clearlinux
+
+#. Deploy the OpenFaaS stack on Kubernetes using :command:`kubectl`.
+
+   .. code:: bash
+
+      kubectl apply -f faas-netes/namespaces.yml
+
+   .. code:: bash
+
+      kubectl -n openfaas create secret generic basic-auth \
+      --from-literal=basic-auth-user=$FAAS_USER \
+      --from-literal=basic-auth-password="$FAAS_PASSWD"
+
+   .. code:: bash
+
+      kubectl apply -f faas-netes/yaml/
+
+   Wait for the OpenFaaS pods and services to get ready. This involves
+   downloading container images from the Internet and may take some time
+   depending on your Internet connection. You can enter the commands below to
+   have the terminal wait until services are ready to use. 
+
+   .. code:: bash
+
+      kubectl wait --for=condition=available --timeout=600s deployment/gateway -n openfaas
+      kubectl wait --for=condition=available --timeout=600s deployment/faas-idler -n openfaas
+      
+#. Login to the OpenFaaS instance. *31112* is the default port.
+
+   - You can login over the command-line:
+     
+     .. code:: bash
+
+        export OPENFAAS_URL=http://127.0.0.1:31112
+        echo -n $FAAS_PASSWD | faas-cli login --password-stdin
+
+
+   - You can also login to the OpenFaaS web interface by navigating to 
+     **http://${master_node_IP}:31112**
+
+
+   .. figure:: /_figures/openfaas/openfaas-login.png
+      :scale: 100%
+      :align: center
+      :alt: OpenFaaS web interface login page
+
+      Figure 1: OpenFaaS web interface login page
+
+OpenFaaS templates
+******************
+
+OpenFaaS templates, though not necessary, abstract configurations for
+running functions in common programming languages. Templates allows developers
+to better focus on writing the code for their function.
+
+OpenFaaS  has dozens of `templates in the official store
+<https://github.com/openfaas/templates>`_. There are also |CL|-based templates
+available for download. 
+
+#. You can list all the official templates in the store using
+   :command:`faas-cli`.
+
+   .. code:: bash
+
+      faas-cli template store list
+
+      NAME                     SOURCE             DESCRIPTION
+      csharp                   openfaas           Classic C# template
+      dockerfile               openfaas           Classic Dockerfile template
+      go                       openfaas           Classic Golang template
+      java8                    openfaas           Classic Java 8 template
+      node                     openfaas           Classic NodeJS 8 template
+      php7                     openfaas           Classic PHP 7 template
+      python                   openfaas           Classic Python 2.7 template
+      python3                  openfaas           Classic Python 3.6 template
+      ...
+
+#. Create and enter a workspace.
+
+   .. code-block:: bash
+
+      mkdir ~/faas-example
+      cd ~/faas-example
+
+#. Download the |CL|-based OpenFaaS templates which are stored in the
+   https://github.com/clearlinux/dockerfiles repository and copy them into your
+   working directory.
+
+   .. code:: bash
+
+      git clone https://github.com/clearlinux/dockerfiles.git
+      cp -r dockerfiles/FaaS/OpenFaaS/template/ .
+
+#. After the |CL| based templates have been retrieved, they will show up in
+   the same repository and available to use locally.
+
+   .. code:: bash
+
+      faas-cli new --list
+
+      Languages available as templates:
+      - dockerfile-clearlinux
+      - python3-clearlinux
+
+OpenFaaS is ready to use at this point. See the `OpenFaaS documentation
+<https://docs.openfaas.com>`_ to learn more about deploying functions.
+
+
+Example: Develop a function
+***************************
+
+In this example, we'll imagine a FaaS solution where: a user provides a URL to
+a pictures, which invokes a function to do image classification and outputs
+the result.
+
+We will use the `OpenVINO Deep Learning Deployment Toolkit (DLDT)
+<https://software.intel.com/en-us/openvino-toolkit/>`_ to do the image
+inference. As inference development is not the focus of this example, we will
+just use the built-in sample "`classification_sample_async
+<https://docs.openvinotoolkit.org/latest/_inference_engine_samples_classification_sample_async_README.html>`_"
+for this function.
+
+
+We'll use the *python3-clearlinux* template as a base and customize it by:
+
+* Adding additional |CL| bundles (*bundles.txt*)
+* Adding additional required python packages (*requirements.txt*)
+* Adding a script to download and convert dldt models (*helper_script.sh*)
+* Finally, we'll develop the python function to be run (*handler.py*)
+
+More ways to customize the |CL| based OpenFaaS templates can be found in the
+`README on GitHub
+<https://github.com/clearlinux/dockerfiles/tree/master/FaaS/OpenFaaS/template#python3-clearlinux>`_.
+
+#. Enter the previously created working directory.
+
+   .. code-block:: bash
+
+      cd ~/faas-example
+
+#. Create a new function skeleton
+
+   .. code-block:: bash
+
+      faas-cli new --lang python3-clearlinux classification-sample --prefix="<your docker name>"
+      
+   This will create the directory  structure below:
+
+   .. code-block:: console
+
+       tree .
+        ├── classification-sample
+        │   ├── bundles.txt
+        │   ├── handler.py
+        │   ├── helper_script.sh
+        │   ├── __init__.py
+        │   └── requirements.txt
+        ├── classification-sample.yml
+
+#. Add the required |CL| bundles to the :file:`bundles.txt` file. 
+
+   .. code-block:: bash
+
+      echo "computer-vision-openvino" >> classification-sample/bundles.txt
+
+#. Add the required python packages to the :file:`requirements.txt` file. 
+
+   .. code-block:: bash
+
+      echo "glob3" >> classification-sample/requirements.txt
+      echo "urllib3" >> classification-sample/requirements.txt
+      echo "networkx==2.3" >> classification-sample/requirements.txt
+
+
+#. OpenCV has a `model downloader and other automation tools
+   <https://github.com/opencv/open_model_zoo/tree/master/tools/downloader>`_
+   to help downloading models and converting them into different formats.
+   Customize the OpenFaaS template to use the model-downloader in the
+   :file:`helper_script.sh` file. The :file:`helper_script.sh` file script
+   gets executed during the build process.
+
+   .. code-block:: bash
+      :caption: helper_script.sh
+      :name: helper_script.sh
+
+      cat classification-sample/helper_script.sh
+      #!/bin/bash
+
+      # Download and convert models
+      export MODEL_DIR="/models"
+      export MO_PATH="/usr/share/openvino/model-optimizer/mo.py"
+      export MODEL_NAME="resnet-50-int8-tf-0001"
+
+      # Download and convert models
+      model-downloader --name $MODEL_NAME -o $MODEL_DIR
+      model-converter --name $MODEL_NAME -d $MODEL_DIR -o $MODEL_DIR --mo $MO_PATH
+
+
+#. With the requirements added to the template. Write a python in the
+   :file:`handler.py` file. This function will parse the input picture URL,
+   find the model path, and call “classification_sample_async” to do image
+   classification. 
+
+   .. code-block:: python
+      :caption: handler.py
+      :name: handler.py
+
+      #!/usr/bin/python3
+
+      import os
+      import glob
+      import urllib.request
+      from urllib.parse import urlparse
+      from os.path import splitext
+
+      ALLOWED_IMAGE_TYPE = [".bmp", ".BMP"]
+
+      def get_ext(url):
+          parsed = urlparse(url)
+          _, ext = splitext(parsed.path)
+          return ext
+
+      def get_image_from_url(url):
+          """get image and save to local path"""
+
+          ext = get_ext(url)
+
+          local_file_path = "/tmp/image" + ext
+          urllib.request.urlretrieve(url, local_file_path)
+          return local_file_path
+
+      def find_model_path():
+          """ return model xml path """
+
+          model_dir = os.getenv('MODEL_DIR', '/models')
+          model_name = os.getenv('MODEL_NAME', 'resnet-50-int8-tf-0001') + ".xml"
+          precision = os.getenv('MODEL_PRECISION', 'FP32')
+
+          pattern = model_dir + '/**/' + precision + '/' + model_name
+          paths = glob.glob(pattern, recursive=True)
+
+          if not len(paths):
+              print("No " + model_name + " found")
+              return None
+
+          return paths[0]
+
+      def do_classification(image, model_path):
+          """ Use dldt sample classification_sample_async """
+
+          cmd = "classification_sample_async -i " + image + " -m " + model_path
+          return os.system(cmd)
+
+      def handle(req):
+          """handle a request to the function
+          Args:
+              req (str): request body
+          """
+          if not len(req):
+              print("Request body is missing.")
+              return
+
+          model_path = find_model_path()
+          if model_path is None:
+              return
+
+          if get_ext(req) not in ALLOWED_IMAGE_TYPE:
+              print("Only " + ALLOWED_IMAGE_TYPE + " images are allowed.")
+              return
+
+          file_path = get_image_from_url(req)
+          do_classification(file_path, model_path)
+
+
+
+
+
+#. Build and deploy the function to the OpenFaaS instance.
+
+   .. code-block:: bash
+
+      faas-cli build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$https_proxy -f classification-sample.yml
+      faas-cli deploy --env=http_proxy=$http_proxy --env=https_proxy=$https_proxy -f classification-sample.yml
+      
+#. Finally, test the function by going to the OpenFaaS web interface at
+   **http://${master_node_IP}:31112** and Invoking the *classification-sample*
+   function with a URL to any BMP image. The result should show the what the
+   image has been identified as and probability. 
+
+
+   .. figure:: /_figures/openfaas/openfaas-invoke-function.png
+      :scale: 100%
+      :align: center
+      :alt: OpenFaaS web interface invoke function
+
+      Figure 2: OpenFaaS web interface invoke function
+
+   .. figure:: /_figures/openfaas/openfaas-function-output.png
+      :scale: 100%
+      :align: center
+      :alt: OpenFaaS web interface function output
+
+      Figure 3: OpenFaaS web interface invoke function
+