Skip to content

Apply feedback on tutorials #834

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

Merged
merged 1 commit into from
May 21, 2025
Merged

Apply feedback on tutorials #834

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
4 changes: 2 additions & 2 deletions source/tutorials/compose-app/compose-app-commit-push-all-new-apps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<factory>/lmp/builds/61/
To https://source.foundries.io/factories/<factory>/containers.git/
f358677..72a9da5 main -> main

.. note::
Expand Down
2 changes: 1 addition & 1 deletion source/tutorials/compose-app/compose-app-docker-compose-apps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions source/tutorials/compose-app/compose-app-testing-applications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<factory>/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/<factory>/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:

Expand Down
6 changes: 3 additions & 3 deletions source/tutorials/customizing-the-platform/commit-and-push-recipe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<factory>/lmp/builds/71/
To https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git/
7767e6a..ccebcb5 main -> main

.. note::
Expand All @@ -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.
26 changes: 8 additions & 18 deletions source/tutorials/getting-started-with-docker/extra-commands.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@

Docker Logs
"""""""""""
Often, it is useful to watch Docker container logs.

Use ``docker logs <container name>`` to see the container's logs.
If you want the command to keep following the log, use the ``--follow`` parameter:

Expand All @@ -33,8 +33,6 @@

host:~$ docker logs --follow shellhttpd

**Example Output**:

.. prompt:: text

GET / HTTP/1.1
Expand Down Expand Up @@ -82,8 +80,6 @@

host:~$ docker exec shellhttpd ls /usr/local/bin/

**Example Output**:

.. prompt:: text

httpd.sh
Expand All @@ -94,8 +90,6 @@

host:~$ docker exec shellhttpd ps

**Example Output**:

.. prompt:: text

PID USER TIME COMMAND
Expand All @@ -109,8 +103,6 @@

host:~$ docker exec -it shellhttpd sh

**Example Output**:

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

docker:~$ ls
Expand All @@ -134,12 +126,13 @@
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}``.

Check warning on line 131 in source/tutorials/getting-started-with-docker/extra-commands.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'MSG' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'MSG' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/tutorials/getting-started-with-docker/extra-commands.rst", "range": {"start": {"line": 131, "column": 32}}}, "severity": "INFO"}
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

Expand Down Expand Up @@ -174,13 +167,12 @@

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``

Expand All @@ -193,8 +185,6 @@
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
Expand All @@ -221,4 +211,4 @@
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.
32 changes: 14 additions & 18 deletions source/tutorials/working-with-tags/adapting-shellhttpd.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,15 @@

.. 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`.

Check warning on line 8 in source/tutorials/working-with-tags/adapting-shellhttpd.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'", "location": {"path": "source/tutorials/working-with-tags/adapting-shellhttpd.rst", "range": {"start": {"line": 8, "column": 93}}}, "severity": "INFO"}

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

Expand All @@ -34,7 +33,7 @@
echo "= $(date) ============================="
done

Edit the file ``Dockerfile`` according to the example below:
Edit ``Dockerfile``:

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

Expand All @@ -48,7 +47,7 @@

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

Expand All @@ -60,14 +59,12 @@

services:
httpd:
image: hub.foundries.io/cavel/shellhttpd:latest
image: hub.foundries.io/<factory>/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:

Expand All @@ -77,11 +74,10 @@
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:

Expand All @@ -94,19 +90,19 @@
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

device:~$ wget -qO- 127.0.0.1:8080

::

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

Expand All @@ -117,7 +113,7 @@
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
Expand Down
33 changes: 13 additions & 20 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,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``.
Expand All @@ -25,27 +24,25 @@ Edit ``docker-compose.yml``:

services:
httpd:
image: hub.foundries.io/cavel/shellhttpd:latest
image: hub.foundries.io/<factory>/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:

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

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.

Expand All @@ -61,22 +58,20 @@ Edit ``docker-compose.yml``:

services:
httpd:
image: hub.foundries.io/cavel/shellhttpd:latest
image: hub.foundries.io/<factory>/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:

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

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.
Expand All @@ -95,25 +90,23 @@ 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/<factory>/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:

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

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::

Expand Down
4 changes: 2 additions & 2 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
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading