From c5db9bbaa7852078789510b188490d705be63de9 Mon Sep 17 00:00:00 2001 From: bktan8 Date: Wed, 18 Mar 2020 19:18:02 -0700 Subject: [PATCH] Update unattended installation doc and deprecate ister doc. (#1079) Closes #1052 Signed-off-by: Bun K Tan --- source/get-started/install-configfile.rst | 173 +++++++++++----------- source/guides/clear/ister.rst | 92 ------------ source/guides/clear/mixer.rst | 2 +- 3 files changed, 90 insertions(+), 177 deletions(-) delete mode 100644 source/guides/clear/ister.rst diff --git a/source/get-started/install-configfile.rst b/source/get-started/install-configfile.rst index 60a1bf75..f6e70377 100644 --- a/source/get-started/install-configfile.rst +++ b/source/get-started/install-configfile.rst @@ -3,10 +3,11 @@ Install using clr-installer and a configuration file #################################################### -This page explains how to install |CL-ATTR| using the clr-installer tool -with a configuration file. The configuration file (:file:`clr-installer.yaml`) -can be reused to duplicate the same installation configuration on additional -machines. +In addition to the interactive GUI and text-based modes, +:command:`clr-installer` also supports an unattended mode where you +simply provide it a YAML configuration file. + +This guide shows you two examples of how to use its unattended mode. .. contents:: :local: @@ -15,67 +16,63 @@ machines. Prerequisites ************* -Ensure that your target system supports the installation: +For installation onto bare metal, ensure that your target system +supports these requirements: * :ref:`system-requirements` * :ref:`compatibility-check` -Process -******* +Download and make bootable USB of the live server image +******************************************************* -This guide describes two methods for using a configuration file with the -clr-installer tool. You can use either method to achieve the same goal. Choose -the method that works best for your setup. +See :ref:`bootable-usb`. -If you are installing |CL| for the first time, we recommend Example 1. +Example 1: Fresh installation onto bare metal +********************************************* -To clone an existing |CL| setup on another system, we recommend Example 2. +This example uses a YAML configuration file to perform a new installation. -Example 1 -========= +#. Boot up the |CL| Live Server USB thumb drive. -This method uses a configuration file template to perform a new installation. - -Perform the following steps: - -#. Go to `Downloads`_ and download the latest Clear Linux OS Server image. - - For example: - https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz - -#. Follow the instructions to :ref:`bootable-usb` based on your OS. - -#. Boot up the USB thumb drive. #. Select :guilabel:`Clear Linux OS` from the menu. -#. In the console window, log in as root and set a password. + +#. In the console window, log in as `root` and set a password. + #. Verify you have a network connection to the Internet and configure proxy settings if you're working behind a firewall. -#. Download a :file:`live-server.yaml` template. - For example: +#. Download a sample YAML configuration file. For example, if you want to + install |CL| with a desktop GUI, you might want to use :file:`live-desktop.yaml`. + Or you can use the :file:`live-server.yaml` if you want to install a non-GUI version + of |CL|. - .. code-block:: bash + * *Desktop:* - curl -O https://download.clearlinux.org/releases/30010/clear/config/image/live-server.yaml + .. code-block:: bash -#. Edit the template and change the settings as needed. + curl -O https://cdn.download.clearlinux.org/current/config/image/live-desktop.yaml - Commonly-changed settings include: + * *Server:* -.. _install-configfile-yaml-begin: + .. code-block:: bash - #. Under *block-devices*, set “file: "/dev/sda"” or enter your preferred device. - #. Under *targetMedia*, set the third partition size to “0” to use the entire disk space. - #. Under *bundles*, add additional bundles as needed. + curl -O https://cdn.download.clearlinux.org/current/config/image/live-server.yaml + +#. Edit the YAML configuration file and change the settings as needed. + + Commonly-changed settings include (refer to the example below): + + a. Under *block-devices* (line 15), set your target media. For example: ``file: "/dev/sda"``. + #. Under *targetMedia* (line 34), set the third partition size to “0” to use the entire disk space. + #. Under *bundles* (line 37), add additional bundles as needed. #. Delete the *post-install* section unless you have post-installation scripts. - #. Under *Version*, set a version number. To use the latest version, set to “0”. + #. Under *Version* (line 50), set a version number. To use the latest version, set to “0”. - Commonly-changed settings are shown in lines 15, 34, 37, and 51 below. See `Installer YAML Syntax`_ for more details. - .. code-block:: bash + .. code-block:: console :linenos: - :emphasize-lines: 14,15,34,37,51 + :emphasize-lines: 14,15,34,37,50 #clear-linux-config @@ -121,7 +118,6 @@ Perform the following steps: telemetry: false iso: true keepImage: true - autoUpdate: false keyboard: us language: en_US.UTF-8 @@ -129,56 +125,67 @@ Perform the following steps: version: 30010 -.. _install-configfile-yaml-end: - -Start the installation with the command: - -.. code-block:: bash - - clr-installer --config live-server.yaml - -Example 2 -========= - -This method uses a saved configuration file from a previous installation, -which you can use to easily duplicate the installation on additional machines. - -Perform the following steps: - -#. Open a console window on a system where |CL| was installed to retrieve a - copy of the configuration file. - -#. In the console window, log in as root and enter your password. - -#. Change directory to :file:`/root` and copy the :file:`clr-installer.yaml` - file to a USB thumb drive. +#. Start the unattended installation using the `--config` option. .. code-block:: bash - cd /root - cp clr-installer.yaml + clr-installer --config live-server.yaml -Start the installation on the target with the following steps: +#. Reboot your system after installation is completed. -#. Go to `Downloads`_ and download the latest Clear Linux OS Server image. +Example 2: Replicate a previous installation +******************************************** - For example: - https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz +This example uses a saved configuration file from a previous installation, +which you can use to easily clone the installation on additional machines +, ideally with the same hardware configuration. -#. Follow the instructions to :ref:`bootable-usb` based on your OS. +.. warning:: + + Be aware of the following when applying a saved configuration on a new machine: + + * Make sure the target media on the new machine matches up + + * The users' credentials will be replicated as well -#. Boot up the USB thumb drive. -#. Select :guilabel:`Clear Linux OS` from the menu. -#. In the console window, log in as root and set a password. -#. Verify you have a network connection to the Internet and configure proxy - settings if you're working behind a firewall. -#. Plug in and mount the USB thumb drive containing the retrieved - :file:`clr-installer.yaml` configuration file. -#. Start the installation with the command: +#. On a system where |CL| was installed, open a terminal window. + +#. Get root privilege. .. code-block:: bash - clr-installer --config clr-installer.yaml + sudo su + +#. Copy the :file:`clr-installer.yaml` from :file:`/root` to a USB thumb drive. + + .. code-block:: bash + + cp /root/clr-installer.yaml + +#. Install on target system. + + a. Boot up the |CL| Live Server USB thumb drive. + + #. Select :guilabel:`Clear Linux OS` from the menu. + + #. In the console window, log in as `root` and set a password. + + #. Verify you have a network connection to the Internet and configure proxy + settings if you're working behind a firewall. + + #. Plug in and mount the USB thumb drive containing the retrieved + :file:`clr-installer.yaml` configuration file. + + #. Doublecheck to make sure the target media in the saved configuration file + matches with the target system's. + + #. Start the installation. + + .. code-block:: bash + + clr-installer --config clr-installer.yaml + + #. Reboot your system after installation is completed. References ********** @@ -186,7 +193,5 @@ References * `Clear Linux Installer`_ * `Installer YAML Syntax`_ -.. _Downloads: https://clearlinux.org/downloads .. _Clear Linux Installer: https://github.com/clearlinux/clr-installer - -.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md \ No newline at end of file +.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md diff --git a/source/guides/clear/ister.rst b/source/guides/clear/ister.rst deleted file mode 100644 index 21e2b6af..00000000 --- a/source/guides/clear/ister.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _ister: - -ister.py image builder -###################### - -The `ister.py`_ tool is a template-based installer used by |CL-ATTR| to produce -images for each release. The same ister tool is available for use in |CL| to -create custom images based on an upstream image. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -|CL| is a rolling release and produces an average of 10 releases per week using the -ister tool. With each release, we produce multiple -:ref:`image types for different environments ` and use cases such -as installers, Hyper-V, KVM, or VMWare. - -Each image has a JSON configuration file that is used by ister to generate the -image. These JSON configuration files describe the image type, partitions, version, -and bundles that will be preinstalled by default with the image. For each image -type we produce, the corresponding JSON configuration file for the image also is -published. - -The :ref:`mixer` tool also uses ister to build images for your custom -mix. Like upstream images, a JSON configuration file is defined for the image, -which ister uses to generate the image. Refer to the :ref:`mixer` guide -for instructions on using ister to build an image for a custom mix. - -Examples -******** - -Recreate an upstream image -========================== - -The published configuration files for upstream images may be used to recreate an -image. Here are some examples: - -* Use an older version of |CL| and the image is no longer available (only after - March 2017). -* Customize the partitions of an image. -* Customize the bundles preinstalled in an image. -* Run your own post installation script. - - -Follow these steps to recreate an upstream image based on the image's JSON -configuration file: - -#. Install the :command:`os-installer` bundle. Refer to :ref:`swupd-guide` for - more information on installing bundles. - -#. Download the `ister.py`_ tool and grant it sudo privileges. - -#. Download the JSON configuration file for the desired image (located in - :file:`config/image/`): - - * `Current release`_ - * `Previous releases`_ (only after March 2017) - - For a previous release, navigate to `Previous releases`_, select the version - you want, and find the JSON configuration file under - :file:`/clear/config/image`. For example: - ``https://cdn.download.clearlinux.org/releases/15700/clear/config/image/`` - -#. Download the “PostNonChroot” script (if applicable). - - The JSON configuration file for the image may have an accompanying - “PostNonChroot” script that is executed at the end of the image creation - process. If it does, download the script and make it executable. - -#. Edit the JSON configuration file as needed. - -#. If your configuration file has an accompanying "PostNonChroot" script, change - the default path of the script to match your path. - -#. Generate the new image with the following command: - - .. code-block:: bash - - sudo ister.py -t [JSON configuration] - -Related topics -************** - -* :ref:`mixer` - -.. _ister.py: https://github.com/bryteise/ister -.. _Current release: https://cdn.download.clearlinux.org/current/ -.. _Previous releases: https://cdn.download.clearlinux.org/releases/ diff --git a/source/guides/clear/mixer.rst b/source/guides/clear/mixer.rst index 7a24a3fb..d545630b 100644 --- a/source/guides/clear/mixer.rst +++ b/source/guides/clear/mixer.rst @@ -160,7 +160,7 @@ A mix is created with the following steps: #. Create image. mixer creates a bootable image from your updated content using - the :ref:`ister` tool. In this step you can specify which bundles you want + the `clr-installer`_ tool. In this step you can specify which bundles you want *preinstalled* in the image. Users can later install other bundles available in your mix.