From 1dd5881251de9962a9a87fc6ae67e7c7e79c95da Mon Sep 17 00:00:00 2001 From: ihutchin Date: Fri, 23 Jun 2017 14:02:36 -0500 Subject: [PATCH 1/3] Separates install options in gs guide. Moves bare metal install from tutorial to getting started guide. Removes repeated and/or out of date information about VM and BM installations and hardware compatibility check. Adds reference tags for future documentation. --- .../bare-metal-install/bare-metal-install.rst | 56 ++++-------- .../bare-metal-install/figures/gnomedt.png | Bin .../compatibility-check.rst | 0 .../getting-started/getting-started.rst | 6 +- .../getting-started/installation-options.rst | 86 ------------------ .../clear-linux/getting-started/kernels.rst | 4 +- .../getting-started/live-image.rst | 43 +++++++++ .../getting-started/supported-hardware.rst | 20 +++- source/clear-linux/tutorials/tutorials.rst | 2 + source/clear-linux/tutorials/wordpress.rst | 23 +++-- 10 files changed, 100 insertions(+), 140 deletions(-) rename source/clear-linux/{tutorials => getting-started}/bare-metal-install/bare-metal-install.rst (88%) rename source/clear-linux/{tutorials => getting-started}/bare-metal-install/figures/gnomedt.png (100%) rename source/clear-linux/{tutorials/bare-metal-install => getting-started}/compatibility-check.rst (100%) delete mode 100644 source/clear-linux/getting-started/installation-options.rst create mode 100644 source/clear-linux/getting-started/live-image.rst diff --git a/source/clear-linux/tutorials/bare-metal-install/bare-metal-install.rst b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst similarity index 88% rename from source/clear-linux/tutorials/bare-metal-install/bare-metal-install.rst rename to source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst index 8eb13162..b6a01f65 100644 --- a/source/clear-linux/tutorials/bare-metal-install/bare-metal-install.rst +++ b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst @@ -3,36 +3,14 @@ Clear Linux host OS install on bare metal ######################################### -Verify your system hardware is supported by |CLOSIA|. |CL| can run on all -Intel® 64bit processors which support UEFI\* and SSE\* v4.1 streaming SIMD\* -instructions. The following processor families can run |CL|: - -* 2nd Generation, or later, Intel® Core™ processor family. -* Intel® Xeon® Processor E3 -* Intel® Xeon® Processor E5 -* Intel® Xeon® Processor E7 -* Intel® Atom™ processor C2000 product family for servers -- Q3 2013 version - or later. -* Intel® Atom™ processor E3800 series -- Q4 2013 version or later. - -Additionally, all the steps of this tutorial were tested using a NUC6i5SYH -Intel® NUC. Visit the `NUC6i5SYH product page`_ for detailed information. - -If you are unsure whether or not your system is compatible with |CL|, you can -follow these instructions to find out. - -.. toctree:: - :maxdepth: 1 - - compatibility-check.rst - .. note:: - Only a system running a Linux distribution can run the compatibility - check. There are two options: + The steps of this installation guide were tested using a NUC6i5SYH + Intel® NUC. Visit the `NUC6i5SYH product page`_ for detailed information. - * Install and run a Linux distribution directly on your system. - * Run a live image from a USB stick. +Verify your system hardware is supported by |CLOSIA|. Review the +:ref:`list of supported processors ` and +:ref:`instructions to run a compatibility check `. .. _create-usb: @@ -47,6 +25,8 @@ device. Therefore, the contents of the USB drive will be destroyed during the creation of the bootable USB drive. Make sure to save anything stored in the drive before proceeding. +.. _download-clear-linux-image: + Download the Latest Clear Linux Image ------------------------------------- @@ -74,6 +54,8 @@ If the files differ, the diff command outputs the difference to the console, otherwise, diff does not have any output to the console and returns you to the command prompt. +.. _copy-image: + Copy the Clear Linux image to a USB drive ----------------------------------------- @@ -116,6 +98,7 @@ The decompression and copy of the image file takes some time to complete. Once the image has been decompressed and copied to the USB drive, you can remove the USB drive from the system and move it to your target system. +.. _install-on-target: Install Clear Linux on your target system ========================================= @@ -182,6 +165,8 @@ that you have successfully installed |CL| onto your system. 10. Press enter, remove the USB drive from the system, and the system will reboot running |CL|. +.. _initial-setup: + Clear Linux initial setup after installation ============================================ @@ -297,7 +282,7 @@ Enter your new `` and the password you created earlier. You should now be in the home directory of ``. The bundle `os-clr-on-clr`_ contains the majority of applications that a developer or system administrator would want but it does not include a graphical user -interface. The `desktop` bundle includes the Gnome Desktop Manager and +interface. The `desktop` bundle includes the Gnome Desktop Manager and additional supporting applications. To test the :command:`sudo` command and ensure we set it up correctly, we can @@ -315,7 +300,7 @@ To start the Gnome Desktop Manager, enter the following command: systemctl start gdm -You will be prompted to authenticate your user. Enter the password for +You will be prompted to authenticate your user. Enter the password for `` and the Gnome Desktop should start as shown in figure 1: .. figure:: figures/gnomedt.png @@ -323,7 +308,7 @@ You will be prompted to authenticate your user. Enter the password for Figure 1: :guilabel:`Gnome Desktop` -If you want to start the Gnome Desktop each time you start your system, enter +If you want to start the Gnome Desktop each time you start your system, enter the following command: .. code-block:: console @@ -349,12 +334,8 @@ Next steps With your system now running |CL| many paths are open for you. -We have created a :ref:`tutorial ` for setting up your -|CL| system as a :abbr:`LAMP (Linux, Apache MySQL, PHP)` web sever. - -Once you have setup your system as a web server, we recommend you try out our -:ref:`tutorial on installing WordPress ` to host your own -CMS-based website on your |CL| system. +Visit our :ref:`tutorials ` page for examples on using your |CL| +system. .. _`NUC6i5SYH product page`: http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html @@ -370,3 +351,6 @@ CMS-based website on your |CL| system. .. _`wheel group`: https://en.wikipedia.org/wiki/Wheel_(Unix_term) + +.. _`tutorials`: + https://clearlinux.org/documentation/clear-linux/tutorials/tutorials.html diff --git a/source/clear-linux/tutorials/bare-metal-install/figures/gnomedt.png b/source/clear-linux/getting-started/bare-metal-install/figures/gnomedt.png similarity index 100% rename from source/clear-linux/tutorials/bare-metal-install/figures/gnomedt.png rename to source/clear-linux/getting-started/bare-metal-install/figures/gnomedt.png diff --git a/source/clear-linux/tutorials/bare-metal-install/compatibility-check.rst b/source/clear-linux/getting-started/compatibility-check.rst similarity index 100% rename from source/clear-linux/tutorials/bare-metal-install/compatibility-check.rst rename to source/clear-linux/getting-started/compatibility-check.rst diff --git a/source/clear-linux/getting-started/getting-started.rst b/source/clear-linux/getting-started/getting-started.rst index 2690d5e0..e8fb1b31 100644 --- a/source/clear-linux/getting-started/getting-started.rst +++ b/source/clear-linux/getting-started/getting-started.rst @@ -1,3 +1,5 @@ +.. _getting-started: + Getting started ############### @@ -10,5 +12,5 @@ on bare metal, or by way of live image. kernels supported-hardware - installation-options - + bare-metal-install/bare-metal-install + live-image diff --git a/source/clear-linux/getting-started/installation-options.rst b/source/clear-linux/getting-started/installation-options.rst deleted file mode 100644 index 9ebb7563..00000000 --- a/source/clear-linux/getting-started/installation-options.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _installation-options: - -Installation options -#################### - -You can check your system hardware -capabilities against the list of -:ref:`supported processors `; alternatively, -download and run the `clear-linux-check-config`_ script to check the hardware -compatibility of your system from the command line. - - -Virtualized images -================== - -Images are also available to run under Virtual Machines or containers. - -To test whether your host contains the necessary components to run the OS in -a container, download the `clear-linux-check-config`_ script and run:: - - $ ./clear-linux-check-config.sh container - -* **KVM Image** -- Download a recent KVM image, along with the UEFI firmware - helper, ``OVMF.fd`` and the KVM start helper script ``start_qemu.sh.`` Find - the ``clear-[version_number]-kvm.img.xz`` image in the `current`_ directory - and see - :ref:`kvm` for further detail. - -* **Docker Image** -- A Clear Linux* Docker* image can be downloaded - directly from the Docker hub and executed within the Docker environment. - Details were posted in the blog post `Clear Linux Highlights 3`_, and - on a Docker* enabled system you can execute:: - - docker pull clearlinux - docker run -it clearlinux - - and then follow the normal Clear Linux* instuctions to add bundles etc. - - -Bare metal installer images -=========================== - -To test whether your system contains the necessary components to run the OS -natively, download the `clear-linux-check-config`_ script and run:: - - $ ./clear-linux-check-config.sh host - - -* **Installer Image** -- The installer image allows you to manipulate and - target partitions, and to set other OS configuration features (hostname, - administrative user) commonly found in Linux installers. Find the - ``clear-[version_number]-installer.img.xz`` in our `current`_ directory. - This `blog post`_ contains more detail about the evolution of our - installer. - -* **Provisioning Image** -- This image is intended to be used in a provioning - environment. Find the ``clear-[version_number]-provision.img.xz`` image in - our `current`_ directory. *Warning*: This installer repartitions - ``/dev/sda`` and installs the OS to the new partition. Don't use this image - on a system where you care about existing data on ``/dev/sda``. - - -Other installation options -========================== - -* **Live Image** -- The live image can be used to boot the OS in a VM, or you - can lay the image down on a USB drive with a tool like ``dd`` and boot from - USB. - - This option is a great way to kick the tires with a minimal amount of - effort. Be aware, however, that if you do **not** manually configure the - install and instead use the auto-install, it will repartition ``/dev/sda``. - This image also enables telemetry by default; see the `telemetry`_ feature - page for more details. - - To select this option, download the ``clear-[version_number]-live.img.xz`` - image in the `current`_ version's download directory. - -For older versions, see our `releases`_ page. - -.. _clear-linux-check-config: http://download.clearlinux.org/current/clear-linux-check-config.sh -.. _current: http://download.clearlinux.org/current -.. _blog post: https://clearlinux.org/blogs/clear-linux-installer-v20 -.. _Clear Linux Highlights 3: https://clearlinux.org/blogs/clear-linux-highlights-3 -.. _telemetry: https://clearlinux.org/features/telemetry -.. _releases: https://download.clearlinux.org/releases diff --git a/source/clear-linux/getting-started/kernels.rst b/source/clear-linux/getting-started/kernels.rst index 806da024..e20c9b46 100644 --- a/source/clear-linux/getting-started/kernels.rst +++ b/source/clear-linux/getting-started/kernels.rst @@ -1,7 +1,7 @@ .. _kernels: -|CL| kernels -############ +Compatible |CL| kernels +####################### The |CLOSIA| provides several Linux kernels distributed over several bundles. These `bundles`_ serve the following specific use cases. diff --git a/source/clear-linux/getting-started/live-image.rst b/source/clear-linux/getting-started/live-image.rst new file mode 100644 index 00000000..eec7da4d --- /dev/null +++ b/source/clear-linux/getting-started/live-image.rst @@ -0,0 +1,43 @@ +.. _live-image: + +Live Image Installation +####################### + +This option is a great way to try a live |CL| environment without writing +to your computer's hard disk. + +The live image can be used to boot the OS in a VM, or you +can create a bootable USB drive and boot from USB. + +Be aware, however, that if you do **not** manually configure the install and +instead use the auto-install, it will repartition ``/dev/sda``. +This image also enables telemetry by default; see the `telemetry`_ feature +page for more details. + +Download the latest Clear Linux Live Image +------------------------------------------ + +Download the ``clear-[version_number]-live.img.xz`` +image in the `current`_ version's download directory. + +For older versions, see our `releases`_ page. + +.. include:: bare-metal-install/bare-metal-install.rst + :Start-after: create-usb: + :end-before: download-clear-linux-image + +This example uses release 10980 so we will download the +:file:`clear-10980-installer.img.xz` image file. + +.. include:: bare-metal-install/bare-metal-install.rst + :Start-after: copy-image: + :end-before: install-on-target + +**Congratulations!** + +You are now ready to boot from USB and kick the tires on your live |CL| +environment. + +.. _telemetry: https://clearlinux.org/features/telemetry +.. _releases: https://download.clearlinux.org/releases +.. _current: http://download.clearlinux.org/current diff --git a/source/clear-linux/getting-started/supported-hardware.rst b/source/clear-linux/getting-started/supported-hardware.rst index 455e3fc6..f733a27c 100644 --- a/source/clear-linux/getting-started/supported-hardware.rst +++ b/source/clear-linux/getting-started/supported-hardware.rst @@ -17,11 +17,21 @@ The following processor families can run |CL|: If you're unsure whether your system will be capable of running Clear Linux\* -OS for Intel® Architecture, you can determine ahead of time by downloading -and running the simple `clear-linux-check-config.sh`_ script locally. This -script is available in the `current`_ download directory; it checks the -hardware capabilities of your system to determine whether it will work with -the latest release. +OS for Intel® Architecture, you can check the hardware capabilities of your +system to determine whether it will work with the latest release: + +.. toctree:: + :maxdepth: 1 + + compatibility-check.rst + +.. note:: + + Only a system running a Linux distribution can run the compatibility + check. There are two alternative options: + + * Install and run a Linux distribution directly on your system. + * Run a live image from a USB stick. Disclaimers =========== diff --git a/source/clear-linux/tutorials/tutorials.rst b/source/clear-linux/tutorials/tutorials.rst index 9ec67f41..ba72f460 100644 --- a/source/clear-linux/tutorials/tutorials.rst +++ b/source/clear-linux/tutorials/tutorials.rst @@ -1,3 +1,5 @@ +.. _tutorials: + Tutorials ######### diff --git a/source/clear-linux/tutorials/wordpress.rst b/source/clear-linux/tutorials/wordpress.rst index 7921d7cf..f5cabe3c 100644 --- a/source/clear-linux/tutorials/wordpress.rst +++ b/source/clear-linux/tutorials/wordpress.rst @@ -4,19 +4,18 @@ WordPress\* use case tutorial ############################# Welcome to our WordPress use case tutorial. The objective of the tutorial is -to guide you from bare metal to a fully realized WordPress website using -|CLOSIA|. +to guide you to a fully realized WordPress website using |CLOSIA|. -For your convenience, we have split this tutorial in three different -sections. If your system is already running |CL|, you can skip the bare metal -installation tutorial. Similarly, you can skip ahead to the WordPress -tutorial if you have already have a |CL| based :abbr:`LAMP (Linux, Apache, -MySQL, PHP)` web server. +In this tutorial we assume your system is already running |CL|. For +instructions on how to install |CL| on bare metal, see the +`bare metal install`_ page from our `getting started`_ guide. +For your convenience, we have split this tutorial in two different +sections. If you already have a |CL| based :abbr:`LAMP (Linux, Apache, MySQL, +PHP)` web server you can skip ahead to the WordPress tutorial. .. toctree:: :maxdepth: 1 - bare-metal-install/bare-metal-install.rst web-server-install/web-server-install.rst wp-install/wp-install.rst @@ -24,4 +23,10 @@ MySQL, PHP)` web server. This tutorial is for development and testing purposes only. Additional steps are required to secure production systems. - Those steps are beyond the scope of this tutorial. \ No newline at end of file + Those steps are beyond the scope of this tutorial. + +.. _bare metal install: + https://clearlinux.org/documentation/clear-linux/getting-started/bare-metal-install/bare-metal-install.html + +.. _getting started: + https://clearlinux.org/documentation/clear-linux/getting-started/getting-started.html From 267fa18384b8c3efb1d45a22d1da846adc4427a1 Mon Sep 17 00:00:00 2001 From: ihutchin Date: Thu, 20 Jul 2017 16:08:32 -0700 Subject: [PATCH 2/3] Improves readability and flow within gs guide. Includes kernel in gs contents page introduction and adds compatibility check to doc-tree. Improves introduction to compatible kernels and bundles. Updates links to avoid hard coding. --- .../bare-metal-install/bare-metal-install.rst | 11 +++++++---- .../getting-started/getting-started.rst | 7 ++++--- source/clear-linux/getting-started/kernels.rst | 5 +++-- source/clear-linux/getting-started/live-image.rst | 4 ++-- .../web-server-install/web-server-install.rst | 3 ++- source/clear-linux/tutorials/wordpress.rst | 15 +++++---------- 6 files changed, 23 insertions(+), 22 deletions(-) diff --git a/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst index b6a01f65..bb42c3cc 100644 --- a/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst +++ b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst @@ -3,15 +3,18 @@ Clear Linux host OS install on bare metal ######################################### -.. note:: - - The steps of this installation guide were tested using a NUC6i5SYH - Intel® NUC. Visit the `NUC6i5SYH product page`_ for detailed information. +The following are instructions for installing |CL| on bare metal using a +bootable USB drive. Verify your system hardware is supported by |CLOSIA|. Review the :ref:`list of supported processors ` and :ref:`instructions to run a compatibility check `. +.. note:: + + The steps of this installation guide were tested using a NUC6i5SYH + Intel® NUC. Visit the `NUC6i5SYH product page`_ for detailed information. + .. _create-usb: Create a Clear Linux bootable USB drive diff --git a/source/clear-linux/getting-started/getting-started.rst b/source/clear-linux/getting-started/getting-started.rst index e8fb1b31..cfb29fd6 100644 --- a/source/clear-linux/getting-started/getting-started.rst +++ b/source/clear-linux/getting-started/getting-started.rst @@ -4,13 +4,14 @@ Getting started ############### There are a number of options available for downloading and running -|CLOSIA|. You can install |CL| under virtual machines or containers, -on bare metal, or by way of live image. +|CLOSIA|. By using different kernels you can install |CL| under virtual +machines, containers, on bare metal, or by way of live image. .. toctree:: :maxdepth: 2 kernels - supported-hardware bare-metal-install/bare-metal-install + supported-hardware + check-compatibility live-image diff --git a/source/clear-linux/getting-started/kernels.rst b/source/clear-linux/getting-started/kernels.rst index e20c9b46..7aeb5329 100644 --- a/source/clear-linux/getting-started/kernels.rst +++ b/source/clear-linux/getting-started/kernels.rst @@ -3,8 +3,9 @@ Compatible |CL| kernels ####################### -The |CLOSIA| provides several Linux kernels distributed over several bundles. -These `bundles`_ serve the following specific use cases. +The |CLOSIA| provides the following Linux kernels with a respective bundle. +This document describes the specific use cases these `bundles`_ serve +and provides links to their source code. Kernel native ============= diff --git a/source/clear-linux/getting-started/live-image.rst b/source/clear-linux/getting-started/live-image.rst index eec7da4d..45fb3477 100644 --- a/source/clear-linux/getting-started/live-image.rst +++ b/source/clear-linux/getting-started/live-image.rst @@ -6,8 +6,8 @@ Live Image Installation This option is a great way to try a live |CL| environment without writing to your computer's hard disk. -The live image can be used to boot the OS in a VM, or you -can create a bootable USB drive and boot from USB. +Use the live image to boot the OS in a VM, or you can create a bootable +USB drive and boot from USB. Be aware, however, that if you do **not** manually configure the install and instead use the auto-install, it will repartition ``/dev/sda``. diff --git a/source/clear-linux/tutorials/web-server-install/web-server-install.rst b/source/clear-linux/tutorials/web-server-install/web-server-install.rst index 14b0b33e..ebd9c2b9 100644 --- a/source/clear-linux/tutorials/web-server-install/web-server-install.rst +++ b/source/clear-linux/tutorials/web-server-install/web-server-install.rst @@ -8,7 +8,8 @@ Prerequisites In order to create a web server using |CL| as the host OS your host system must be running |CL|. Therefore, this tutorial assumes you have -already gone through the steps in :ref:`bare-metal-install`. +already gone through the :ref:`bare metal installation` +instructions. Before installing any new packages, update the |CL| OS with the console command: diff --git a/source/clear-linux/tutorials/wordpress.rst b/source/clear-linux/tutorials/wordpress.rst index f5cabe3c..61eb4469 100644 --- a/source/clear-linux/tutorials/wordpress.rst +++ b/source/clear-linux/tutorials/wordpress.rst @@ -8,10 +8,11 @@ to guide you to a fully realized WordPress website using |CLOSIA|. In this tutorial we assume your system is already running |CL|. For instructions on how to install |CL| on bare metal, see the -`bare metal install`_ page from our `getting started`_ guide. -For your convenience, we have split this tutorial in two different -sections. If you already have a |CL| based :abbr:`LAMP (Linux, Apache, MySQL, -PHP)` web server you can skip ahead to the WordPress tutorial. +:ref:`bare metal install` page from our +:ref:`getting started` guide. For your convenience, we have +split this tutorial in two different sections. If you already have a |CL| +based :abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server you can skip ahead +to the WordPress tutorial. .. toctree:: :maxdepth: 1 @@ -24,9 +25,3 @@ PHP)` web server you can skip ahead to the WordPress tutorial. This tutorial is for development and testing purposes only. Additional steps are required to secure production systems. Those steps are beyond the scope of this tutorial. - -.. _bare metal install: - https://clearlinux.org/documentation/clear-linux/getting-started/bare-metal-install/bare-metal-install.html - -.. _getting started: - https://clearlinux.org/documentation/clear-linux/getting-started/getting-started.html From cc336f2bd74a6e9e13f955a0615e5a47a426a6b7 Mon Sep 17 00:00:00 2001 From: ihutchin Date: Mon, 24 Jul 2017 11:56:34 -0700 Subject: [PATCH 3/3] Remove unnecessary verbage and hard-coded links. --- .../bare-metal-install/bare-metal-install.rst | 9 +++------ source/clear-linux/getting-started/getting-started.rst | 2 +- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst index bb42c3cc..cf42980d 100644 --- a/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst +++ b/source/clear-linux/getting-started/bare-metal-install/bare-metal-install.rst @@ -3,8 +3,8 @@ Clear Linux host OS install on bare metal ######################################### -The following are instructions for installing |CL| on bare metal using a -bootable USB drive. +These instructions will guide you through the installation of |CL| on bare +metal using a :ref:`bootable USB drive`. Verify your system hardware is supported by |CLOSIA|. Review the :ref:`list of supported processors ` and @@ -311,7 +311,7 @@ You will be prompted to authenticate your user. Enter the password for Figure 1: :guilabel:`Gnome Desktop` -If you want to start the Gnome Desktop each time you start your system, enter +To start the Gnome Desktop each time you start your system, enter the following command: .. code-block:: console @@ -354,6 +354,3 @@ system. .. _`wheel group`: https://en.wikipedia.org/wiki/Wheel_(Unix_term) - -.. _`tutorials`: - https://clearlinux.org/documentation/clear-linux/tutorials/tutorials.html diff --git a/source/clear-linux/getting-started/getting-started.rst b/source/clear-linux/getting-started/getting-started.rst index cfb29fd6..f44584f8 100644 --- a/source/clear-linux/getting-started/getting-started.rst +++ b/source/clear-linux/getting-started/getting-started.rst @@ -4,7 +4,7 @@ Getting started ############### There are a number of options available for downloading and running -|CLOSIA|. By using different kernels you can install |CL| under virtual +|CLOSIA|. Using different kernels, you can install |CL| under virtual machines, containers, on bare metal, or by way of live image. .. toctree::