From 9ae8a705a68e6eba594786c12d48bdcd262a6882 Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Tue, 20 May 2025 07:53:53 -0400 Subject: [PATCH] Apply feedback on tutorials MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Customer feedback and additional cleanup applied to tutorials. QA: ran vale linter while editing, checked rendered HTML output. This commit addresses issue FFTK-1460, "fixes based on…conversations" Signed-off-by: Katrina Prosise --- .../compose-app-commit-push-all-new-apps.rst | 4 +-- .../compose-app-docker-compose-apps.rst | 2 +- .../compose-app-testing-applications.rst | 4 +-- .../commit-and-push-recipe.rst | 6 ++-- .../extra-commands.rst | 26 +++++---------- .../working-with-tags/adapting-shellhttpd.rst | 32 ++++++++---------- .../working-with-tags/creating-targets.rst | 33 ++++++++----------- .../following-specific-tag.rst | 4 +-- .../working-with-tags/inspecting-targets.rst | 13 +++----- .../working-with-tags/working-with-tags.rst | 8 ++--- 10 files changed, 54 insertions(+), 78 deletions(-) diff --git a/source/tutorials/compose-app/compose-app-commit-push-all-new-apps.rst b/source/tutorials/compose-app/compose-app-commit-push-all-new-apps.rst index 776df595f..1cf3447be 100644 --- a/source/tutorials/compose-app/compose-app-commit-push-all-new-apps.rst +++ b/source/tutorials/compose-app/compose-app-commit-push-all-new-apps.rst @@ -58,8 +58,8 @@ Push all committed modifications to the remote repository: Writing objects: 100% (14/14), 2.48 KiB | 2.48 MiB/s, done. Total 14 (delta 0), reused 4 (delta 0), pack-reused 0 remote: Trigger CI job... - remote: CI job started: https://ci.foundries.io/projects/cavel/lmp/builds/61/ - To https://source.foundries.io/factories/cavel/containers.git/ + remote: CI job started: https://ci.foundries.io/projects//lmp/builds/61/ + To https://source.foundries.io/factories//containers.git/ f358677..72a9da5 main -> main .. note:: diff --git a/source/tutorials/compose-app/compose-app-docker-compose-apps.rst b/source/tutorials/compose-app/compose-app-docker-compose-apps.rst index 0da61978e..278360e73 100644 --- a/source/tutorials/compose-app/compose-app-docker-compose-apps.rst +++ b/source/tutorials/compose-app/compose-app-docker-compose-apps.rst @@ -95,7 +95,7 @@ In this case, ``app/docker-compose.yml`` file looks like this: Multiple Sources ---------------- -You can can also mix the examples for both single and multiple container applications. +You can also mix the examples for both single and multiple container applications. For example: .. prompt:: text diff --git a/source/tutorials/compose-app/compose-app-testing-applications.rst b/source/tutorials/compose-app/compose-app-testing-applications.rst index 7cceeefa0..7326cf96a 100644 --- a/source/tutorials/compose-app/compose-app-testing-applications.rst +++ b/source/tutorials/compose-app/compose-app-testing-applications.rst @@ -30,10 +30,10 @@ Once ``aktualizr-lite`` finishes, check the running containers: :: CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c563d12b2c6 hub.foundries.io/cavel/shellhttpd-mqtt "/usr/local/bin/http…" 9 minutes ago Up 9 minutes 0.0.0.0:8082->8082/tcp shellhttpd-mqtt_httpd-mqtt_1 + 9c563d12b2c6 hub.foundries.io//shellhttpd-mqtt "/usr/local/bin/http…" 9 minutes ago Up 9 minutes 0.0.0.0:8082->8082/tcp shellhttpd-mqtt_httpd-mqtt_1 ab91fca6c88b eclipse-mosquitto "/docker-entrypoint.…" 9 minutes ago Up 9 minutes 0.0.0.0:1883->1883/tcp mosquitto_mosquitto_1 0b88c1dc7bbf nginx "/docker-entrypoint.…" 10 minutes ago Up About a minute 0.0.0.0:80->80/tcp flask-mqtt-nginx_nginx_1 - 129a54e5821b hub.foundries.io/cavel/flask-mqtt "python3 -m flask ru…" 10 minutes ago Up 7 minutes flask-mqtt-nginx_flask-mqtt_1 + 129a54e5821b hub.foundries.io//flask-mqtt "python3 -m flask ru…" 10 minutes ago Up 7 minutes flask-mqtt-nginx_flask-mqtt_1 On your device, follow the ``shellhttpd-mqtt_httpd-mqtt_1`` container logs: diff --git a/source/tutorials/customizing-the-platform/commit-and-push-recipe.rst b/source/tutorials/customizing-the-platform/commit-and-push-recipe.rst index 8f105a177..d6abae7a7 100644 --- a/source/tutorials/customizing-the-platform/commit-and-push-recipe.rst +++ b/source/tutorials/customizing-the-platform/commit-and-push-recipe.rst @@ -52,8 +52,8 @@ Push: Writing objects: 100% (3/3), 299 bytes | 299.00 KiB/s, done. Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 remote: Trigger CI job... - remote: CI job started: https://ci.foundries.io/projects/cavel/lmp/builds/71/ - To https://source.foundries.io/factories/cavel/meta-subscriber-overrides.git/ + remote: CI job started: https://ci.foundries.io/projects//lmp/builds/71/ + To https://source.foundries.io/factories//meta-subscriber-overrides.git/ 7767e6a..ccebcb5 main -> main .. note:: @@ -70,6 +70,6 @@ The latest **Target** named :guilabel:`platform-main` should be the CI job you j .. note:: - Yocto Project builds could take some time. Click on the building target and follow the live console for details. + Yocto Project builds could take some time. Click on the building Target and follow the live console for details. Wait until it finishes, then move on to the next step. diff --git a/source/tutorials/getting-started-with-docker/extra-commands.rst b/source/tutorials/getting-started-with-docker/extra-commands.rst index 0d7c3cf63..00168ded9 100644 --- a/source/tutorials/getting-started-with-docker/extra-commands.rst +++ b/source/tutorials/getting-started-with-docker/extra-commands.rst @@ -23,7 +23,7 @@ Add ``--all`` to see all containers on the device, even if they are not running. Docker Logs """"""""""" -Often, it is useful to watch Docker container logs. + Use ``docker logs `` to see the container's logs. If you want the command to keep following the log, use the ``--follow`` parameter: @@ -33,8 +33,6 @@ The log might be empty unless you tested the ``shellhttpd`` application with ``c host:~$ docker logs --follow shellhttpd -**Example Output**: - .. prompt:: text GET / HTTP/1.1 @@ -82,8 +80,6 @@ To verify the files in the root file system of the container, use the following host:~$ docker exec shellhttpd ls /usr/local/bin/ -**Example Output**: - .. prompt:: text httpd.sh @@ -94,8 +90,6 @@ To check what processes are running: host:~$ docker exec shellhttpd ps -**Example Output**: - .. prompt:: text PID USER TIME COMMAND @@ -109,8 +103,6 @@ Finally, you can start a shell inside the container with: host:~$ docker exec -it shellhttpd sh -**Example Output**: - .. prompt:: bash docker:~$, auto docker:~$ ls @@ -134,12 +126,13 @@ To stop and then remove the container, run the commands: host:~$ docker stop shellhttpd host:~$ docker rm shellhttpd -During development, it is common to make and test changes to the Docker image. +During development it is common to make and test changes to the Docker image. Let us give this a try. -In the file ``httpd.sh``, we specify the MSG variable with ``${MSG-OK}``. +In ``httpd.sh`` we specify the MSG variable with ``${MSG-OK}``. This means if ``MSG`` is not otherwise specified, it is set with the default value "OK". -Using the text editor of your choice, change ``OK`` to ``FoundriesFactory``, then rebuild and run: +Using a text editor, change ``OK`` to ``FoundriesFactory``. +Rebuild and run: .. prompt:: bash host:~$, auto @@ -174,13 +167,12 @@ Test the new change with curl: host:~$ curl 127.0.0.1:8080 -**Example Output**: - .. prompt:: text FoundriesFactory -The ``docker run`` command can accept many other parameters. For example, +The ``docker run`` command can accept other parameters. +For example, the ``--env`` parameter which specifies an environment variable to the container. Remove the previous image and launch it again with: ``--env MSG=MyFirstContainer`` @@ -193,8 +185,6 @@ Test the new change with curl: host:~$ docker run --env MSG=MyFirstContainer --name shellhttpd -d -p 8080:8080 shellhttpd:1.0 host:~$ curl 127.0.0.1:8080 -**Example Output**: - .. prompt:: text MyFirstContainer @@ -221,4 +211,4 @@ Remove the container: host:~$ docker rm shellhttpd All these commands are important in understanding how Docker containers work. -Next is going into how ``docker-compose`` works. +Next we explore how ``docker-compose`` works. diff --git a/source/tutorials/working-with-tags/adapting-shellhttpd.rst b/source/tutorials/working-with-tags/adapting-shellhttpd.rst index 7e19272c7..d65c8391a 100644 --- a/source/tutorials/working-with-tags/adapting-shellhttpd.rst +++ b/source/tutorials/working-with-tags/adapting-shellhttpd.rst @@ -5,16 +5,15 @@ 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` + If you do not have the ``shellhttpd`` application, complete :ref:`tutorial-creating-first-target`. -Open a new terminal on your host machine and go into your containers repo folder. +Open a terminal on your host machine and go into your ``containers`` repo folder. .. prompt:: bash host:~$, auto host:~$ cd containers/ -Edit ``httpd.sh`` according to the example below: +Edit ``httpd.sh``: .. prompt:: bash host:~$, auto @@ -34,7 +33,7 @@ Edit ``httpd.sh`` according to the example below: echo "= $(date) =============================" done -Edit the file ``Dockerfile`` according to the example below: +Edit ``Dockerfile``: .. prompt:: bash host:~$, auto @@ -48,7 +47,7 @@ Edit the file ``Dockerfile`` according to the example below: CMD ["/usr/local/bin/httpd.sh"] -Edit the file ``docker-compose.yml`` according to the example below: +Edit ``docker-compose.yml``: .. prompt:: bash host:~$, auto @@ -60,14 +59,12 @@ Edit the file ``docker-compose.yml`` according to the example below: services: httpd: - image: hub.foundries.io/cavel/shellhttpd:latest + image: hub.foundries.io//shellhttpd:latest restart: always ports: - 8080:${PORT-8080} environment: - MSG: "Tag devel, test:01" - -Note that ``MSG`` is defined with ``This is the TEST 01``. + MSG: "${MSG-Hello world}" Commit and push all changes: @@ -77,11 +74,10 @@ Commit and push all changes: host:~$ git add shellhttpd/docker-compose.yml host:~$ git add shellhttpd/httpd.sh host:~$ git add shellhttpd/Dockerfile - host:~$ git commit -m "This is the TEST 02" + host:~$ git commit -m "Changes for adapting shellhttpd tutorial" host:~$ git push -Wait for your build to finish by checking the latest Target on the :guilabel:`Devices` tab -for your Factory. +Wait for your build to finish by checking the latest Target on the :guilabel:`Devices` tab. Use ``fioctl`` to configure your device to run just the ``shellhttpd`` application: @@ -94,9 +90,9 @@ Use ``fioctl`` to configure your device to run just the ``shellhttpd`` applicati Changing apps from: [] -> [shellhttpd] Changing packagemanager to ostree+compose_apps -In a few minutes, your device should receive an update. +In a few minutes your device should receive an update. -On your device, test the container again: +Test the container on your device: .. prompt:: bash device:~$, auto @@ -104,9 +100,9 @@ On your device, test the container again: :: - This is the TEST 01 + Hello world -Check again the Target version list with ``fioctl`` +Check the Target version list with ``fioctl`` .. prompt:: bash host:~$, auto @@ -117,7 +113,7 @@ Check again the Target version list with ``fioctl`` 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 diff --git a/source/tutorials/working-with-tags/creating-targets.rst b/source/tutorials/working-with-tags/creating-targets.rst index 6afafd1f2..1d32c05fe 100644 --- a/source/tutorials/working-with-tags/creating-targets.rst +++ b/source/tutorials/working-with-tags/creating-targets.rst @@ -1,12 +1,11 @@ Creating Targets ^^^^^^^^^^^^^^^^ -Let's simulate regular development on the branch ``devel``. +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 that—while you will keep developing on ``devel`` —you want to decide which -Target your devices tagged with ``tutorial`` will receive. +Imagine that—while you will keep developing on ``devel`` —you want to decide the Target your devices tagged with ``tutorial`` will receive. .. hint:: On the previous page we tagged the latest ``devel`` Target with the additional tag, ``tutorial``. @@ -25,14 +24,12 @@ Edit ``docker-compose.yml``: services: httpd: - image: hub.foundries.io/cavel/shellhttpd:latest + image: hub.foundries.io//shellhttpd:latest restart: always ports: - 8080:${PORT-8080} environment: - MSG: "This is the TEST 02" - -Note that ``MSG`` is defined with ``This is the TEST 02``. + MSG: "Oi Mundo" Commit and push the changes: @@ -40,12 +37,12 @@ Commit and push the changes: host:~$ git status host:~$ git add shellhttpd/docker-compose.yml - host:~$ git commit -m "This is the TEST 02" + host:~$ git commit -m "Update msg" host:~$ git push 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 created. Wait until it finishes and change your application again. @@ -61,14 +58,12 @@ Edit ``docker-compose.yml``: services: httpd: - image: hub.foundries.io/cavel/shellhttpd:latest + image: hub.foundries.io//shellhttpd:latest restart: always ports: - 8080:${PORT-8080} environment: - MSG: "This is the TEST 03" - -Note that ``MSG`` is defined with ``This is the TEST 03``. + MSG: "Hallo Welt" Commit and push the changes: @@ -76,7 +71,7 @@ Commit and push the changes: host:~$ git status host:~$ git add shellhttpd/docker-compose.yml - host:~$ git commit -m "This is the TEST 03" + host:~$ git commit -m "Change msg again" host:~$ git push Keep watching your jobs on https://app.foundries.io and once it finishes, change your application one more time. @@ -95,14 +90,12 @@ Keep watching your jobs on https://app.foundries.io and once it finishes, change services: httpd: - image: hub.foundries.io/cavel/shellhttpd:latest + image: hub.foundries.io//shellhttpd:latest restart: always ports: - 8080:${PORT-8080} environment: - MSG: "This is the TEST 04" - -Note that ``MSG`` is defined with ``This is the TEST 04``. + MSG: "Howdy world" Commit and push the changes: @@ -110,10 +103,10 @@ Commit and push the changes: host:~$ git status host:~$ git add shellhttpd/docker-compose.yml - host:~$ git commit -m "This is the TEST 04" + host:~$ git commit -m "Update msg once again" host:~$ git push -Finally, you should have three new versions in the Targets version list. +You now 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 13b43e191..a141d77b5 100644 --- a/source/tutorials/working-with-tags/following-specific-tag.rst +++ b/source/tutorials/working-with-tags/following-specific-tag.rst @@ -19,7 +19,7 @@ Use ``fioctl`` on your host machine to list all Targets: 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 @@ -119,7 +119,7 @@ Use ``fioctl`` again to list all Target versions: 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 diff --git a/source/tutorials/working-with-tags/inspecting-targets.rst b/source/tutorials/working-with-tags/inspecting-targets.rst index 1f52c3fda..eecdf43bf 100644 --- a/source/tutorials/working-with-tags/inspecting-targets.rst +++ b/source/tutorials/working-with-tags/inspecting-targets.rst @@ -5,7 +5,7 @@ At this point, your Factory could have a different number of builds/versions com To get started, inspect the Targets you have created: -Use Fioctl® on your host machine to list all Target versions: +Use ``fioctl`` on your host machine to list all Target versions: .. prompt:: bash host:~$, auto @@ -25,12 +25,10 @@ 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 the same number of versions as it depends on how many builds you have triggered. - 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 any applications from ``containers.git`` on the ``devel`` branch successfully building. +This tutorial assumes you have 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``. @@ -48,9 +46,9 @@ Use ``fioctl`` on your host machine to verify what Target the device is running. ---- ------- ------ ------ ---- ---------- 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``. +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 check if your device is following the ``devel`` tag, use ``fioctl`` to inspect the device: .. prompt:: bash host:~$, auto @@ -98,6 +96,5 @@ To make sure your device is configured to follow the ``devel`` tag, use ``fioctl /lQvPR8gJM+byg4zx4iu6TIFh0Xx+VkoYjhy0wnamEciV7VbuQZopP4Ffw== -----END PUBLIC KEY----- -Note that the device is configured with tag: ``devel``. -If your device is not following ``devel``, flash the latest ``platform-devel`` on your device and register the device again. +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/working-with-tags.rst b/source/tutorials/working-with-tags/working-with-tags.rst index 645fe5184..7cbf5f5a9 100644 --- a/source/tutorials/working-with-tags/working-with-tags.rst +++ b/source/tutorials/working-with-tags/working-with-tags.rst @@ -13,14 +13,14 @@ This means the Targets have the tag ``main``. See the :ref:`ref-factory-sources` reference manual on how to configure the CI with new branches. 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. +For example: you start with ``platform-devel``, a ``platform`` build based on ``devel`` branch to install on a device. -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``. +Next you develop an application on ``containers.git`` from the ``devel`` branch. +The application is built by the CI with a ``containers-devel`` trigger name, producing a Target tagged with ``devel``. Finally, the device automatically updates to the latest Target tagged with ``devel``. -There are some use cases that you might want to control what tag a device follows, and Targets are tagged: +There are some use cases where you want to control what tag a device follows, and Targets are tagged: - 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.