ug: Add documentation for aktualizr-lite command line interface #734

detsch · 2024-08-01T12:13:03Z

CLI documentation update for v95.

PR Template and Checklist

Please complete as much as possible to speed up the reviewing process.

Readiness and adding reviewers as appropriate is required.

All PRs should be reviewed by a technical writer/documentation team and a peer.
If effecting customers—which is a majority of content changes—a member of Customer Success must also review.

Readiness

Merge (pending reviews)
Merge after date or event
Draft

Overview

Why merge this PR? What does it solve?

Checklist

Comments

Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.

doanac · 2024-08-01T12:15:46Z

Docs for 5c71a19 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2715/docs/artifacts/html/index.html

mike-sul · 2024-08-02T20:05:08Z

source/user-guide/custom-sota-client.rst

+.. highlight:: bash
+   :linenothreshold: 1
+
+Sample bash script illustrating usage of CLI operations and return codes handling::


I would move this script to the sotactl repo and reference it from this doc.

I was thinking about having it on a repo an also keep it in the docs, I believe it is simple enough to contribute to the docs context.

mike-sul · 2024-08-02T20:06:18Z

source/user-guide/custom-sota-client.rst

+    - Unable to fetch TUF metadata
+- *14*: Failure
+    - TUF metadata not found in the provided path (offline mode only)
+- *15*: Failure


I think we need to ask someone from CS team to check if the CLI commands and return codes as explained here works for them.

source/user-guide/custom-sota-client.rst

vanmaegima · 2024-08-05T18:27:11Z

I'm missing a note about stopping aklite daemon before running CLI.
We could cover:

manual updates (stop aklite and stop fioconfig)
skip daemon start from lmp-device-register
skip daemon from the build (we have an example for custom-sota, what would be the alternative for CLI?)

vanmaegima · 2024-08-05T18:27:37Z

I haven't reviewed return codes and sample script yet.

doanac · 2024-08-08T20:25:56Z

Docs for 4564d81 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2717/docs/artifacts/html/index.html

doanac · 2024-09-04T00:45:56Z

Docs for 5e568db are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2742/docs/artifacts/html/index.html

source/user-guide/custom-sota-client.rst

doanac · 2024-09-04T19:44:25Z

Docs for 1548918 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2743/docs/artifacts/html/index.html

source/user-guide/custom-sota-client.rst

mike-sul · 2024-09-06T15:14:48Z

source/user-guide/custom-sota-client.rst

+Fetch TUF Metadata and List Updates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``check`` command will refresh the Targets metadata from the OTA server, and present you with a list of available Targets::


@kprosise Do you think this "refresh the Targets metadata from the OTA server" means what the command actually does?

source/user-guide/custom-sota-client.rst

doanac · 2024-09-06T18:08:03Z

Docs for 9eebdc6 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2751/docs/artifacts/html/index.html

detsch · 2024-09-06T18:24:37Z

I'm missing a note about stopping aklite daemon before running CLI. We could cover:

manual updates (stop aklite and stop fioconfig)

Added note.

skip daemon start from lmp-device-register

Added note.

skip daemon from the build (we have an example for custom-sota, what would be the alternative for CLI?)

We do need the daemon binary, so the build itself is not changed someone is going to use CLI. Perhaps adding something about not enabling the aklite service by default in the build? Not sure hot that can be done, will have to check it.

doanac · 2024-09-06T20:58:46Z

Docs for 968cbee are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2752/docs/artifacts/html/index.html

mike-sul · 2024-09-09T08:27:57Z

source/user-guide/custom-sota-client.rst

+.. note::
+   An update can only be performed when the original and update Targets are under the same tag.
+   In case the Target is tagged differently,
+   it is required to switch tags before running this command.


I would rather recommend to add the device's tag to the Target, switching tags on a device is rather the last resort.

Maybe we should remove this note at all since this is a general rule, not specific to the CLI, is applicable to any types of update.

I agree. Having it here only adds uneccessary complexity to the documentation. The target would not be listed in the list and check commands anyway. Removing the note.

mike-sul

LGTM, just minor comments.

doanac · 2024-09-09T23:12:56Z

Docs for f227e91 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2753/docs/artifacts/html/index.html

doanac · 2024-09-10T17:50:15Z

Docs for c9b6130 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2758/docs/artifacts/html/index.html

detsch · 2024-09-10T23:29:43Z

@kprosise can you take a look? Feel free to do text adjustments and merge if no changes are required from our side. Thanks!

kprosise

Made some minor suggestions, but otherwise it LGTM

kprosise · 2024-09-11T07:52:24Z

source/user-guide/custom-sota-client.rst

+
+    sudo aktualizr-lite status
+
+Fetch TUF Metadata and List Updates


Suggested change

Fetch TUF Metadata and List Updates

Fetch :term:`TUF` Metadata and List Updates

kprosise · 2024-09-11T07:53:29Z

source/user-guide/custom-sota-client.rst

+The ``install``  command installs the Target, which should have been previously pulled.
+It yields an error if the specified Target has not been pulled before, and also supports the ``--update-name`` option.
+
+It is necessary to verify the return codes for each command in order to guarantee the correct update process flow,


Suggested change

It is necessary to verify the return codes for each command in order to guarantee the correct update process flow,

It is necessary to verify the return codes for each command to guarantee the correct update process flow,

kprosise · 2024-09-11T07:54:00Z

source/user-guide/custom-sota-client.rst

+^^^^^^^^^^
+The commands set exit codes (``echo $?``) that can be used by the caller to act accordingly.


Suggested change

^^^^^^^^^^

The commands set exit codes (``echo $?``) that can be used by the caller to act accordingly.

^^^^^^^^^^

The commands set exit codes (``echo $?``) that can be used by the caller to act accordingly.

kprosise · 2024-09-11T07:54:36Z

source/user-guide/custom-sota-client.rst

+- *130*: Failure
+    - Installation failed and rollback operation was not successful
+
+Automating the use of CLI operations


Suggested change

Automating the use of CLI operations

Automating the use of CLI Operations

kprosise · 2024-09-11T07:55:11Z

source/user-guide/custom-sota-client.rst

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The individual command line interface operations,
+specially ``check``, ``pull``, ``install`` and ``run``,


Suggested change

specially ``check``, ``pull``, ``install`` and ``run``,

especially ``check``, ``pull``, ``install`` and ``run``,

kprosise · 2024-09-11T08:15:43Z

source/user-guide/custom-sota-client.rst

+Command Line Interface - CLI (Aktualizr-lite Manual Mode)
+---------------------------------------------------------
+
+The `aktualizr-lite` executable can be invoked to perform individual operations allowing more control over the update flow.


Suggested change

The `aktualizr-lite` executable can be invoked to perform individual operations allowing more control over the update flow.

The ``aktualizr-lite`` executable can be invoked to perform individual operations allowing more control over the update flow.

kprosise · 2024-09-11T08:18:36Z

source/user-guide/custom-sota-client.rst

+    and/or disabled with ``sudo systemctl disable aktualizr-lite``.
+
+.. note:: If lmp-device-register is used,
+    the `--start-daemon 0` is recommended


Suggested change

the `--start-daemon 0` is recommended

Using ``--start-daemon 0`` is recommended

kprosise · 2024-09-11T08:18:48Z

source/user-guide/custom-sota-client.rst

+
+.. note:: If lmp-device-register is used,
+    the `--start-daemon 0` is recommended
+    in order to avoid starting aktualizr-lite daemon automatically.


Suggested change

in order to avoid starting aktualizr-lite daemon automatically.

in order to avoid starting the aktualizr-lite daemon automatically.

kprosise · 2024-09-11T08:25:37Z

source/user-guide/custom-sota-client.rst

+
+   sudo aktualizr-lite update
+
+To update to a specific build number or target name,


Suggested change

To update to a specific build number or target name,

To update to a specific build number or Target name,

kprosise · 2024-09-11T08:26:19Z

source/user-guide/custom-sota-client.rst

+   Only choose to do so mindfully.
+   For any update, always test before rolling out to production devices.
+
+Aktualizr-lite command line interface also allows the update steps to be performed individually,


Suggested change

Aktualizr-lite command line interface also allows the update steps to be performed individually,

The command line interface also allows the update steps to be performed individually,

kprosise · 2024-09-12T08:26:33Z

@detsch, if you could add the suggestions, if they seem appropriate, then squash the commits, I will then go ahead and merge. Thank you!

Signed-off-by: Andre Detsch <andre.detsch@foundries.io>

detsch · 2024-09-12T12:56:21Z

Thanks @kprosise! Applied all your suggestions, and rebased to the latest main . Feel free to merge when appropriate.

doanac · 2024-09-12T12:56:51Z

Docs for 9d9037d are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2764/docs/artifacts/html/index.html

doanac · 2024-09-12T12:57:47Z

Docs for 4502850 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2765/docs/artifacts/html/index.html

detsch requested review from vanmaegima, mike-sul and caiotpereira August 1, 2024 14:26

mike-sul reviewed Aug 2, 2024

View reviewed changes

vanmaegima reviewed Aug 5, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

vanmaegima reviewed Aug 5, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Show resolved Hide resolved

detsch force-pushed the detsch-document-aklite-cli branch from 5c71a19 to 4564d81 Compare August 8, 2024 20:23

detsch force-pushed the detsch-document-aklite-cli branch from 4564d81 to 5e568db Compare September 4, 2024 00:41

vanmaegima reviewed Sep 4, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

detsch force-pushed the detsch-document-aklite-cli branch from 5e568db to 1548918 Compare September 4, 2024 19:40

mike-sul reviewed Sep 6, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

mike-sul reviewed Sep 6, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

mike-sul reviewed Sep 6, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

mike-sul reviewed Sep 6, 2024

View reviewed changes

source/user-guide/custom-sota-client.rst Outdated Show resolved Hide resolved

detsch force-pushed the detsch-document-aklite-cli branch from 1548918 to 9eebdc6 Compare September 6, 2024 18:03

detsch force-pushed the detsch-document-aklite-cli branch from 9eebdc6 to 968cbee Compare September 6, 2024 20:53

mike-sul reviewed Sep 9, 2024

View reviewed changes

mike-sul approved these changes Sep 9, 2024

View reviewed changes

detsch force-pushed the detsch-document-aklite-cli branch from 968cbee to f227e91 Compare September 9, 2024 23:08

detsch force-pushed the detsch-document-aklite-cli branch 2 times, most recently from 0a1f96f to c9b6130 Compare September 10, 2024 17:46

detsch marked this pull request as ready for review September 10, 2024 17:48

kprosise reviewed Sep 11, 2024

View reviewed changes

detsch force-pushed the detsch-document-aklite-cli branch from c9b6130 to 9d9037d Compare September 12, 2024 12:53

ug: Add documentation for aktualizr-lite command line interface

4502850

Signed-off-by: Andre Detsch <andre.detsch@foundries.io>

detsch force-pushed the detsch-document-aklite-cli branch from 9d9037d to 4502850 Compare September 12, 2024 12:55

kprosise merged commit 4e459db into foundriesio:main Sep 12, 2024
1 of 3 checks passed

detsch mentioned this pull request Sep 12, 2024

ug: Minor fixes in aklite CLI documentation #753

Merged

19 tasks


		sudo aktualizr-lite status

		Fetch TUF Metadata and List Updates

	Fetch TUF Metadata and List Updates
	Fetch :term:`TUF` Metadata and List Updates

	It is necessary to verify the return codes for each command in order to guarantee the correct update process flow,
	It is necessary to verify the return codes for each command to guarantee the correct update process flow,

		^^^^^^^^^^
		The commands set exit codes (``echo $?``) that can be used by the caller to act accordingly.

	Automating the use of CLI operations
	Automating the use of CLI Operations

	specially ``check``, ``pull``, ``install`` and ``run``,
	especially ``check``, ``pull``, ``install`` and ``run``,

	The `aktualizr-lite` executable can be invoked to perform individual operations allowing more control over the update flow.
	The ``aktualizr-lite`` executable can be invoked to perform individual operations allowing more control over the update flow.

	the `--start-daemon 0` is recommended
	Using ``--start-daemon 0`` is recommended

	in order to avoid starting aktualizr-lite daemon automatically.
	in order to avoid starting the aktualizr-lite daemon automatically.


		sudo aktualizr-lite update

		To update to a specific build number or target name,

	Aktualizr-lite command line interface also allows the update steps to be performed individually,
	The command line interface also allows the update steps to be performed individually,

ug: Add documentation for aktualizr-lite command line interface #734

ug: Add documentation for aktualizr-lite command line interface #734

Conversation

detsch commented Aug 1, 2024 • edited Loading

PR Template and Checklist

Readiness

Overview

Checklist

Comments

doanac commented Aug 1, 2024

Choose a reason for hiding this comment

detsch Aug 8, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vanmaegima commented Aug 5, 2024

vanmaegima commented Aug 5, 2024

doanac commented Aug 8, 2024

doanac commented Sep 4, 2024

doanac commented Sep 4, 2024

Choose a reason for hiding this comment

doanac commented Sep 6, 2024

detsch commented Sep 6, 2024 • edited Loading

doanac commented Sep 6, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mike-sul left a comment

Choose a reason for hiding this comment

doanac commented Sep 9, 2024

doanac commented Sep 10, 2024

detsch commented Sep 10, 2024

kprosise left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kprosise commented Sep 12, 2024

detsch commented Sep 12, 2024

doanac commented Sep 12, 2024

doanac commented Sep 12, 2024

detsch commented Aug 1, 2024 •

edited

Loading

detsch Aug 8, 2024 •

edited

Loading

detsch commented Sep 6, 2024 •

edited

Loading