diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 3981563f..89d76597 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -1,43 +1,42 @@ .. _custom-clear-container: -Build a custom Clear Linux based Docker container image -####################################################### +Build a custom Clear Linux\* based Docker\* container image +########################################################### -The official base |CLOSIA| container image is published on Docker\* Hub and -is updated on a regular basis. This section contains the steps to build a -custom image. +The official base |CLOSIA| container image is published on Docker\* Hub and is +updated on a regular basis. This section contains the steps to build a custom +container image. Prerequisites ************* -* These steps must be performed on a |CL| system because the `swupd` command - is needed to manage bundles in the container. -* The `containers-basic` bundle must be installed on the |CL| system for - Docker to work. -* Basic knowledge of Docker is required. +* You must perform these steps on a |CL| system because the + :abbr:`swupd (software updater)` is used to manage bundles in the + container. +* You must install the :file:`containers-basic` bundle on the |CL| system + or Docker will not work. +* You have a basic understanding of Docker. -Build the base Clear Linux container image -****************************************** +Build the base container image +****************************** #. Log in and get root privileges. - .. code-block:: console + .. code-block:: bash - $ sudo -s + sudo -s #. Verify Docker is installed and running. - .. code-block:: console + .. code-block:: bash - # docker info + sudo docker info - If Docker is installed and running, the expected output will be similar to - this: + If Docker is installed and running, the output is similar to + this example: .. code-block:: console - # docker info - Containers: 0 Running: 0 Paused: 0 @@ -76,135 +75,135 @@ Build the base Clear Linux container image 127.0.0.0/8 Live Restore Enabled: false - If Docker is not installed, perform these steps: + If Docker is not installed, enter the commands: - .. code-block:: console + .. code-block:: bash - # swupd bundle-add containers-basic - # systemctl start docker + sudo swupd bundle-add containers-basic + sudo systemctl start docker -#. Create the directory structure needed for building the |CL| container. +#. Create the directory structure to build the |CL| container. - .. code-block:: console + .. code-block:: bash - # mkdir -p ./custom-clear-linux-container/base/usr/share/clear/bundles - # cd custom-clear-linux-container + sudo mkdir -p ./custom-clear-linux-container/base/usr/share/clear/bundles + sudo cd custom-clear-linux-container .. note:: - * The directories `customer-clear-linux-container` and `base` are for - the purpose of staging and can be named something else, if preferred. - * The remaining directories (`/usr/share/clear/bundles`) are mandatory. + * The directories :file:`custom-clear-linux-container` and + :file:`base` are used for staging. You can rename these directories. -#. Create the reference files of the minimum required |CL| bundles (`os-core` and - `os-core-update`). `swupd` determines which bundles to download and install - by using the reference filenames. + * The directories :file:`/usr/share/clear/bundles` are mandatory and + cannot be renamed. - .. code-block:: console +#. Create the reference files of the minimum required |CL| bundles, + :file:`os-core` and :file:`os-core-update`. The software updater + uses the reference filenames to determine which bundles to download and + install. - # touch ./base/usr/share/clear/bundles/os-core - # touch ./base/usr/share/clear/bundles/os-core-update - .. note:: + .. code-block:: bash - * `os-core` provides the minimal Linux namespace. - * `os-core-update` provides basic suite for running the |CL| - for iA Updater + sudo touch ./base/usr/share/clear/bundles/os-core + sudo touch ./base/usr/share/clear/bundles/os-core-update -#. Optionally, additional bundles can be included with the base image. + .. note:: - #. Identify the desired bundles by going to the |CL| website's - :ref:`available-bundles` page or by executing the - `swupd bundle-list -a` command + * :file:`os-core` provides the minimal Linux namespace. + * :file:`os-core-update` provides the basic suite for running the |CLOSIA| + updater. - #. Create the reference files for the identified bundles. For example, - to include the `editors` and `network-basic` bundles: +#. Optionally, you can include additional bundles with the base image. - .. code-block:: console + #. Identify the desired bundles on the |CL| website's + :ref:`available-bundles` page or execute the + :command:`swupd bundle-list -a` command. - # touch ./base/usr/share/clear/bundles/editors - # touch ./base/usr/share/clear/bundles/network-basic + #. Create reference files for the identified bundles. For example, + to include the :file:`editors` and :file:`network-basic` bundles, + enter the commands: -#. Use `swupd` to download and install the bundles into the directory - structure created. + .. code-block:: bash - .. code-block:: console + sudo touch ./base/usr/share/clear/bundles/editors + sudo touch ./base/usr/share/clear/bundles/network-basic - # swupd verify --install --path="base" --manifest 17870 \ +#. Use `swupd` to download and install the bundles. + + .. code-block:: bash + + sudo swupd verify --install --path="base" --manifest 17870 \ --url https://cdn.download.clearlinux.org/update \ --statedir "$PWD/swupd-state" --no-boot-update - .. note:: - * `verify –-install` tells `swupd` to download and install - * `–-path` specifies the root path of where the bundles are to be - installed - * `--manifest` specifies the version of the |CL| bundles to use - * `--url` specifies the URL of the bundles repository - * `--statedir` specifies the state directory where downloaded bundles - and any - state information are stored - * `--no-boot-update` tells `swupd` to skip updating boot files since - it's not needed for a container + The `swupd` example uses the following flags: - For more information on the `swupd` flags, enter the `swupd verify -h` + * :command:`verify –-install` tells `swupd` to download and install. + * :command:`--path` specifies the root path where the bundles are to be + installed. + * :command:`--manifest` specifies the version of the |CL| bundles. + * :command:`--url` specifies the URL of the bundles repository. + * :command:`--statedir` specifies the state directory where downloaded bundles + and any state information are stored. + * :command:`--no-boot-update` tells `swupd` to skip updating boot files because + boot files are not required for a container. + + For more information on `swupd` flags, enter the :command:`swupd verify -h` command. Example output: - .. code-block:: console + .. code-block:: console - # swupd verify --install --path="base" --manifest 17870 \ - --url https://cdn.download.clearlinux.org/update \ - --statedir "$PWD/swupd-state" --no-boot-update + swupd-client software verify 3.12.2 + Copyright (C) 2012-2017 Intel Corporation - swupd-client software verify 3.12.2 - Copyright (C) 2012-2017 Intel Corporation + Verifying version 17870 + Attempting to download version string to memory + Downloading packs... - Verifying version 17870 - Attempting to download version string to memory - Downloading packs... - - Extracting python-basic pack for version 17820 - ...14% - Extracting perl-basic pack for version 17790 - ...28% - Extracting openssh-server pack for version 17660 - ...42% - Extracting editors pack for version 17850 - ...57% - Extracting network-basic pack for version 17650 - ...71% - Extracting os-core pack for version 17870 - ...85% - Extracting os-core-update pack for version 17870 - ...100% - Adding any missing files - ...88% - Inspected 33982 files - 33974 files were missing - 33974 of 33974 missing files were replaced - 0 of 33974 missing files were not replaced - Calling post-update helper scripts. - WARNING: boot files update skipped due to --no-boot-update argument - Fix successful + Extracting python-basic pack for version 17820 + ...14% + Extracting perl-basic pack for version 17790 + ...28% + Extracting openssh-server pack for version 17660 + ...42% + Extracting editors pack for version 17850 + ...57% + Extracting network-basic pack for version 17650 + ...71% + Extracting os-core pack for version 17870 + ...85% + Extracting os-core-update pack for version 17870 + ...100% + Adding any missing files + ...88% + Inspected 33982 files + 33974 files were missing + 33974 of 33974 missing files were replaced + 0 of 33974 missing files were not replaced + Calling post-update helper scripts. + WARNING: boot files update skipped due to --no-boot-update argument + Fix successful .. note:: The `WARNING` message is expected and can be ignored. -#. Tar up the files and compress it. +#. Create a tarball and compress it. - .. code-block:: console + .. code-block:: bash - # tar -C base -cf base.tar . - # xz -v -T0 base.tar + sudo tar -C base -cf base.tar . + sudo xz -v -T0 base.tar #. Create the Dockerfile to build the image. - .. code-block:: console + .. code-block:: bash - # cat > Dockerfile << EOF + sudo cat > Dockerfile << EOF FROM scratch MAINTAINER First Last ADD base.tar.xz / @@ -213,169 +212,167 @@ Build the base Clear Linux container image #. Build the |CL| container image. - .. code-block:: console + .. code-block:: bash - # docker build -t my-custom-clear-linux-container . + sudo docker build -t my-custom-clear-linux-container . Example output: - .. code-block:: console + .. code-block:: console - # docker build -t my-custom-clear-linux-container . - - Sending build context to Docker daemon 806.5MB - Step 1/4 : FROM scratch - ---> - Step 2/4 : MAINTAINER First Last - ---> Running in 7238f35abcd0 - ---> ec5064287c60 - Removing intermediate container 7238f35abcd0 - Step 3/4 : ADD base.tar.xz / - ---> 2723b7d20716 - Removing intermediate container 16e3ed0df8da - Step 4/4 : CMD /bin/bash - ---> Running in efa893350647 - ---> 5414c3a12993 - Removing intermediate container efa893350647 - Successfully built 5414c3a12993 - Successfully tagged my-custom-clear-linux-container:latest + Sending build context to Docker daemon 806.5MB + Step 1/4 : FROM scratch + ---> + Step 2/4 : MAINTAINER First Last + ---> Running in 7238f35abcd0 + ---> ec5064287c60 + Removing intermediate container 7238f35abcd0 + Step 3/4 : ADD base.tar.xz / + ---> 2723b7d20716 + Removing intermediate container 16e3ed0df8da + Step 4/4 : CMD /bin/bash + ---> Running in efa893350647 + ---> 5414c3a12993 + Removing intermediate container efa893350647 + Successfully built 5414c3a12993 + Successfully tagged my-custom-clear-linux-container:latest #. List the newly created |CL| container image. - .. code-block:: console + .. code-block:: bash - # docker images + sudo docker images Example output: - .. code-block:: console + .. code-block:: console - # docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - my-custom-clear-linux-container latest 5414c3a12993 About a minute ago 616MB + REPOSITORY TAG IMAGE ID CREATED SIZE + my-custom-clear-linux-container latest 5414c3a12993 About a minute ago 616MB #. Launch the built |CL| container. - .. code-block:: console + .. code-block:: bash - # docker run -it my-custom-clear-linux-container + sudo docker run -it my-custom-clear-linux-container -Manage bundles in a Clear Linux based container -*********************************************** +Manage bundles in a container +***************************** -Bundles can be added and removed from an existing |CL| container by using -the `swupd` command in the Dockerfile. +You can add and remove bundles from a |CL| container using the +:command:`RUN swupd` command in the Dockerfile. -Add a bundle (`swupd bundle-add`) ---------------------------------- +Add a bundle +============ -This example Dockerfile shows how to add the `pxe-server` bundle to the -previously created |CL| Docker image: +This example Dockerfile adds the :file:`pxe-server` bundle to an existing |CL| +Docker image: - .. code-block:: console +.. code-block:: bash - # cat > Dockerfile << EOF - FROM my-customer-clear-linux-container - MAINTAINER First Last - RUN swupd bundle-add pxe-server - CMD ["/bin/bash/bash"] - EOF + sudo cat > Dockerfile << EOF + FROM my-customer-clear-linux-container + MAINTAINER First Last + RUN swupd bundle-add pxe-server + CMD ["/bin/bash/bash"] + EOF - Example output: +Example output: - .. code-block:: console +.. code-block:: console - # docker build -t my-clearlinux-with-pxe-server-bundle . + sudo docker build -t my-clearlinux-with-pxe-server-bundle . - Sending build context to Docker daemon 806.5MB - Step 1/4 : FROM my-custom-clear-linux-container - ---> 5414c3a12993 - Step 2/4 : MAINTAINER First Last - ---> Running in 19b4411cf4bd - ---> 08d400baffde - Removing intermediate container 19b4411cf4bd - Step 3/4 : RUN swupd bundle-add pxe-server - ---> Running in 3e634d6e0792 - swupd-client bundle adder 3.12.2 - Copyright (C) 2012-2017 Intel Corporation + Sending build context to Docker daemon 806.5MB + Step 1/4 : FROM my-custom-clear-linux-container + ---> 5414c3a12993 + Step 2/4 : MAINTAINER First Last + ---> Running in 19b4411cf4bd + ---> 08d400baffde + Removing intermediate container 19b4411cf4bd + Step 3/4 : RUN swupd bundle-add pxe-server + ---> Running in 3e634d6e0792 + swupd-client bundle adder 3.12.2 + Copyright (C) 2012-2017 Intel Corporation - Attempting to download version string to memory - Downloading packs... + Attempting to download version string to memory + Downloading packs... - Extracting pxe-server pack for version 17820 - . - Installing bundle(s) files... - .............................................................................. - .............................................................................. - .............................................................................. - .............................................................................. - .............................................................................. - .............................................................................. - Calling post-update helper scripts. - WARNING: systemctl not operable, unable to run systemd update triggers - Bundle(s) installation done. - ---> 8ead5f2c0c33 - Removing intermediate container 3e634d6e0792 - Step 4/4 : CMD /bin/bash - ---> Running in 0ceae320279b - ---> dcd9adb40611 - Removing intermediate container 0ceae320279b - Successfully built dcd9adb40611 - Successfully tagged my-clearlinux-with-pxe-server-bundle:latest + Extracting pxe-server pack for version 17820 + . + Installing bundle(s) files... + .............................................................................. + .............................................................................. + .............................................................................. + .............................................................................. + .............................................................................. + .............................................................................. + Calling post-update helper scripts. + WARNING: systemctl not operable, unable to run systemd update triggers + Bundle(s) installation done. + ---> 8ead5f2c0c33 + Removing intermediate container 3e634d6e0792 + Step 4/4 : CMD /bin/bash + ---> Running in 0ceae320279b + ---> dcd9adb40611 + Removing intermediate container 0ceae320279b + Successfully built dcd9adb40611 + Successfully tagged my-clearlinux-with-pxe-server-bundle:latest - .. note:: +.. note:: - This `WARNING` message is expected and can be ignored because Systemd - doesn't run inside a container. + The `WARNING` message can be ignored because systemd does not run inside + a container. -Remove a bundle (`swupd bundle-remove`) ---------------------------------------- -This example Dockerfile shows how to remove the `pxe-server` bundle from the -previously created |CL| Docker image: +Remove a bundle +=============== - .. code-block:: console +This example Dockerfile removes the :file:`pxe-server` bundle from an existing +|CL| Docker image: - # cat > Dockerfile << EOF - FROM my-clearlinux-with-pxe-server-bundle - MAINTAINER First Last - RUN swupd bundle-remove pxe-server - CMD ["/bin/bash/bash"] - EOF +.. code-block:: bash - Example output: + sudo cat > Dockerfile << EOF + FROM my-clearlinux-with-pxe-server-bundle + MAINTAINER First Last + RUN swupd bundle-remove pxe-server + CMD ["/bin/bash/bash"] + EOF - .. code-block:: console +Example output: - # docker build -t my-clearlinux-remove-pxe-server-bundle . +.. code-block:: console - Sending build context to Docker daemon 806.5MB - Step 1/4 : FROM my-clearlinux-with-pxe-server-bundle - ---> dcd9adb40611 - Step 2/4 : MAINTAINER First Last - ---> Running in 71b60f15003e - ---> 742192751c1a - Removing intermediate container 71b60f15003e - Step 3/4 : RUN swupd bundle-remove pxe-server - ---> Running in ad28a3390ecc - swupd-client bundle remover 3.12.2 - Copyright (C) 2012-2017 Intel Corporation + sudo docker build -t my-clearlinux-remove-pxe-server-bundle . - Removing bundle: pxe-server - Deleting bundle files... - Total deleted files: 92 - Untracking bundle from system... - Success: Bundle removed - 1 bundle(s) were removed successfully - ---> d6ee7903e14d - Removing intermediate container ad28a3390ecc - Step 4/4 : CMD /bin/bash - ---> Running in 7694989e97de - ---> ec23189ef954 - Removing intermediate container 7694989e97de - Successfully built ec23189ef954 - Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest + Sending build context to Docker daemon 806.5MB + Step 1/4 : FROM my-clearlinux-with-pxe-server-bundle + ---> dcd9adb40611 + Step 2/4 : MAINTAINER First Last + ---> Running in 71b60f15003e + ---> 742192751c1a + Removing intermediate container 71b60f15003e + Step 3/4 : RUN swupd bundle-remove pxe-server + ---> Running in ad28a3390ecc + swupd-client bundle remover 3.12.2 + Copyright (C) 2012-2017 Intel Corporation -Also see: + Removing bundle: pxe-server + Deleting bundle files... + Total deleted files: 92 + Untracking bundle from system... + Success: Bundle removed + 1 bundle(s) were removed successfully + ---> d6ee7903e14d + Removing intermediate container ad28a3390ecc + Step 4/4 : CMD /bin/bash + ---> Running in 7694989e97de + ---> ec23189ef954 + Removing intermediate container 7694989e97de + Successfully built ec23189ef954 + Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest - * :ref:`cc-getting-started` +For more details, refer to: + +* :ref:`cc-getting-started` +* :ref:`architecture-overview`