Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup working with tags tutorial #558

Merged
merged 1 commit into from
Jul 11, 2023
Merged

Cleanup working with tags tutorial #558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed source/_static/tutorials/working-with-tags/ci_jobs.png
View file
Open in desktop
Binary file not shown.
47 changes: 16 additions & 31 deletions source/tutorials/working-with-tags/adapting-shellhttpd.rst
View file
Open in desktop
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may have missed it, but since the repository won't have a devel branch, should we just have this whole thing set to for the main branch instead?

Also - for wording, I think "change the devel branch" is confusing - For a minute I thought we were saying something different. Maybe "When you push changes to the branch..."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i see below you talk about setting up a devel branch now. I guess the bigger question is: "Do we want to force devel upon people to get started?". I thought the answer was "no" and we just want to get people up to speed making changes directly on main.

If we want them on devel - i can change the factory setup to include rules for a devel branch. Maybe we need @mike-scott to weigh in here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mike-scott @rsalveti @doanac Do we have a decision on this for v91? To clarify/restate:

  • This will be proceeded by a new tutorial on creating a new branch, but that won't be ready for this release
  • In the meantime, there is a bit of a disclaimer on this tutorial that it will require creating a devel branch first, I can expand on that a bit
  • We can pull this tutorial for now and reintroduce it once the branching tutorial is ready, or we can keep it as it is in this commit.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think it makes sense. this whole article is about working with tags.

38 changes: 17 additions & 21 deletions source/tutorials/working-with-tags/creating-targets.rst
View file
Open in desktop
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
Open in desktop
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