From 9f675e581664bb542428754732ec6d71f1f5d12a Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Wed, 23 Jan 2019 09:50:26 -0800 Subject: [PATCH 1/6] Initial commit of new ister guide Signed-off-by: Kristal Dale --- source/clear-linux/tutorials/ister.rst | 76 ++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 source/clear-linux/tutorials/ister.rst diff --git a/source/clear-linux/tutorials/ister.rst b/source/clear-linux/tutorials/ister.rst new file mode 100644 index 00000000..1c5977c5 --- /dev/null +++ b/source/clear-linux/tutorials/ister.rst @@ -0,0 +1,76 @@ +.. _ister: + +Create custom upstream |CL| images with ister.py +################################################ + + +.. Bun: ister is Clear Linux specific? (It looks tuned to CL), but not in the CL project repo? This is good content - but if its part of CL it should be a full guide (will require some more info). If its an external tool, lets do it as a tutorial. +.. Bun: this url https://cdn.download.clearlinux.org/releases//clear/config/image/ doesnt work for all releases -for eg 08 Mar 2017 +.. Bun: please provide a brief description of what can be edited in the config + +|CL-ATTR| is a rolling release and produces on average 10 releases per week +using the `ister.py tool`_. This tutorial shows how to use the same ister tool +with a published image configuration file to recreate an upstream image. + +Overview +******** + +With each release, we produce multiple `different image types`_ for different environments and use cases such as installers, Hyper-V, KVM, or VMWare. For each image, we publish a corresponding JSON configuration file used to generate the image. These JSON configuration files describe XXXXXX. + +These configurations files are useful to recreate an image, for example when you want to: + +* Use an older version of |CL| and the image is no longer available. +* Customize the partitions of an image. +* Customize the bundles preinstalled in an image. +* Run your own post installation script. + +Prerequisites +************* + +#. **|CL| installed** + +#. **Required bundles** + + ister requires that the :command:`os-installer` bundle is installed. + +#. **ister.py has sudo privilege** + +Recreate an upstream image +************************** + +Follow these steps to recreate an upstream image based on the image's JSON +configuration file: + +#. Download the JSON configuration file for the desired image. Find the JSON + configuration file for the desired image: + + * `Configuration files for the current release`_ + * `Previous releases`_. + + For a previous release, the configuration file for the specific release is + located at + ``https://cdn.download.clearlinux.org/releases//clear/config/image/`` + +#. 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 as well and make it executable. + +#. Edit the JSON configuration file as needed. + + .. todo DETAILS!!! such as... + +#. If your configuration file has an accompanying "PostNonChroot" script, change + the default path of the script to match yours. + +#. Generate the new image with the following command: + + .. code-block:: bash + + sudo ister.py -t [JSON configuration] + + + +.. _ister.py tool: https://github.com/bryteise/ister +.. _different image types: https://cdn.download.clearlinux.org/image/README-IMAGES.html +.. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ +.. _Previous releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file From 7df2e75491efdcfa4cb581d5fe967ead8919b8c7 Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Fri, 25 Jan 2019 16:03:30 -0800 Subject: [PATCH 2/6] add new ister guide to toctree Signed-off-by: Kristal Dale --- .../clear-linux/guides/maintenance/ister.rst | 94 +++++++++++++++++++ .../guides/maintenance/maintenance.rst | 1 + 2 files changed, 95 insertions(+) create mode 100644 source/clear-linux/guides/maintenance/ister.rst diff --git a/source/clear-linux/guides/maintenance/ister.rst b/source/clear-linux/guides/maintenance/ister.rst new file mode 100644 index 00000000..293119b0 --- /dev/null +++ b/source/clear-linux/guides/maintenance/ister.rst @@ -0,0 +1,94 @@ +.. _ister: + +ister +##### + +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 to create +custom images based on upstream |CL|. + +Description +*********** + +|CL| is a rolling release and produces on average 10 releases per week using the +ister tool. With each release, we produce multiple `different image types`_ for +different environments and use cases such as installers, Hyper-V, KVM, or +VMWare. + +For each image, we also publish the corresponding JSON configuration file used +by ister to generate the image. These JSON configuration files describe image +type, partitions, version, and which bundles will be preinstalled by default +with the image. + +The :ref:`mixer` tool uses ister to build an image for your custom mix. +Like upstream images, a JSON configuration file is defined for the image, which +ister uses to generate the image. + +Configuration files for upstream images may be used to recreate an image, for +example when you want to: + +* 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. + +How to use ister +**************** + +Learn how to use ister to recreate an upstream image. Refer to the +:ref:`mixer ` guide for instruction on using ister to build an image for +a custom mix. + +Example: Recreate an upstream image +=================================== + +Prerequisites +------------- + +#. |CL| installed. + +#. :command:`os-installer` bundle is installed. + +#. ister.py has sudo privilege. + +Recreate upstream image +----------------------- + +Follow these steps to recreate an upstream image based on the image's JSON +configuration file: + +#. Download the JSON configuration file for the desired image: + + * `Configuration files for the current release`_ + * `Previous releases`_ (only after March 2017) + + For a previous release, the configuration file for the specific release is + located at + ``https://cdn.download.clearlinux.org/releases//clear/config/image/`` + +#. 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 as well 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 yours. + +#. Generate the new image with the following command: + + .. code-block:: bash + + sudo ister.py -t [JSON configuration] + +Related topics +************** + +* :ref:`mixer` +* :ref:`bulk-provision` + +.. _ister.py tool: https://github.com/bryteise/ister +.. _different image types: https://cdn.download.clearlinux.org/image/README-IMAGES.html +.. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ +.. _Previous releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst index 3d89fa54..1f76811c 100644 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ b/source/clear-linux/guides/maintenance/maintenance.rst @@ -28,3 +28,4 @@ completed. download-verify-decompress-windows autospec assign-static-ip + ister From 47fb8af7b5dd3006be012bd3b7bc9e16de1cd96b Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Mon, 28 Jan 2019 16:17:11 -0800 Subject: [PATCH 3/6] Revise content order based on guide template. Remove ister.rst file in tutorials (misplaced location). Signed-off-by: Kristal Dale --- .../clear-linux/guides/maintenance/ister.rst | 53 ++++++------- source/clear-linux/tutorials/ister.rst | 76 ------------------- 2 files changed, 24 insertions(+), 105 deletions(-) delete mode 100644 source/clear-linux/tutorials/ister.rst diff --git a/source/clear-linux/guides/maintenance/ister.rst b/source/clear-linux/guides/maintenance/ister.rst index 293119b0..db1b6938 100644 --- a/source/clear-linux/guides/maintenance/ister.rst +++ b/source/clear-linux/guides/maintenance/ister.rst @@ -1,31 +1,36 @@ .. _ister: -ister -##### +ister.py +######## 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 to create -custom images based on upstream |CL|. +images for each release. The same ister tool is available for use in |CL| to +create custom images based on an upstream image. Description *********** |CL| is a rolling release and produces on average 10 releases per week using the -ister tool. With each release, we produce multiple `different image types`_ for -different environments and use cases such as installers, Hyper-V, KVM, or -VMWare. +ister tool. With each release we produce multiple +`image types for different environments`_ and use cases such as installers, +Hyper-V, KVM, or VMWare. -For each image, we also publish the corresponding JSON configuration file used -by ister to generate the image. These JSON configuration files describe image -type, partitions, version, and which bundles will be preinstalled by default -with the image. +Each image has a JSON configuration file used by ister to generate the image. +These JSON configuration files describe the image type, partitions, version, +and which bundles will be preinstalled by default with the image. For each image +type we produce, the corresponding JSON configuration file for the image is also +published. -The :ref:`mixer` tool uses ister to build an image for your custom mix. -Like upstream images, a JSON configuration file is defined for the image, which -ister uses to generate the image. +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 instruction on using ister to build an image for a custom mix. -Configuration files for upstream images may be used to recreate an image, for -example when you want to: +Example: Recreate an upstream image +*********************************** + +The published configuration files for upstream images may be used to recreate an +image, for example when you want to: * Use an older version of |CL| and the image is no longer available (only after March 2017). @@ -33,18 +38,8 @@ example when you want to: * Customize the bundles preinstalled in an image. * Run your own post installation script. -How to use ister -**************** - -Learn how to use ister to recreate an upstream image. Refer to the -:ref:`mixer ` guide for instruction on using ister to build an image for -a custom mix. - -Example: Recreate an upstream image -=================================== - Prerequisites -------------- +============= #. |CL| installed. @@ -53,7 +48,7 @@ Prerequisites #. ister.py has sudo privilege. Recreate upstream image ------------------------ +======================= Follow these steps to recreate an upstream image based on the image's JSON configuration file: @@ -89,6 +84,6 @@ Related topics * :ref:`bulk-provision` .. _ister.py tool: https://github.com/bryteise/ister -.. _different image types: https://cdn.download.clearlinux.org/image/README-IMAGES.html +.. _image types for different environments: https://cdn.download.clearlinux.org/image/README-IMAGES.html .. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ .. _Previous releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file diff --git a/source/clear-linux/tutorials/ister.rst b/source/clear-linux/tutorials/ister.rst deleted file mode 100644 index 1c5977c5..00000000 --- a/source/clear-linux/tutorials/ister.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _ister: - -Create custom upstream |CL| images with ister.py -################################################ - - -.. Bun: ister is Clear Linux specific? (It looks tuned to CL), but not in the CL project repo? This is good content - but if its part of CL it should be a full guide (will require some more info). If its an external tool, lets do it as a tutorial. -.. Bun: this url https://cdn.download.clearlinux.org/releases//clear/config/image/ doesnt work for all releases -for eg 08 Mar 2017 -.. Bun: please provide a brief description of what can be edited in the config - -|CL-ATTR| is a rolling release and produces on average 10 releases per week -using the `ister.py tool`_. This tutorial shows how to use the same ister tool -with a published image configuration file to recreate an upstream image. - -Overview -******** - -With each release, we produce multiple `different image types`_ for different environments and use cases such as installers, Hyper-V, KVM, or VMWare. For each image, we publish a corresponding JSON configuration file used to generate the image. These JSON configuration files describe XXXXXX. - -These configurations files are useful to recreate an image, for example when you want to: - -* Use an older version of |CL| and the image is no longer available. -* Customize the partitions of an image. -* Customize the bundles preinstalled in an image. -* Run your own post installation script. - -Prerequisites -************* - -#. **|CL| installed** - -#. **Required bundles** - - ister requires that the :command:`os-installer` bundle is installed. - -#. **ister.py has sudo privilege** - -Recreate an upstream image -************************** - -Follow these steps to recreate an upstream image based on the image's JSON -configuration file: - -#. Download the JSON configuration file for the desired image. Find the JSON - configuration file for the desired image: - - * `Configuration files for the current release`_ - * `Previous releases`_. - - For a previous release, the configuration file for the specific release is - located at - ``https://cdn.download.clearlinux.org/releases//clear/config/image/`` - -#. 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 as well and make it executable. - -#. Edit the JSON configuration file as needed. - - .. todo DETAILS!!! such as... - -#. If your configuration file has an accompanying "PostNonChroot" script, change - the default path of the script to match yours. - -#. Generate the new image with the following command: - - .. code-block:: bash - - sudo ister.py -t [JSON configuration] - - - -.. _ister.py tool: https://github.com/bryteise/ister -.. _different image types: https://cdn.download.clearlinux.org/image/README-IMAGES.html -.. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ -.. _Previous releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file From f688fb707ad626ab500955c176a995b74e4f6c04 Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Wed, 20 Feb 2019 15:57:37 -0800 Subject: [PATCH 4/6] Updates per feedback from @mvincerx. Revise example section to include prereq as part of steps. Update Prereq to template standard. Signed-off-by: Kristal Dale --- .../clear-linux/guides/maintenance/ister.rst | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/source/clear-linux/guides/maintenance/ister.rst b/source/clear-linux/guides/maintenance/ister.rst index db1b6938..65aa925d 100644 --- a/source/clear-linux/guides/maintenance/ister.rst +++ b/source/clear-linux/guides/maintenance/ister.rst @@ -38,38 +38,41 @@ image, for example when you want to: * Customize the bundles preinstalled in an image. * Run your own post installation script. -Prerequisites -============= - -#. |CL| installed. - -#. :command:`os-installer` bundle is installed. - -#. ister.py has sudo privilege. - -Recreate upstream image -======================= - Follow these steps to recreate an upstream image based on the image's JSON configuration file: +#. Make sure you have all prerequisites: + + * |CL| + + :ref:`bare-metal-install`. + + * :command:`os-installer` bundle + + `Install a bundle`_. + +#. Download the `ister.py tool`_ and grant it sudo privileges. + #. Download the JSON configuration file for the desired image: * `Configuration files for the current release`_ * `Previous releases`_ (only after March 2017) - For a previous release, the configuration file for the specific release is - located at - ``https://cdn.download.clearlinux.org/releases//clear/config/image/`` + 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/`` -#. The JSON configuration file for the image may have an accompanying +#. Download “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 as well and make it executable. + 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 yours. + the default path of the script to match your path. #. Generate the new image with the following command: @@ -86,4 +89,5 @@ Related topics .. _ister.py tool: https://github.com/bryteise/ister .. _image types for different environments: https://cdn.download.clearlinux.org/image/README-IMAGES.html .. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ -.. _Previous releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file +.. _Previous releases: https://cdn.download.clearlinux.org/releases/ +.. _Install a bundle: https://clearlinux.org/documentation/clear-linux/guides/maintenance/swupd-guide#adding-a-bundle \ No newline at end of file From fc8cc08e6dfceb9608504ee1a5540e4ee9ff4c7c Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Thu, 21 Feb 2019 12:55:48 -0800 Subject: [PATCH 5/6] Organization revisions (minor) to bring inline with template. Signed-off-by: Kristal Dale --- .../clear-linux/guides/maintenance/ister.rst | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/source/clear-linux/guides/maintenance/ister.rst b/source/clear-linux/guides/maintenance/ister.rst index 65aa925d..ae7ff386 100644 --- a/source/clear-linux/guides/maintenance/ister.rst +++ b/source/clear-linux/guides/maintenance/ister.rst @@ -7,6 +7,10 @@ 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 *********** @@ -26,8 +30,11 @@ 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 instruction on using ister to build an image for a custom mix. -Example: Recreate an upstream image -*********************************** +Examples +******** + +Recreate an upstream image +========================== The published configuration files for upstream images may be used to recreate an image, for example when you want to: @@ -38,18 +45,12 @@ image, for example when you want to: * 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: -#. Make sure you have all prerequisites: - - * |CL| - - :ref:`bare-metal-install`. - - * :command:`os-installer` bundle - - `Install a bundle`_. +#. Install the :command:`os-installer` bundle. Refer to `Install a bundle`_ for + more details. #. Download the `ister.py tool`_ and grant it sudo privileges. From 55163e84d46f65fae8071530059770f707dde38d Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Fri, 1 Mar 2019 11:19:07 -0800 Subject: [PATCH 6/6] Update guide title per @mvincerx feedback Signed-off-by: Kristal Dale --- source/clear-linux/guides/maintenance/ister.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/guides/maintenance/ister.rst b/source/clear-linux/guides/maintenance/ister.rst index ae7ff386..4f29229a 100644 --- a/source/clear-linux/guides/maintenance/ister.rst +++ b/source/clear-linux/guides/maintenance/ister.rst @@ -1,7 +1,7 @@ .. _ister: -ister.py -######## +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