Skip to content

Commit

Permalink
Cleanup working with tags tutorial
Browse files Browse the repository at this point in the history 
Tutorial edited for simplification and style guide.
Additional changes were needed to reflect the introduction of fast first
Target in v91. As this change means there are no longer devel and master
branches, much of this tutorial needed to be modified. Information was
added pointing to the reference manual page on having the CI follow
branches. This is a stop-gap measure until an additional tutorial is
added which will focus on adding an additional branch. At that point,
this tutorial will be revised again.

QA steps: ran linter, checked output in browser.

This commit addresses FFTK-2517
This commit applies to FFTK-2510
This commit applies to FFTK-2430
This commit applies to FFTK-988

Signed-off-by: Katrina Prosise <katrina.prosise@foundries.io>
  • Loading branch information
@kprosise
kprosise committed Jul 11, 2023
1 parent 88d6cdd commit 807c621
Show file tree
Hide file tree
Showing 8 changed files with 106 additions and 161 deletions.
Binary file removed source/_static/tutorials/working-with-tags/ci_jobs.png
View file
Binary file not shown.
47 changes: 16 additions & 31 deletions source/tutorials/working-with-tags/adapting-shellhttpd.rst
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -42,8 +40,6 @@ Edit the file ``Dockerfile`` according to the example below:

host:~$ gedit shellhttpd/Dockerfile

**shellhttpd/Dockerfile**:

.. prompt:: text

FROM alpine
Expand All @@ -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'
Expand All @@ -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

Expand All @@ -86,45 +80,39 @@ 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:

.. prompt:: bash host:~$, auto

host:~$ fioctl devices config updates --apps shellhttpd <device-name>

**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
------- ---- ---- ------------
Expand All @@ -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
---- ------- ------ ------ ---- ----------
<device-name> <factory> 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.
38 changes: 17 additions & 21 deletions source/tutorials/working-with-tags/creating-targets.rst
View file
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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

Expand All @@ -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'
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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::

Expand Down
25 changes: 8 additions & 17 deletions source/tutorials/working-with-tags/following-specific-tag.rst
View file
Original file line number Diff line number Diff line change
@@ -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
------- ---- ---- ------------
Expand All @@ -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]
Expand Down Expand Up @@ -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
------- ---- ---- ------------
Expand All @@ -143,9 +136,7 @@ Change the device configuration to start following the ``tutorial`` tag:

host:~$ fioctl devices config updates --tags tutorial <device-name>

**Example Output**:

.. prompt:: text
::

Changing tags from: [] -> [tutorial]
Changing packagemanager to ostree+compose_apps
Loading

0 comments on commit 807c621

Please sign in to comment.