diff --git a/source/_static/tutorials/working-with-tags/ci_jobs.png b/source/_static/tutorials/working-with-tags/ci_jobs.png deleted file mode 100644 index b869b7288..000000000 Binary files a/source/_static/tutorials/working-with-tags/ci_jobs.png and /dev/null differ diff --git a/source/tutorials/working-with-tags/adapting-shellhttpd.rst b/source/tutorials/working-with-tags/adapting-shellhttpd.rst index dabf239ca..985dc7803 100644 --- a/source/tutorials/working-with-tags/adapting-shellhttpd.rst +++ b/source/tutorials/working-with-tags/adapting-shellhttpd.rst @@ -1,27 +1,25 @@ Adapting Shellhttpd ^^^^^^^^^^^^^^^^^^^ -Edit the shellhttpd application back to its original state. +Edit ``shellhttpd`` back to its original state. .. tip:: In case you do not have the ``shellhttpd`` application. Complete the tutorial: :ref:`tutorial-creating-first-target` -Open a new terminal in your host machine and find the container folder used in the previous tutorial. +Open a new terminal on your host machine and go into your containers repo folder. .. prompt:: bash host:~$, auto host:~$ cd containers/ -Edit the file ``httpd.sh`` according to the example below: +Edit ``httpd.sh`` according to the example below: .. prompt:: bash host:~$, auto host:~$ gedit shellhttpd/httpd.sh -**shellhttpd/httpd.sh**: - .. prompt:: text #!/bin/sh -e @@ -42,8 +40,6 @@ Edit the file ``Dockerfile`` according to the example below: host:~$ gedit shellhttpd/Dockerfile -**shellhttpd/Dockerfile**: - .. prompt:: text FROM alpine @@ -58,8 +54,6 @@ Edit the file ``docker-compose.yml`` according to the example below: host:~$ gedit shellhttpd/docker-compose.yml -**shellhttpd/docker-compose.yml**: - .. prompt:: text version: '3.2' @@ -75,7 +69,7 @@ Edit the file ``docker-compose.yml`` according to the example below: Note that ``MSG`` is defined with ``This is the TEST 01``. -Commit and push all changes done in the ``containers`` folder: +Commit and push all changes: .. prompt:: bash host:~$, auto @@ -86,8 +80,8 @@ Commit and push all changes done in the ``containers`` folder: host:~$ git commit -m "This is the TEST 02" host:~$ git push -Wait for your build to finish by checking the latest **Target** on the :guilabel:`Devices` tab -in your Factory. +Wait for your build to finish by checking the latest Target on the :guilabel:`Devices` tab +for your Factory. Use ``fioctl`` to configure your device to run just the ``shellhttpd`` application: @@ -95,36 +89,30 @@ Use ``fioctl`` to configure your device to run just the ``shellhttpd`` applicati host:~$ fioctl devices config updates --apps shellhttpd -**Example Output**: - -.. prompt:: text +:: Changing apps from: [] -> [shellhttpd] Changing packagemanager to ostree+compose_apps -In a maximum of 2 minutes, your device should receive an update. +In a few minutes, your device should receive an update. -On your device, test the container again by running the following command: +On your device, test the container again: .. prompt:: bash device:~$, auto device:~$ wget -qO- 127.0.0.1:8080 -**Example Output**: - -.. prompt:: text +:: This is the TEST 01 -Check again the **Target** version list with ``fioctl`` +Check again the Target version list with ``fioctl`` .. prompt:: bash host:~$, auto host:~$ fioctl targets list -**Example Output**: - -.. prompt:: text +:: VERSION TAGS APPS HARDWARE IDs ------- ---- ---- ------------ @@ -138,20 +126,17 @@ Check again the **Target** version list with ``fioctl`` 9 devel mosquitto,shellhttpd,flask-mqtt-nginx,shellhttpd-mqtt raspberrypi3-64 10 devel mosquitto,shellhttpd,flask-mqtt-nginx,shellhttpd-mqtt raspberrypi3-64 -Check what **Target** your device is running: +Check what Target your device is running: .. prompt:: bash host:~$, auto host:~$ fioctl device list -**Example Output**: - -.. prompt:: text +:: NAME FACTORY TARGET STATUS APPS UP-TO-DATE ---- ------- ------ ------ ---- ---------- raspberrypi3-64-lmp-10 OK flask-mqtt-nginx,mosquitto,shellhttpd-mqtt true -Whenever you change the ``devel`` branch, FoundriesFactory CI will build -and generate a new **Target** tagged with ``devel``. As a result, devices following -``devel`` will update to the latest **Target**. +Whenever you push changes to the ``devel`` branch, FoundriesFactory® CI will build and generate a new Target tagged with ``devel``. +As a result, devices following ``devel`` will update to the latest Target. diff --git a/source/tutorials/working-with-tags/creating-targets.rst b/source/tutorials/working-with-tags/creating-targets.rst index 32573a2f8..2d18c9a11 100644 --- a/source/tutorials/working-with-tags/creating-targets.rst +++ b/source/tutorials/working-with-tags/creating-targets.rst @@ -1,25 +1,24 @@ Creating Targets ^^^^^^^^^^^^^^^^ -Let's simulate development in the branch ``devel``, as you change it, it -generates **Targets** tagged with ``devel`` and all devices following ``devel`` -receive updates. +Let's simulate regular development on the branch ``devel``. +Recall that as you commit changes, it generates Targets tagged with ``devel``. +Then all devices following the ``devel`` tag receive updates. -Imagine, you will keep developing on ``devel`` but you want to decide which -**Target** your device tagged with ``tutorial`` should update to. +Imagine that—while you will keep developing on ``devel`` —you want to decide which +Target your devices tagged with ``tutorial`` will receive. -The latest ``devel`` **Target** is also tagged with ``tutorial``. +.. hint:: + On the previous page we tagged the latest ``devel`` Target with the additional tag, ``tutorial``. -Change the ``shellhttpd`` application to create new **Target**: +Now to change the ``shellhttpd`` application to create new Target. -Edit the file ``docker-compose.yml`` according to the example below: +Edit ``docker-compose.yml``: .. prompt:: bash host:~$, auto host:~$ gedit shellhttpd/docker-compose.yml -**shellhttpd/docker-compose.yml**: - .. prompt:: text version: '3.2' @@ -35,7 +34,7 @@ Edit the file ``docker-compose.yml`` according to the example below: Note that ``MSG`` is defined with ``This is the TEST 02``. -Commit and push all changes done in the ``containers`` folder: +Commit and push the changes: .. prompt:: bash host:~$, auto @@ -46,18 +45,16 @@ Commit and push all changes done in the ``containers`` folder: Go to https://app.foundries.io, select your Factory and click on :guilabel:`Targets`: -The latest **Target** named :guilabel:`containers-devel` should be the CI job you just created. +The latest Target named :guilabel:`containers-devel` should be the CI job you just created. Wait until it finishes and change your application again. -Edit the file ``docker-compose.yml`` according to the example below: +Edit ``docker-compose.yml``: .. prompt:: bash host:~$, auto host:~$ gedit shellhttpd/docker-compose.yml -**shellhttpd/docker-compose.yml**: - .. prompt:: text version: '3.2' @@ -73,7 +70,7 @@ Edit the file ``docker-compose.yml`` according to the example below: Note that ``MSG`` is defined with ``This is the TEST 03``. -Commit and push all changes done in the ``containers`` folder: +Commit and push the changes: .. prompt:: bash host:~$, auto @@ -82,10 +79,9 @@ Commit and push all changes done in the ``containers`` folder: host:~$ git commit -m "This is the TEST 03" host:~$ git push -Keep watching your jobs on https://app.foundries.io and once it finishes change -your application one more time. +Keep watching your jobs on https://app.foundries.io and once it finishes, change your application one more time. -Edit the file ``docker-compose.yml`` according to the example below: +``docker-compose.yml``: .. prompt:: bash host:~$, auto @@ -108,7 +104,7 @@ Edit the file ``docker-compose.yml`` according to the example below: Note that ``MSG`` is defined with ``This is the TEST 04``. -Commit and push all changes done in the ``containers`` folder: +Commit and push the changes: .. prompt:: bash host:~$, auto @@ -117,7 +113,7 @@ Commit and push all changes done in the ``containers`` folder: host:~$ git commit -m "This is the TEST 04" host:~$ git push -Finally, you should have three new versions in the **Targets** version list. +Finally, you should have three new versions in the Targets version list. .. note:: diff --git a/source/tutorials/working-with-tags/following-specific-tag.rst b/source/tutorials/working-with-tags/following-specific-tag.rst index ef88f9445..a8c1b76aa 100644 --- a/source/tutorials/working-with-tags/following-specific-tag.rst +++ b/source/tutorials/working-with-tags/following-specific-tag.rst @@ -1,23 +1,20 @@ Following a Specific Tag ^^^^^^^^^^^^^^^^^^^^^^^^ -Before configuring a device to follow a specific tag, you must have at least one -**Target** tagged with the new tag. +Before configuring a device to follow a specific tag, you must have at least one Target tagged with the new tag. -Let's start tagging all **Targets** in the latest version with the tag ``devel`` and ``tutorial``. +Let's start tagging all Targets in the latest version with the tag ``devel`` *and* ``tutorial``. .. tip:: For tags, you may use the following characters: [a–z], [A–Z], [0–9], as well as `.`, `_`, `+`, and `-`. -Use ``fioctl`` on your host machine to list all **Target** versions: +Use ``fioctl`` on your host machine to list all Targets: .. prompt:: bash host:~$, auto host:~$ fioctl targets list -**Example Output**: - -.. prompt:: text +:: VERSION TAGS APPS HARDWARE IDs ------- ---- ---- ------------ @@ -37,9 +34,7 @@ Use ``fioctl`` to Tag version 10: host:~$ fioctl targets tag --by-version 10 -T devel,tutorial -**Example Output**: - -.. prompt:: text +:: [devel tutorial] Changing tags of raspberrypi3-64-lmp-10 from [devel] -> [devel tutorial] @@ -113,15 +108,13 @@ Use ``fioctl`` to Tag version 10: | | | | |_| |_| -Use ``fioctl`` again to list all **Target** versions: +Use ``fioctl`` again to list all Target versions: .. prompt:: bash host:~$, auto host:~$ fioctl targets list -**Example Output**: - -.. prompt:: text +:: VERSION TAGS APPS HARDWARE IDs ------- ---- ---- ------------ @@ -143,9 +136,7 @@ Change the device configuration to start following the ``tutorial`` tag: host:~$ fioctl devices config updates --tags tutorial -**Example Output**: - -.. prompt:: text +:: Changing tags from: [] -> [tutorial] Changing packagemanager to ostree+compose_apps diff --git a/source/tutorials/working-with-tags/inspecting-targets.rst b/source/tutorials/working-with-tags/inspecting-targets.rst index 343177821..1f52c3fda 100644 --- a/source/tutorials/working-with-tags/inspecting-targets.rst +++ b/source/tutorials/working-with-tags/inspecting-targets.rst @@ -1,24 +1,23 @@ -Inspecting your Factory Targets -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -At this point, your Factory could have a different number of builds/versions -comparing to the examples below. +Inspecting Factory Targets +^^^^^^^^^^^^^^^^^^^^^^^^^^ -To get started, inspect all your **Targets** you have created in your Factory. +At this point, your Factory could have a different number of builds/versions compared to the examples below. -Use ``fioctl`` on your host machine to list all **Target** versions: +To get started, inspect the Targets you have created: + +Use Fioctl® on your host machine to list all Target versions: .. prompt:: bash host:~$, auto host:~$ fioctl targets list -**Example Output**: - -.. prompt:: text +:: VERSION TAGS APPS HARDWARE IDs ------- ---- ---- ------------ 2 devel raspberrypi3-64 - 3 master raspberrypi3-64 + 3 main raspberrypi3-64 + 3 main raspberrypi3-64 4 devel shellhttpd raspberrypi3-64 5 devel shellhttpd raspberrypi3-64 6 devel shellhttpd raspberrypi3-64 @@ -26,47 +25,38 @@ Use ``fioctl`` on your host machine to list all **Target** versions: 8 devel shellhttpd-mqtt,mosquitto,shellhttpd,flask-mqtt-nginx raspberrypi3-64 9 devel mosquitto,shellhttpd,flask-mqtt-nginx,shellhttpd-mqtt raspberrypi3-64 -You might not have ``9`` versions. It depends on how many builds you -trigger on your FondriesFactory CI. +You might not have the same number of versions as it depends on how many builds you have triggered. -Note that most versions are tagged with ``devel`` because we have used the -``devel`` branch on previous tutorials. +Note that though most versions are tagged with ``devel``, yours may be tagged as ``main``. +This depends on if and when you created the ``devel`` branch. -This tutorial assumes you have all applications from your ``containers.git`` at -``devel`` repository successfully building. +This tutorial assumes you have any applications from ``containers.git`` on the ``devel`` branch successfully building. -Your device should also be following the ``devel`` tag and running its latest -**Target** with the tag ``devel``. +Your device should also be following the ``devel`` tag and running its latest Target with the tag ``devel``. -Based on the **Target** version listed above, the device should be running version ``9``. +Based on the Target version listed above, the device should be running version ``9``. -Use ``fioctl`` on your host machine to verify what **Target** the device is running. +Use ``fioctl`` on your host machine to verify what Target the device is running. .. prompt:: bash host:~$, auto host:~$ fioctl device list -**Example Output**: - -.. prompt:: text +:: NAME FACTORY TARGET STATUS APPS UP-TO-DATE ---- ------- ------ ------ ---- ---------- raspberrypi3-64-lmp-9 OK flask-mqtt-nginx,mosquitto,shellhttpd-mqtt true -As you can see above, the device is running ``raspberrypi3-64-lmp-9`` which is -the **Target** created for ``raspberrypi3-64`` in the build version ``9``. +As you can see above, the device is running ``raspberrypi3-64-lmp-9``, which is the Target created for ``raspberrypi3-64`` in the build version ``9``. -To make sure your device is configured to follow the ``devel`` tag, use ``fioctl`` -to inspect the device: +To make sure your device is configured to follow the ``devel`` tag, use ``fioctl`` to inspect the device: .. prompt:: bash host:~$, auto host:~$ fioctl device show -**Example Output**: - -.. prompt:: text +:: UUID: 2b7f3164-b288-4c7e-b4e9-2c75c9943dd1 Owner: 5e13232f73927550af883e7b @@ -110,5 +100,4 @@ to inspect the device: Note that the device is configured with tag: ``devel``. -In case your device is not following ``devel``, flash the latest ``platform-devel`` -on your device and register the device again. \ No newline at end of file +If your device is not following ``devel``, flash the latest ``platform-devel`` on your device and register the device again. diff --git a/source/tutorials/working-with-tags/tagging-specific-version.rst b/source/tutorials/working-with-tags/tagging-specific-version.rst index 0e62d480c..5eb2d54e3 100644 --- a/source/tutorials/working-with-tags/tagging-specific-version.rst +++ b/source/tutorials/working-with-tags/tagging-specific-version.rst @@ -1,20 +1,18 @@ Tagging a Specific Version ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use ``fioctl`` on your host machine to list all **Target** versions you created: +Use Fioctl® on your host machine to list all Target versions: .. prompt:: bash host:~$, auto host:~$ fioctl targets list -**Example Output**: - -.. prompt:: text +:: VERSION TAGS APPS HARDWARE IDs ------- ---- ---- ------------ 2 devel raspberrypi3-64 - 3 master raspberrypi3-64 + 3 main raspberrypi3-64 4 devel shellhttpd raspberrypi3-64 5 devel shellhttpd raspberrypi3-64 6 devel shellhttpd raspberrypi3-64 @@ -26,34 +24,33 @@ Use ``fioctl`` on your host machine to list all **Target** versions you created: 12 devel mosquitto,shellhttpd,flask-mqtt-nginx,shellhttpd-mqtt raspberrypi3-64 13 devel mosquitto,shellhttpd,flask-mqtt-nginx,shellhttpd-mqtt raspberrypi3-64 -If you have any device following the ``devel`` tag, it should be running the latest -**Target**, in the example above, version 13. +If you have any device following the ``devel`` tag, it should be running the latest Target. +In the example above, this is version 13. -Because your device is configured to follow ``tutorial``, it should probably be -stuck in the latest version tagged with ``tutorial``, in the example above, version 10. +Because your device is configured to follow ``tutorial``, it should be stuck in the last version that was tagged with ``tutorial``. +In the example above, version 10. -This tutorial created 4 different **Targets**. Each one with a different message. +We had just created 4 different Targets. +Each one with a different message. -Your device is now running a version with the ``MSG``: ``This is the TEST 01``. +Your device is currently running a version with the ``MSG``: ``This is the TEST 01``. -Let's imagine you don't want to deploy to your device the second version you created with the ``MSG``: ``This is the TEST 02``. +Let's imagine you do not want to deploy the second version, the one with the ``MSG``: ``This is the TEST 02``. -Also, you don't want to deploy the latest version you created with the ``MSG``: ``This is the TEST 04``. +Also, you do not want to deploy the latest version you created with the ``MSG``: ``This is the TEST 04``. -There is something special in the third change you did with the ``MSG`` set as -``This is the TEST 03`` and you want to deploy this version. +There is something special in the third change you did with the ``MSG``:``This is the TEST 03``. +You want to deploy this version. -Looking to the **Target** list above. You should tag version 12 with ``tutorial``. +Looking at the Target list above, you would tag version 12 with ``tutorial``. -Use ``fioctl`` to tag version 12: +Use Fioctl to tag version you want, making sure to use the version you want from your Factory: .. prompt:: bash host:~$, auto host:~$ fioctl targets tag --by-version -T devel,tutorial 12 -**Example Output**: - -.. prompt:: text +:: [devel tutorial] Changing tags of raspberrypi3-64-lmp-12 from [devel] -> [devel tutorial] @@ -127,16 +124,14 @@ Use ``fioctl`` to tag version 12: | | | | |_| |_| -In a maximum of 2 minutes, your device should receive an update. +Within a few minutes, your device should receive an update. -On your device, test the container again by running the following command: +On your device, test the container: .. prompt:: bash device:~$, auto device:~$ wget -qO- 127.0.0.1:8080 -**Example Output**: - .. prompt:: text - This is the TEST 03 \ No newline at end of file + This is the TEST 03 diff --git a/source/tutorials/working-with-tags/working-with-tags-summary.rst b/source/tutorials/working-with-tags/working-with-tags-summary.rst index 04b416d23..60b99789a 100644 --- a/source/tutorials/working-with-tags/working-with-tags-summary.rst +++ b/source/tutorials/working-with-tags/working-with-tags-summary.rst @@ -1,11 +1,8 @@ Summary ------- -This tutorial shows how to use tags to deploy specific versions on the device. +This tutorial introduced you to using tags to deploy specific Target versions on a device. -Note that all the instructions from this tutorial were moving the device running -**Target** into a forward-only flow. - -It's important to understand that because adding or removing tags from **Targets** or from devices -could cause unexpected behaviors to the device. The suggestion is to keep your device -moving forward and do not update to earlier versions. \ No newline at end of file +Note that all the instructions from this tutorial were moving the device running Target into a forward-only flow. +This is important because adding or removing tags from Targets or devices could cause unexpected behaviors in the device. +The suggestion is to keep your device moving *forward* and do not update to earlier versions. diff --git a/source/tutorials/working-with-tags/working-with-tags.rst b/source/tutorials/working-with-tags/working-with-tags.rst index 4a7a3dd84..645fe5184 100644 --- a/source/tutorials/working-with-tags/working-with-tags.rst +++ b/source/tutorials/working-with-tags/working-with-tags.rst @@ -1,39 +1,31 @@ .. _tutorial-working-with-tags: -Working with Tags +Working With Tags ================= -In the previous tutorial, :ref:`tutorial-creating-first-target`, you learned -the concept of a **Target**. In the section ":ref:`tutorial-what-is-a-target`" -there is brief explanation about tags. +Your Factory initially has a single branch, ``main``. +By convention, Targets are tagged with the branches they are built from. +This means the Targets have the tag ``main``. -By default, your Factory is configured to tag all **Targets** built from ``master`` -and ``devel`` branches with the respective tag: ``master`` and ``devel``. +.. warning:: + For this tutorial, it is assumed you have created and worked on a ``devel`` branch. + This has not yet been covered. + See the :ref:`ref-factory-sources` reference manual on how to configure the CI with new branches. -That is good to keep the development flow fast. For example, you start with the -``platform-devel``, a ``platform`` build based on ``devel`` branch, and install it on the device. +This helps keep the development flow fast. +For example, you have ``platform-devel``, a ``platform`` build based on ``devel`` branch, and install it on the device. -Then you develop applications on ``containers.git`` from the ``devel`` branch. The -application is built in CI with a ``containers-devel`` trigger name -and produces a **Target** tagged with ``devel``. +Then you develop applications on ``containers.git`` from the ``devel`` branch. +The application is built by the CI with a ``containers-devel`` trigger name and produces a Target tagged with ``devel``. -Finally, the device automatically updates to the latest **Target** tagged with ``devel``. +Finally, the device automatically updates to the latest Target tagged with ``devel``. -.. figure:: /_static/tutorials/working-with-tags/ci_jobs.png - :width: 900 - :align: center +There are some use cases that you might want to control what tag a device follows, and Targets are tagged: - FoundriesFactory CI Job List +- Preventing a device from following a tag such as ``devel``, which is automatically created every time you change the ``devel`` branch. +- Testing a specific Target on a specific device. -There are some use cases that you might want to control what tag the device -should follow and how **Targets** should be tagged. - -Some examples of use cases could be: - -- Prevent a device following a tag such as ``devel`` which is automatically created every time you change the ``devel`` branch. -- Test a specific **Target** on a specific device. - -This tutorial will guide you over examples to help you understand how tags work. +This tutorial will guide you through examples to help you understand how tags work. .. note:: @@ -42,8 +34,8 @@ This tutorial will guide you over examples to help you understand how tags work. Learning Objectives ------------------- -- Create more ``devel`` **Targets**. -- Use ``fioctl`` to Tag a specific **Target**. +- Create more ``devel`` Targets. +- Use ``fioctl`` to Tag a specific Target. - Configure the device to follow a specific tag. Prerequisites @@ -63,4 +55,4 @@ Instructions following-specific-tag creating-targets tagging-specific-version - working-with-tags-summary \ No newline at end of file + working-with-tags-summary