diff --git a/source/_static/userguide/container-preloading/container-preloading-apps.png b/source/_static/userguide/container-preloading/container-preloading-apps.png deleted file mode 100644 index b691a9271..000000000 Binary files a/source/_static/userguide/container-preloading/container-preloading-apps.png and /dev/null differ diff --git a/source/_static/userguide/container-preloading/container-preloading-image.png b/source/_static/userguide/container-preloading/container-preloading-image.png deleted file mode 100644 index a393dba59..000000000 Binary files a/source/_static/userguide/container-preloading/container-preloading-image.png and /dev/null differ diff --git a/source/_static/userguide/container-preloading/container-preloading-new-target.png b/source/_static/userguide/container-preloading/container-preloading-new-target.png index b90fb003e..f751ce929 100644 Binary files a/source/_static/userguide/container-preloading/container-preloading-new-target.png and b/source/_static/userguide/container-preloading/container-preloading-new-target.png differ diff --git a/source/_static/userguide/container-preloading/container-preloading-platform-image.png b/source/_static/userguide/container-preloading/container-preloading-platform-image.png deleted file mode 100644 index 437419983..000000000 Binary files a/source/_static/userguide/container-preloading/container-preloading-platform-image.png and /dev/null differ diff --git a/source/_static/userguide/container-preloading/container-preloading-platform.png b/source/_static/userguide/container-preloading/container-preloading-platform.png index fe9e9ff23..82cd5a7d4 100644 Binary files a/source/_static/userguide/container-preloading/container-preloading-platform.png and b/source/_static/userguide/container-preloading/container-preloading-platform.png differ diff --git a/source/_static/userguide/container-preloading/container-preloading-target.png b/source/_static/userguide/container-preloading/container-preloading-target.png deleted file mode 100644 index 15c24e8a3..000000000 Binary files a/source/_static/userguide/container-preloading/container-preloading-target.png and /dev/null differ diff --git a/source/user-guide/account-management/subscription-and-billing.rst b/source/user-guide/account-management/subscription-and-billing.rst index 80beb7186..b79254c50 100644 --- a/source/user-guide/account-management/subscription-and-billing.rst +++ b/source/user-guide/account-management/subscription-and-billing.rst @@ -1,17 +1,17 @@ .. _ref-subscription-and-billing: -Managing your Subscription +Managing Your Subscription ========================== .. hint:: - FoundriesFactory is a DevSecOps platform subscription service. + FoundriesFactory® is a DevSecOps platform subscription service. Per month or annual plan choices, both provide access to all FoundriesFactory features and support. Subscriptions apply per Factory; if you have *Factories*, you will manage them separately. -Changing your Plan +Changing Your Plan ------------------ From your Factory's page, navigate to the :guilabel:`Plan` tab. @@ -44,7 +44,7 @@ For using other forms of payment, please `contact us ` covers available scopes. + The FoundriesFactory® :ref:`API documentation` covers available scopes. Larger organizations often need to restrict the access level a user has to the Factory. For example, some users might only need access for managing devices, @@ -28,9 +28,8 @@ See :ref:`Access to Device Groups` for more details. It may take a moment for changes to scope/teams to take effect. Teams can be created by anyone with either the **Owner** or **Admin** role. -Additionally, these roles are granted read-write operations for all Factory resources by default, -but when checking user scope with ``fioctl users `` , -it will return blank unless they are part of a team. +While these roles are granted read-write operations for all Factory resources by default, +checking user scope with ``fioctl users `` will return blank unless they are part of a team. Members with devices may manage their own with read-write access. .. tip:: @@ -63,12 +62,12 @@ Team "read-write-ci" can do CI read-write operations: .. figure:: /_static/teams-example-read-only.png :align: center :scale: 80% - :alt: Teams example - Team read-only users + :alt: Teams example: Team read-only users .. figure:: /_static/teams-example-read-write-ci.png :align: center :scale: 80% - :alt: Teams example - Team read-write CI users + :alt: Teams example: Team read-write CI users A member is then added to both teams. The member then has a combined list of scopes: @@ -128,7 +127,7 @@ Example A Factory has two teams in place and one device group, ``test-lab-devices``. -Members of the "read-only-users" team have read-only access to all factory resources with one exception - device groups and devices. +Members of the "read-only-users" team have read-only access to all factory resources with one exception—device groups and devices. They can see only the ``test-lab-devices`` group and devices included into it. diff --git a/source/user-guide/container-preloading/container-preloading.rst b/source/user-guide/container-preloading/container-preloading.rst index eda9b2e6f..c785b58b0 100644 --- a/source/user-guide/container-preloading/container-preloading.rst +++ b/source/user-guide/container-preloading/container-preloading.rst @@ -3,33 +3,30 @@ Container Preloading ==================== -This section guides you to configure your ``platform`` images to preload Docker Compose Apps. +This guide covers configuring your ``platform`` images to preload Docker Compose Apps. -By default, the ``platform`` build creates an image to be flashed to a device that -doesn't include Docker Compose Apps. After installing the image and registering -the device, ``aktualizr-lite`` downloads and runs the configured apps. +By default, the ``platform`` build creates an image to be flashed to a device—that does not include Docker Compose Apps. +Then, after installing the image and registering the device, ``aktualizr-lite`` downloads and runs the configured Apps. -There are cases where having applications preloaded on the image can be helpful, such as: +Cases where having Apps preloaded on the image can be helpful include: -- Executing a Docker Compose App right after the first boot, even without internet or registering the device. +- Executing a Docker Compose App right after first boot, even without internet or registering the device. - Reducing network data usage during the Docker Image download. -.. note:: +.. warning:: - Preloading container images will increase the size of the system image - considerably, especially if the containers have not been optimally - constructed. + Preloading container images will increase the size of the system image considerably, + especially if the containers have not been optimally constructed. - Refer to the official Docker documentation for best practices - on writing Dockerfiles: - https://docs.docker.com/develop/develop-images/dockerfile_best-practices/ + Refer to the official Docker documentation for + `best practices on writing Dockerfiles `_. There are two ways to create these images: * :ref:`fioctl targets image` * configuring ``ci-scripts`` to preload each build -Here we focus on the second approach so every Target includes a flashable image with preloaded containers. +Here we focus on the second approach, so that every Target includes a flashable image with preloaded containers. Configure the CI ---------------- @@ -41,11 +38,10 @@ Clone your ``ci-scripts`` repo and enter its directory: git clone https://source.foundries.io/factories//ci-scripts.git cd ci-scripts -Edit the ``factory-config.yml`` file and add the configuration below: - -**factory-config.yml**: +Add the following to ``factory-config.yml``, +making sure to set the appropriate values for ``app_type`` and ``oe_builtin`` (see below): -.. prompt:: text +.. code-block:: YAML containers: preloaded_images: @@ -54,17 +50,21 @@ Edit the ``factory-config.yml`` file and add the configuration below: shortlist: "shellhttpd" oe_builtin: -- ``enabled`` - Whether to produce an archive containing docker images as part of a container build trigger. -- ``shortlist`` - Defines the list of apps to preload. All Target's apps are preloaded if it is not specified or its value is empty. Here, it is set to preload the ``shellhttpd`` app. -- ``app_type`` - Defines a type of Apps to preload. - If an option is not defined or set to an empty value, the ``app_type`` preload will depend on the LmP version. If the LmP version is equal to or higher than **v85**, then `restorable` type is preloaded, otherwise `compose` type. +- ``enabled``- Whether to produce an archive containing Docker images as part of a container build trigger. +- ``shortlist``- Defines the list of apps to preload. + All the Target's apps are preloaded if not specified or empty. + Here, it is set to preload the ``shellhttpd`` app. +- ``app_type`` - Defines the type of Apps to preload. + If not defined, or set to an empty value, the ``app_type`` preload will depend on the LmP version. + If the LmP version is **v85** or newer, then `restorable` type is preloaded, otherwise `compose` type is used. See :ref:`ug-restorable-apps` for more details on Restorable Apps. - ``oe_builtin`` - *Optional*: Preload Apps during an OE build CI run. Should be left disabled/undefined for most machines. .. note:: - The ``oe_builtin`` is a special preloading case where Apps are preloaded during an OE build CI run, rather than preloaded by the `assemble` run of a LmP CI build. This is needed when the image produced by the LmP build is not a WIC image. + ``oe_builtin`` is a special preloading case where Apps are preloaded during an OE build, rather than by the `assemble` run of a LmP build. + This is needed when the image produced is not a WIC image. - In this case, rootfs as well as a system image produced by the run include preloaded Apps. + In this case, rootfs and the system image will include preloaded Apps. Only `Restorable` type of Apps (default) are supported by the OE builtin preloader. @@ -80,25 +80,20 @@ Add the ``factory-config.yml`` file, commit and push: Getting a New Image with Preloaded Containers ---------------------------------------------- -After these steps, when a ``platform`` or ``containers`` build finishes, it will -generate a ``.wic.gz`` file in :guilabel:`Runs`, ``assemble-system-image`` , ```` folder, with the preloaded Docker Images. +After these steps, a ``platform`` or ``containers`` build will generate a ``.wic.gz`` file with the preloaded Docker Images under +:guilabel:`Runs`, ``assemble-system-image`` , ````. -For example, pushing to ``containers-devel`` after this change triggers the usual build and an additional run called ``assemble-system-image``. Check the latest **Target** named ``containers-devel`` you just created: +For example, pushing to ``main`` triggers the usual build and an additional run called ``assemble-system-image``. +Check the latest Target you just created: .. figure:: /_static/userguide/container-preloading/container-preloading-new-target.png :width: 900 :align: center - FoundriesFactory New Target - -When FoundriesFactory CI finishes all jobs, click in the **Target**, find :guilabel:`Runs` and download the image from ``assemble-system-image``: - -.. figure:: /_static/userguide/container-preloading/container-preloading-image.png - :width: 900 - :align: center - - FoundriesFactory New Containers Image + New Target +When the FoundriesFactory® CI finishes, click Target. +Find :guilabel:`Runs` and download the image from ``assemble-system-image``. Flash the image and boot the device. .. note:: @@ -110,39 +105,39 @@ Flash the image and boot the device. Checking the Preloaded Image ---------------------------- -app_type: restorable -~~~~~~~~~~~~~~~~~~~~ +Restorable Type +~~~~~~~~~~~~~~~ Restorable apps are enabled by default on LmP v85+. -On your device, switch to root and list the files in the folder -``/var/sota/reset-apps``. +On your device, switch to root and list the files in the folder ``/var/sota/reset-apps``. .. prompt:: bash device:~$ sudo su ls /var/sota/reset-apps/apps -.. prompt:: text +.. code-block:: text app-05 app-07 app-08 -Preloaded Restorable Apps should be listed in the output, provided that the preloading was successful. In this case, the preloaded apps are ``app-05``, ``app-07`` and ``app-08``. +Preloaded Restorable Apps are listed in the output, provided that the preloading was successful. +In this case, the preloaded apps are ``app-05``, ``app-07`` and ``app-08``. -Another option to verify whether Restorable Apps are preloaded is to use `aklite-apps` utility. +Another option to verify whether Restorable Apps are preloaded is to use the `aklite-apps` utility. .. prompt:: bash device:~$ sudo su aklite-apps ls -.. prompt:: text +.. code-block:: text app-05 app-07 app-08 -A user can try to start preloaded Restorable Apps manually by using `aklite-apps` utility. +Try to start the preloaded Restorable Apps manually using `aklite-apps`: .. prompt:: bash device:~$ @@ -150,7 +145,9 @@ A user can try to start preloaded Restorable Apps manually by using `aklite-apps aklite-apps run [--apps ] .. note:: - ``app_type`` is set to ``restorable`` by default since LmP **v85**. If ``compose`` app type is set, then the preloaded apps are located under ``/var/sota/compose-apps/``. Here is an example using ``shellhttpd`` preloaded app: + ``app_type`` is set to ``restorable`` by default since LmP **v85**. + If ``compose`` app type is set, then the preloaded apps are located under ``/var/sota/compose-apps/``. + Here is an example using ``shellhttpd`` preloaded app: .. prompt:: bash device:~$ @@ -161,9 +158,8 @@ A user can try to start preloaded Restorable Apps manually by using `aklite-apps Starting Compose Apps Automatically ----------------------------------- -To start the preloaded application automatically after the boot and before -the device registration when aktualizr-lite starts, you have to enable a systemd service -responsible for it. +To start the preloaded application automatically between the boot and the device registration when aktualizr-lite starts, +enable a systemd service responsible for it. meta-lmp_ provides a recipe that launches preloaded apps after the device boots. @@ -171,14 +167,12 @@ Clone your ``meta-subscriber-overrides.git`` repo and enter its directory: .. prompt:: bash host:~$ - git clone -b devel https://source.foundries.io/factories//meta-subscriber-overrides.git + git clone https://source.foundries.io/factories//meta-subscriber-overrides.git cd meta-subscriber-overrides Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe to the ``CORE_IMAGE_BASE_INSTALL`` list: -**recipes-samples/images/lmp-factory-image.bb**: - -.. prompt:: text +.. code-block:: diff diff --git a/recipes-samples/images/lmp-factory-image.bb b/recipes-samples/images/lmp-factory-image.bb --- a/recipes-samples/images/lmp-factory-image.bb @@ -199,35 +193,28 @@ Add the ``recipes-samples/images/lmp-factory-image.bb`` file, commit and push: host:~$ git commit -m "compose-apps-early-start: Adding recipe" recipes-samples/images/lmp-factory-image.bb host:~$ git push -The latest **Target** named ``platform-devel`` should be the CI job you just created. +The latest Target should be the CI job you just created. .. figure:: /_static/userguide/container-preloading/container-preloading-platform.png :width: 900 :align: center - FoundriesFactory New Platform Target - -When FoundriesFactory CI finishes all jobs, click in the **Target**, find :guilabel:`Runs` and download the image from the ``assemble-system-image`` run: - -.. figure:: /_static/userguide/container-preloading/container-preloading-platform-image.png - :width: 900 - :align: center - - FoundriesFactory Platform Image + New Platform Target +When the FoundriesFactory CI finishes, click on the Target. +Find :guilabel:`Runs` and download the image from the ``assemble-system-image`` run. Flash the image and boot the device. Testing Auto Start ------------------ -On your device, use the following command to list the ``compose-apps-early-start`` -service: +On your device, list the ``compose-apps-early-start`` service: .. prompt:: bash device:~$ systemctl list-unit-files | grep enabled | grep compose-apps-early-start -.. prompt:: text +.. code-block:: text compose-apps-early-start.service enabled enabled @@ -237,7 +224,7 @@ Verify the ``compose-apps-early-start`` application status: device:~$ systemctl status compose-apps-early-start -.. prompt:: text +.. code-block:: text compose-apps-early-start.service - Ensure apps are configured and running as early> Loaded: loaded (/usr/lib/systemd/system/compose-apps-early-start.service; enabl> diff --git a/source/user-guide/custom-ci/custom-ci-for-apps.rst b/source/user-guide/custom-ci/custom-ci-for-apps.rst index b0824c61f..2c5d85cfd 100644 --- a/source/user-guide/custom-ci/custom-ci-for-apps.rst +++ b/source/user-guide/custom-ci/custom-ci-for-apps.rst @@ -5,92 +5,85 @@ Custom CI To Build Compose App Targets ====================================== -FoundriesFactory includes all you need to build a containerized application and securely deploy it on devices. -In particular, it provides you with a git repository and the CI service that does all the necessary steps to build and delivery apps by leveraging the TUF compliant OTA service. -You can learn more details about it by going through this :ref:`tutorial `. +FoundriesFactory® includes all you need to build a containerized application and securely deploy it on devices. +This includes: -The FoundriesFactory solution consists of a few loosely coupled services. -It allows using the FoundriesFactory OTA framework directly, eliminating the need to host -your App source code in the FoundriesFactory git repository and using the FoundriesFactory CI service. -Therefore, you can host your App in any source code repository and build App by any other framework, -yet still leverage the rest part of FoundriesFactory. +* a git repository +* a CI service that handles the steps to build and delivery apps leveraging the TUF compliant OTA service. + +You can learn more through this :ref:`tutorial `. + +FoundriesFactory consists of well integrated but loosely coupled services. +This allows for using the FoundriesFactory OTA framework directly, without using either FoundriesFactory git repos or the CI service. +This means you can host your source code anywhere, and build your App through any framework, and still leverage the rest of FoundriesFactory. This section guides you through the steps of creating a custom CI pipeline in GitHub that: - builds multi-arch container images and pushes them to `FoundriesFactory Registry`_; -- builds `FoundriesFactory Compose App`_ and pushes it to the `FoundriesFactory Registry`_; +- builds a `FoundriesFactory Compose App`_ and pushes it to the `FoundriesFactory Registry`_; - composes `TUF Targets role metadata`_ compliant with FoundriesFactory TUF requirements; - adds the composed TUF Targets to `FoundriesFactory Targets`_. Prerequisites ------------- -1. Your Factory has been successfully created. - -2. At least one successful Factory CI build and the corresponding Target with the tag and a hardware ID that you will use in the following guide. +#. A successful build with a corresponding Target and tag, and the hardware ID, to use for this guide. -3. You have a GitHub repo with source code, Dockerfiles, and a Docker compose file that work. +#. A GitHub repo with source code, Dockerfiles, and a Docker compose file. Below is an example of how the prerequisites would look like: -1. Factory ``lmp-demo`` is setup and has been successfully created. -2. The successfully built Target with the tag ``custom-ci-devel`` and the hardware ID ``raspberrypi4-64``. +1. Factory ``lmp-demo`` with a successfully built Target having the tag ``custom-ci-devel`` and the hardware ID ``raspberrypi4-64``. - .. prompt:: text + .. code-block:: bash Fioctl targets show 1 -f lmp-demo APP HASH --- ---- ## Target: raspberrypi4-64-lmp-1 - Created: 2022-11-30T00:20:31Z - Tags: custom-ci-devel - OSTree Hash: fe15cf8ad5e09136725ef996c93299d70fa0d20bfa2f10651437b8860b9edcdb + Created: 2022-11-30T00:20:31Z + Tags: custom-ci-devel + OSTree Hash: fe15cf8ad5e09136725ef996c93299d70fa0d20bfa2f10651437b8860b9edcdb 3. `The GitHub repo`_ that contains a working App implementation. -Creating And Setting the Access Token --------------------------------------- - -The GitHub action needs to authenticate itself at the FoundriesFactory OTA service and the `FoundriesFactory Registry`_. -Therefore, an access token must be created and added to the GitHub repo action tokens prior to running any CI pipelines. -You can create the token at `FoundriesFactory WebApp`_. -The token must have ``containers:read-update`` and ``targets:read-update`` scopes to access the registry and the OTA service correspondingly. +Creating And Setting the Access Token +------------------------------------- +The GitHub action needs to be authentication for the FoundriesFactory OTA service and the `FoundriesFactory Registry`_. +You can create the token to add to the GitHub action via the `FoundriesFactory WebApp`_. +The token must have ``containers:read-update`` and ``targets:read-update`` scopes to access the registry and the OTA service, respectively. Set Token in GitHub Repo ------------------------ -Go to ``https://github.com/foundriesio//settings/secrets/actions`` and add a secret named ``FIO_TOKEN`` -and the value of the token obtained in the previous step. +Go to ``https://github.com/foundriesio//settings/secrets/actions`` and add a secret named ``FIO_TOKEN`` with the value of the token obtained in the previous step. Define GitHub Actions Workflow ------------------------------ The next step is to define a GitHub actions workflow in your repo or extend an existing one. -`The sample GitHub actions workflow`_ provides an example of the workflow that communicates with FoundriesFactory to achieve the goal, -i.e. the items listed at the end of :ref:`the introductory section`. +`The sample GitHub actions workflow`_ demonstrates a workflow that communicates with FoundriesFactory to achieve the `goals ` of this guide. The workflow does the following: 1. Builds and pushes images to the registry. -2. Stores the built image URIs (must be digest/hashed reference) so they can be referred from the App compose project. -3. Builds and pushes Compose App by utilizing Foundries utility `compose-publish`_. -4. Composes and posts new Target(s) that refers to the App built in the step 3. The ``fioctl targets add`` command is utilized to accomplish it. - +2. Stores the built image URIs (must be digest/hashed references) so they can be referenced from the App compose project. +3. Builds and pushes the Compose App by utilizing the `compose-publish`_ utility. +4. Composes and posts new Target(s) that references the App built in step 3. + The ``fioctl targets add`` command is utilized to accomplish it. Learn App Repo Structure Details -------------------------------- It is important to understand the structure of the sample App before creating your own App and CI job that communicates with the FoundriesFactory services. -Docker files and build directories of the container images are located in sub-directories of ``/docker``. +Docker files and build directories for the container images are located in sub-directories of ``/docker``. The name of each sub-directory corresponds to a container image name. -The compose project definition refers to the container images defined in the repository and built by the given CI job -by the following reference ``hub.foundries.io/lmp-demo/``. +The compose project definition refers to the container images defined in the repo, and built by the CI job with the reference ``hub.foundries.io/lmp-demo/``. -The App compose file and supplementary files (if any) are placed under ``/compose/`` directory. -The container images hosted in the same repo as the given App and built by the repo CI job should be referred -in the compose file without any tag or hash, e.g. ``image: hub.foundries.io/lmp-demo/ha-app``. -Container images that are not hosted in the given repo (``external``) and are not built by the given CI job must be referenced with a tag or a hash, e.g. ``image: ghcr.io/home-assistant/home-assistant:2022.11.4``. +The App compose file and any supplementary files are placed under the ``/compose/`` directory. +The container images in the same repo as the App, built by the repo CI job, should be referenced in the compose file *without* any tag or hash, e.g., ``image: hub.foundries.io/lmp-demo/ha-app``. +Container images that are not hosted in the given repo (``external``), and not built by the CI job, must be referenced *with* a tag or a hash, e.g. ``image: ghcr.io/home-assistant/home-assistant:2022.11.4``. FoundriesFactory Utilities: Usage Details ----------------------------------------- @@ -99,27 +92,28 @@ The `compose-publish`_ CLI utility does the following: 1. Pins images referenced from the App compose file. a) If an image is already pinned (digest, a reference with sha256 hash) it does nothing. - b) If an image is referred by a tag it tries to get the image digest — a reference with sha256 hash. If it fails to obtain an image digest then the utility exists with an error. - c) If an image reference has not tag nor hash it checks if it's specified via ``--pinned-images`` input parameter. If no digest reference is found in ``pinned-images`` the utility exists with an error. + b) If an image is referred by a tag it tries to get the image digest—a reference with sha256 hash. + If it fails to obtain an image digest, the utility exists with an error. + c) If an image reference has no tag or hash, it checks if the digest is specified via the ``--pinned-images`` parameter. + If not found, the utility exists with an error. 2. Creates the compose App container image. - a) Creates an archive (``tgz``) that contains the App compose file and its supplementary files. - b) Creates a container image manifest referring to the App archive as an image layer/blob. + a) Creates an archive (``tgz``) containing the App compose file and any supplementary files. + b) Creates a container image manifest referencing the App archive as an image layer/blob. 3. Pushes the App container image to the `FoundriesFactory Registry`_. -The utility outputs the built and pushed App image digest to the file specified via ``-d`` input parameter. -Then the published App can be referenced with a hashed URI — ``hub.foundries.io//@sha256:``. +The utility outputs the built and pushed App image digest to the file specified via ``-d``. +The published App can now be referenced with a hashed URI — ``hub.foundries.io//@sha256:``. Once the App is successfully built and pushed to the registry, a new Target referring to it can be created. -To do so the Fioctl® command ``fioctl targets add`` should be used. +Use the Fioctl® command ``fioctl targets add`` to do so. -Check The Workflow Result +Check the Workflow Result ------------------------- -Use ``fioctl targets list`` and ``fioctl targets show`` commands to check whether the new Targets are registered in the FoundriesFactory OTA service -and whether their content is correct. +Use ``fioctl targets list`` and ``fioctl targets show`` to check whether the new Targets are registered in the FoundriesFactory OTA service, and whether their content is correct. .. note:: @@ -129,7 +123,6 @@ and whether their content is correct. 1. :ref:`Git Mirroring ` 2. :ref:`Git Submodules ` - .. seealso:: :ref:`ug-custom-ci-for-rootfs` diff --git a/source/user-guide/custom-ci/custom-ci-for-rootfs.rst b/source/user-guide/custom-ci/custom-ci-for-rootfs.rst index e054a2985..c348935ce 100644 --- a/source/user-guide/custom-ci/custom-ci-for-rootfs.rst +++ b/source/user-guide/custom-ci/custom-ci-for-rootfs.rst @@ -1,81 +1,85 @@ .. _ug-custom-ci-for-rootfs: -Custom CI For RootFS +Custom CI for RootFS ==================== -FoundriesFactory includes all you need to build a Linux-based operating system and securely deploy it on devices. -In particular, it provides you with a git repository and the CI service that does all the necessary steps -to build the Linux kernel and rootfs out of source code and deliver them to devices by leveraging the TUF compliant OTA service. -You can learn more details about it by reading the :ref:`reference ` section. +FoundriesFactory® includes all you need to build a Linux®-based operating system and securely deploy it. +In particular, it provides you with a git repo and a CI service that handles building the kernel and rootfs, and delivering them to devices. +This is done while leveraging the TUF compliant OTA service. +You can learn more in the :ref:`reference ` section. -In some cases you may need to build your system image and deploy it on devices by means of the FoundriesFactory OTA service without using the FoundriesFactory CI service. -The following guide walks you through the steps to accomplish just that. +In some cases, you want to build your system image and deploy it via the FoundriesFactory OTA service **without** using the CI service. +This guide walks you through the steps to accomplish this. Prerequisites ------------- -1. Your Factory has been successfully created. - -2. At least one successful Factory CI build and the corresponding Target with the tag and a hardware ID that you will use in the following guide. +#. A successful CI build, and a corresponding Target with the tag and hardware ID to use for the following. Bitbake ------- -Use the :ref:`lmp-sdk container` (aka dev container) to bitbake a system image and/or an ostree repo that contains an OTA-updatable part for rootfs. +Use the :ref:`lmp-sdk container` (aka dev container) to bitbake a system image or an ostree repo that contains an OTA-updatable part for rootfs. -Disable the steps that are FoundriesFactory CI specific, i.e. add the following to ``conf/local.conf`` +1. Disable FoundriesFactory CI specific steps. + Add the following to ``conf/local.conf``: -.. prompt:: text + .. prompt:: text - IMAGE_FSTYPES:remove = "ostreepush garagesign garagecheck" + IMAGE_FSTYPES:remove = "ostreepush garagesign garagecheck" -2. Run the following to bitbake both a system image (if flashing of a device is needed) and the ostree repo. +2. Run the following to build a system image (if flashing of a device is needed) and the ostree repo: -.. prompt:: text + .. prompt:: text - bitbake lmp-factory-image + bitbake lmp-factory-image -3. Run the following to bitbake just the ostree repo. +3. To bitbake just the ostree repo: -.. prompt:: text + .. prompt:: text - bitbake lmp-factory-image -c do_image_ostreecommit + bitbake lmp-factory-image -c do_image_ostreecommit -As a result, you should get an ostree repo that contains a rootfs to deliver to your devices via the OTA service. For example: +You should now have an ostree repo that contains a rootfs to deliver to your devices via the OTA service. For example: -.. prompt:: text + .. code-block:: bash - ./deploy/images/intel-corei7-64/ostree_repo + ./deploy/images/intel-corei7-64/ostree_repo Push OSTree Repo To Cloud ------------------------- -The :ref:`ref-linux-dev-container` includes utilities called ``fiopush`` and ``fiocheck`` that pushes an ostree repo to the foundries multi-tenant storage based on GCS. -You need an auth token to run these commands. -The token can be obtained at `FoundriesFactory WebApp`_, and it should have ``targets:read-update`` scope. -Run ``fiopush -factory -repo ./deploy/images/intel-corei7-64/ostree_repo -token `` to push the bitbaked ostree repo to the FoundriesFactory storage. +The :ref:`ref-linux-dev-container` includes utilities called ``fiopush`` and ``fiocheck``. +These are used to push an ostree repo to the multi-tenant storage based on GCS. + +.. important:: + You need an auth token to run these commands. + The token can be obtained at `FoundriesFactory WebApp`_. + It should have ``targets:read-update`` scope. + +Run ``fiopush -factory -repo ./deploy/images/intel-corei7-64/ostree_repo -token `` to push the ostree repo to the FoundriesFactory storage. Add OSTree Target ----------------- -Once the ostree repo carrying rootfs is built and pushed to the cloud, a user can add a new Target referring to it. +Once the ostree repo carrying rootfs is pushed to the cloud, you can add a new Target referencing it. -The rootfs committed to the ostree repo is referred by the commit hash. -Run ``find ./deploy/images/intel-corei7-64/ostree_repo -name *.commit`` or ``ostree --repo ./deploy/images/intel-corei7-64/ostree_repo rev-parse `` -to obtain the hash. +The rootfs committed to the ostree repo is referenced by the commit hash. +To obtain, run ``find ./deploy/images/intel-corei7-64/ostree_repo -name *.commit`` +or ``ostree --repo ./deploy/images/intel-corei7-64/ostree_repo rev-parse ``. -Then, you can run ``fioctl targets add`` add new Target that references the given ostree-based rootfs, e.g., +Run ``fioctl targets add`` ato add the new Target referencing the given ostree-based rootfs, e.g., -.. prompt:: text +.. code-block:: bash fioctl targets add --type ostree --tags master,devel --src-tag master intel-corei7-64 094a6d77b7053f2fec1e5e4ccd83c38cb89174f644303c6bb09693648be98912 Check the OSTree Target ----------------------- -Use ``fioctl targets list`` and ``fioctl targets show`` commands to check whether the new Target is registered in the OTA service -and whether their content is correct. +Use ``fioctl targets list`` and ``fioctl targets show`` to check whether the new Target is registered with the OTA service, +and whether the content is correct. -If ``aktualizr-lite`` is configured for one of the new Target's tags, then it should be able to enlist and install the Target. +If ``aktualizr-lite`` is configured for one of the new Target's tags, then it is able to enlist and install the Target. .. prompt:: text @@ -83,7 +87,7 @@ If ``aktualizr-lite`` is configured for one of the new Target's tags, then it sh ... info: 1589 sha256:094a6d77b7053f2fec1e5e4ccd83c38cb89174f644303c6bb09693648be98912 -Then during the update one can see the log saying that aklite is downloading the expected ostree commit. +During the update, the log can show that aklite is downloading the expected ostree commit: .. prompt:: text @@ -93,4 +97,4 @@ Then during the update one can see the log saying that aklite is downloading the info: Active image is: 1589 sha256:00b2ad4a1dd7fe1e856a6d607ed492c354a423be22a44bad644092bb275e12fa .. _FoundriesFactory WebApp: - https://app.foundries.io/settings/tokens/ \ No newline at end of file + https://app.foundries.io/settings/tokens/ diff --git a/source/user-guide/custom-ci/custom-ci.rst b/source/user-guide/custom-ci/custom-ci.rst index ebb9452dd..1221e220b 100644 --- a/source/user-guide/custom-ci/custom-ci.rst +++ b/source/user-guide/custom-ci/custom-ci.rst @@ -3,26 +3,27 @@ Custom CI ========= -FoundriesFactory is like a Swiss Army knife that includes everything you need to manage the lifecycle of -a Linux-based operating system and the containerized applications running on it. In particular, it includes: +FoundriesFactory® is a Swiss Army knife. +It includes everything you need to manage the lifecycle of a Linux®-based OS with containerized applications running on it: -1. Git repositories for your operating system (OE layers/recipes) and containerized applications. -2. The CI service to build your operating system and containerized applications. -3. The TUF compliant OTA service to securely update the OS and the Apps on your devices. -4. Utilities to configure and manage the aforementioned services. + - Git repositories for your operating system (OE layers/recipes) and containerized applications. + - The CI service to build your operating system and containerized applications. + - The TUF compliant OTA service to securely update the OS and the Apps on your devices. + - Utilities to configure and manage the aforementioned services. -While it all works together like a charm, in some cases you may wanna use just some subsets of the provided services. -In particular, you may want to build OS and applications by yourself and still use the FoundriesFactory OTA service. -The following two guides walk you through the steps to accomplish it. +While it all works together like a charm, in some cases you may want to use only a subset of the services. +In particular, you may want to build the OS and applications yourself, while still using the FoundriesFactory OTA service. +The following guides walk you through the steps to accomplish this. -The :ref:`ug-custom-ci-for-rootfs` guide outlines steps to build an LmP-based OS image outside of the FoundriesFactory CI service -and how to use the OTA service to update the OS on devices. +:ref:`ug-custom-ci-for-rootfs` outlines building an LmP image outside of the FoundriesFactory CI service, +and how to use the OTA service to update the OS. -The :ref:`ug-custom-ci-for-apps` guide provides an example of building containerized applications in a GitHub workflow along with -the OTA service usage to update applications on devices. +:ref:`ug-custom-ci-for-apps` provides an example of building containerized Apps in a GitHub workflow, +along with the OTA service usage to update Apps on devices. .. toctree:: :maxdepth: 1 custom-ci-for-rootfs custom-ci-for-apps + diff --git a/source/user-guide/custom-sota-client.rst b/source/user-guide/custom-sota-client.rst index 7747d7703..985635642 100644 --- a/source/user-guide/custom-sota-client.rst +++ b/source/user-guide/custom-sota-client.rst @@ -3,24 +3,20 @@ Custom Update Agents ==================== -This section shows how to create a custom update agent, "SOTA client" -for your platform. :ref:`ref-aktualizr-lite` is a general purpose -SOTA client that fits many needs. However, some types of products -require more control over the update agent than aktualizr-lite and -it's "hooks" system provides. In these cases, a custom SOTA client -can be written in C++ using the aktualizr-lite API_. +This section shows how to create a custom update agent—"SOTA client"—for your platform. +:ref:`ref-aktualizr-lite` is a general purpose SOTA client that fits many needs. +However, some cases require more control over the update agent than aktualizr-lite and the "hooks" system can provide. +In these cases, a custom SOTA client can be written in C++ using the aktualizr-lite API_. .. _API: https://github.com/foundriesio/aktualizr-lite/blob/master/include/aktualizr-lite/api.h - -Using the custom-sota-client Example +Using the Custom SOTA Client Example ------------------------------------ -We provide a `SOTA client`_ example in aktualizr-lite that serves as a great -starting place to experiment. The **meta-lmp** layer includes a recipe_ that -runs this example as the default SOTA client. Later, this serves as an example -to copy/paste into a Factory specific recipe. +The example `SOTA client`_ in aktualizr-lite is a great place to start experimenting. +The ``meta-lmp`` layer includes a recipe_ that runs this example as the default SOTA client. +Later, this can serve as an example to copy/paste into a Factory specific recipe. .. _recipe: https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-base/recipes-sota/custom-sota-client @@ -28,8 +24,7 @@ to copy/paste into a Factory specific recipe. .. _SOTA client: https://github.com/foundriesio/aktualizr-lite/tree/master/examples/custom-client-cxx -Users can build this custom client into their LmP image with a small addition -to ``meta-subscriber-overrides.git``: +Users can build this custom client into their LmP image with a small addition to ``meta-subscriber-overrides.git``: .. prompt:: bash host:~$ @@ -37,19 +32,17 @@ to ``meta-subscriber-overrides.git``: cd meta-subscriber-overrides echo 'SOTA_CLIENT = "custom-sota-client"' >> conf/machine/include/lmp-factory-custom.inc -Forking the custom-sota-client +Forking the custom SOTA Client ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Producing a factory-specific SOTA client can be done by: - #. Creating a Git repository for your custom code. Copying the - `examples/custom-client-cxx`_ directory is a good place to start. + #. Creating a Git repository for your custom code. + Copying the `examples/custom-client-cxx`_ directory is a good place to start. - #. Copying the `custom-sota-client`_ recipe from **meta-lmp** into - ``meta-subscriber-overrides/recipes-sota``. + #. Copying the `custom-sota-client`_ recipe from ``meta-lmp`` into ``meta-subscriber-overrides/recipes-sota``. - #. Changing the ``custom-sota-client_git.bb`` Git references (``SRC_URI``, - ``BRANCH``, ``SRCREV``) to point at your new sources. + #. Changing the ``custom-sota-client_git.bb`` Git references (``SRC_URI``, ``BRANCH``, ``SRCREV``) to point at your new sources. .. _examples/custom-client-cxx: https://github.com/foundriesio/aktualizr-lite/tree/master/examples/custom-client-cxx