Cleanup of factory reference manual section

Style guide lines applied. Removed link to the Yocto Project layers section which is part of the LmP reference manual; this was done to make navigation less confusing, and to keep sections focused. The section on Factory Sources was placed before the Factory Definition, for better explanatory flow. QA steps: Ran linter and addressed issues where possible/appropriate. Checked html output in browser, no obvious rendering issues discovered. Ran linkcheck. This commit addresses FFTK-2790 This commit addresses FFTK-1880 This commit applies to FFTK-2732 This commit applies to FFTK-2730 This commit applies to FFTK-988 Signed-off-by: Katrina Prosise <[email protected]>
foundriesio · Nov 17, 2023 · adcd244 · adcd244
1 parent 4d94ede
commit adcd244
Show file tree

Hide file tree

Showing 8 changed files with 300 additions and 341 deletions.
diff --git a/source/reference-manual/factory/api-access.rst b/source/reference-manual/factory/api-access.rst
@@ -3,9 +3,9 @@
 API Access
 ==========
 
-FoundriesFactory APIs can be accessed with two different methods:
+FoundriesFactory® APIs can be accessed via two methods:
 
- #. OAuth2_ tokens managed in the `Application Credentials`_ interface.
+ #. `OAuth2`_ tokens managed in the `Application Credentials`_ interface.
  #. API Tokens managed in the `API tokens`_ interface.
 
 These credentials allow users to access:
@@ -18,70 +18,81 @@ These credentials allow users to access:
    password to Git clone and fetch operations.
  * `Factory containers`_. Access is granted by passing an API token as the
    password to ``docker login hub.foundries.io``.
- * Fioctl uses OAuth2 by default, but can also use API Tokens.
+ * Fioctl® uses OAuth2 by default, but can also use API Tokens.
 
 All tokens are created with scopes to help limit what they can do.
 
 .. note::
-   Fioctl® has a :ref:`docker-credential-helper` which simplifies access to
-   hub.foundries.io.
 
-Common scopes
+   Fioctl has a :ref:`docker-credential-helper` which simplifies access to
+   ``hub.foundries.io``.
+
+Common Scopes
 -------------
 
-Some common scopes users may find handy include:
+Some common scopes you may find useful include:
 
- * ``source:read-update`` - Useful for Git.
- * ``targets:read, devices:read, ci:read`` - read-only access
-   for fioctl or REST API
- * ``targets:read-update, devices:read-update, ci:read`` - read-update
-   access for fioctl.
- * ``containers:read`` - Useful for running docker commands on
-   factory containers.
+ * ``source:read-update``: For Git.
+ * ``targets:read, devices:read, ci:read``: Read-only access for Fioctl or REST API.
+ * ``targets:read-update, devices:read-update, ci:read``: Read-update access for Fioctl.
+ * ``containers:read``: For running docker commands on Factory containers.
 
 .. _ref-scopes:
 
 Token Scopes
 ------------
 
-Scopes define what resources a given token may perform operations on. The
-following scopes are supported:
+Scopes define what resources a given token may perform operations on.
+The following scopes are supported:
+
+Source
+^^^^^^
 
-source:read
+``source:read``
  Can perform git clone/fetch/pull operations.
-source:read-update
+``source:read-update``
  Can perform git push operations.
-source:delete
- Can delete a reference (git push --delete ...) and force-push (git push -f).
-source:create
+``source:delete``
+ Can delete a reference (``git push --delete ...``) and force-push (``git push -f``).
+``source:create``
  Can create a new references (tags and branches).
 
-containers:read
-  Can docker pull.
-containers:read-update
- Can docker push.
-
-ci:read
- Can access CI builds `https://api.foundries.io/projects/<factory>/lmp/`.
-ci:read-update
- This isn’t needed normally because ``source:read-update`` triggers CI.
- However, certain custom use-cases that trigger CI builds via
- `https://api.foundries.io/projects/<factory>/lmp/builds/` can use this.
-
-devices:read
- Can view device(s) `https://api.foundries.io/ota/devices/`.
-devices:read-update
- Can update configuration on a device
- `https://api.foundries.io/ota/devices/<device>/config/`
-devices:create
- Can create a device (lmp-device-register with an API token).
-devices:delete
- Can delete a device `https://api.foundries.io/ota/devices/<device>/`
-
-targets:read
-  Can view targets.json `https://api.foundries.io/ota/factories/<factory>/targets/`.
-targets:read-update
-  Can update targets.json `https://api.foundries.io/ota/factories/<factory>/targets/`.
+Containers
+^^^^^^^^^^
+
+``containers:read``
+ Can ``docker pull``.
+``containers:read-update``
+ Can ``docker push``.
+
+CI
+^^
+
+``ci:read``
+ Can access CI builds ``https://api.foundries.io/projects/<factory>/lmp/``.
+``ci:read-update``
+ This is not usually needed as ``source:read-update`` triggers the CI.
+ However, custom use-cases that trigger CI builds via ``https://api.foundries.io/projects/<factory>/lmp/builds/`` may use this.
+
+Devices
+^^^^^^^
+
+``devices:read``
+ Can view device(s) ``https://api.foundries.io/ota/devices/``.
+``devices:read-update``
+ Can update configuration on a device ``https://api.foundries.io/ota/devices/<device>/config/``
+``devices:create``
+ Can create a device (``lmp-device-register`` with an API token).
+``devices:delete``
+ Can delete a device ``https://api.foundries.io/ota/devices/<device>/``
+
+Targets
+^^^^^^^
+
+``targets:read``
+  Can view ``targets.json`` ``https://api.foundries.io/ota/factories/<factory>/targets/``.
+``targets:read-update``
+  Can update ``targets.json`` ``https://api.foundries.io/ota/factories/<factory>/targets/``.
 
 .. _API Tokens:
    https://app.foundries.io/settings/tokens

diff --git a/source/reference-manual/factory/ci-webhooks.rst b/source/reference-manual/factory/ci-webhooks.rst
@@ -3,13 +3,11 @@
 CI Webhooks
 ===========
 
-By default each factory is configured to send
-:ref:`email notifications <def-notify>` when CI builds complete.
-Customers also have the option of receiving webhooks when builds
-complete. Webhooks provide a way  to do things like launching
-internal workflows.
+By default, each Factory is configured to send :ref:`email notifications <def-notify>` when CI builds complete.
+You also have the option of receiving *webhooks* when builds complete.
+Webhooks provide a way to do things such as launching internal workflows.
 
-Webhook data sent by CI looks like::
+Webhook data sent by the CI looks like::
 
   {
     "build_id": 67,
@@ -28,17 +26,6 @@ Webhook data sent by CI looks like::
     "tests": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-amd64-partner/tests/"
     },
     {
-    "name": "build-armhf",
-    "url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/",
-    "status": "PASSED",
-    "log_url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/console.log",
-    "web_url": "https://ci.foundries.io/projects/andy-corp/lmp/builds/67/build-armhf/",
-    "created": "2021-07-26T18:10:39+00:00",
-    "completed": "2021-07-26T18:11:10+00:00",
-    "host_tag": "armhf",
-    "tests": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/tests/"
-    },
-    {
     "name": "build-aarch64",
     "url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-aarch64/",
     "status": "PASSED",
@@ -66,9 +53,7 @@ Webhook data sent by CI looks like::
     "completed": "2021-07-26T18:19:24+00:00"
   }
 
-This message includes an HMAC-SHA256_ HTTP header from the
-Foundries `CI engine`_, ``X-JobServ-Sig`` to help authenticate the
-sender.
+This message includes an `HMAC-SHA256`_ HTTP header from the FoundriesFactory® `CI engine`_, ``X-JobServ-Sig`` to help authenticate the sender.
 
 .. _HMAC-SHA256:
    https://en.wikipedia.org/wiki/HMAC
@@ -78,91 +63,89 @@ sender.
 Prerequisites
 -------------
 
-The customer will need a server with an HTTP(S) port exposed to the
-internet. HTTPS is recommended, but the HMAC signing does help
-prevent malicious 3rd parties from tampering with the message body.
+You will need a server with an HTTP(S) port exposed to the internet.
+HTTPS is recommended, but the HMAC signing also helps prevent malicious 3rd parties from tampering with the message body.
 
-.. note:: Ngrok_ can be a useful tool for prototype work.
+.. note::
+   `Ngrok`_ can be a useful tool for prototype work.
 
 .. _Ngrok:
    https://ngrok.com/
 
-Configuring webhooks
+Configuring Webhooks
 --------------------
 
 Define a webhook secret for HMAC signing::
 
   $ fioctl secrets update webhook-docs-example=UseSomethingGoodHere
 
-This command informs the Foundries backend about a new CI related
-secret.
+This informs the FoundriesFactory backend about a new CI related secret.
 
 Configuring the Factory
 -----------------------
 
-The `factory-config.yml` file in ci-scripts.git will need something
-like::
+``factory-config.yml`` from ``ci-scripts.git`` will need something like:
+
+.. code-block:: YAML
 
  notify:
    webhooks:
     - url: https://29171f519f0a.ngrok.io/webhook
       secret_name: webhook-docs-example
 
+``secret_name`` ties things together so that the backend will use the correct key when signing the HTTP message.
 
-The ``secret_name`` ties things together so that the backend will
-know what key to use when signing the HTTP message.
+Once this change is pushed, all builds will send webhooks to the configured server.
 
-Once this change is pushed, all future builds will send webhooks to
-the configured server.
+Example
+-------
 
-A quick example
----------------
+A Docker-compose based project has been written to help prototype.
+This example uses Ngrok_ so that it can be tested behind firewalls.
 
-A simple project docker-compose based project has been written to
-help users prototype. This example uses Ngrok_ so that it can be
-tested behind firewalls.
+.. note:: Ngrok changes URLs every time it restarts.
+   This requires the ``factory-config.yml`` file to change as well.
 
-.. note:: Ngrok changes URLs every time it restarts. This requires
-   the factory-config.yml file to change as well.
-
-Prepare the app
+Prepare the App
 ~~~~~~~~~~~~~~~
+
 ::
 
  $ git clone https://github.com/foundriesio/jobserv-webhook-example
  $ cd jobserv-webhook-example
  $ docker-compose build
 
-Create the secret
+Create the Secret
 ~~~~~~~~~~~~~~~~~
+
 ::
 
   # Set secret in backend:
   $ fioctl secrets update webhook-docs-example=UseSomethingGoodHere
   # Set secret for compose app:
   $ echo UseSomethingGoodHere > webhook-secret
 
-Launch the app
+Launch the App
 ~~~~~~~~~~~~~~
+
 ::
 
   $ docker-compose up
 
-At this point, close attention must be paid to the docker-compose
-logs. Ngrok will print a message like::
+At this point, pay attention to the Docker-compose logs.
+Ngrok will print a message like::
 
   ngrok-proxy_1  | t=2021-07-26T17:51:15+0000 lvl=info msg="started tunnel" obj=tunnels name=command_line addr=http://webhook:5000 url=https://29171f519f0a.ngrok.io
 
 That tells the URL its proxying with. Take this URL and configure
 the factory-config.yml's ``notify.webhooks[0].url`` value.
 
-Push a change
+Push a Change
 ~~~~~~~~~~~~~
 
-Go to a branch in containers.git like "devel" and push and empty
-change with::
+Go to a branch in ``containers.git``  such as ``devel`` if you have it, and push an empty change with::
 
   $ git commit --allow-empty -m "bump to test webhooks"
 
-Now sit and wait for CI to complete and webhook to be delivered to
-the webhook app. It will print the contents of the webhook data.
+Wait for it to complete and the webhook to be delivered to the webhook app.
+It will print the contents of the webhook data.
diff --git a/source/reference-manual/factory/data-retention.rst b/source/reference-manual/factory/data-retention.rst
@@ -3,7 +3,7 @@
 Data Retention Policies
 =======================
 
-Understanding data retention policies within a FoundriesFactory can help with the compliance processes for a product.
+Understanding data retention policies for Foundries.io™ FoundriesFactory® can help with the compliance processes for a product.
 This page explains how data is managed within a Factory.
 FoundriesFactory consists of several tightly integrated projects:
 
@@ -28,7 +28,7 @@ Customer Data
 source.foundries.io
 ~~~~~~~~~~~~~~~~~~~
 Source code like ``containers.git`` lives in Digital Ocean's SFO2 data center where it is periodically backed up.
-Backups —but not the source itself— older than 6 months get pruned.
+Backups—but not the source itself—older than 6 months get pruned.
 Source code gets deleted when a Factory is deleted.
 
 ci.foundries.io
@@ -55,10 +55,12 @@ This data get pruned periodically, and gets deleted when a Factory is deleted.
 
 api.foundries.io
 ~~~~~~~~~~~~~~~~
+
 A reverse proxy to other services, and stores no data.
 
 app.foundries.io
 ~~~~~~~~~~~~~~~~
+
 This service has two components:
 
  * A web view to ``api.foundries.io``
@@ -108,4 +110,4 @@ Backups over 6 months old get pruned.
 ostree.foundries.io
 ~~~~~~~~~~~~~~~~~~~
 Devices pull LmP updates down from this service.
-It is managed in a similar way to hub.foundries.io.
+It is managed in a similar way to ``hub.foundries.io``.