diff --git a/requirements.txt b/requirements.txt index cc0ca39e..91286710 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,11 +2,12 @@ setuptools==78.1.1 pydata-sphinx-theme sphinx-design sphinx==8.1.3 -sphinx_copybutton>=0.5.2 +sphinx_copybutton>=0.5.2 sphinx_toolbox sphinx-reredirects sphinx-autobuild meilisearch sphinx-new-tab-link +sphinxcontrib-mermaid # uncomment when building PDF. May require additional system dependencies. #sphinx-simplepdf diff --git a/source/conf.py b/source/conf.py index 1173e538..65d99c16 100644 --- a/source/conf.py +++ b/source/conf.py @@ -159,6 +159,7 @@ 'sphinx_reredirects', 'sphinx.ext.graphviz', 'sphinx_new_tab_link', + 'sphinxcontrib.mermaid', ] #-- copy button config --------------------------------------------------------- diff --git a/source/getting-started/arduino-uno-q/index.rst b/source/getting-started/arduino-uno-q/index.rst index cf76a31c..ca026891 100644 --- a/source/getting-started/arduino-uno-q/index.rst +++ b/source/getting-started/arduino-uno-q/index.rst @@ -24,48 +24,15 @@ Using the Arduino UNO Q with FoundriesFactory .. warning:: - This section is specific to Arduino UNO Q users. Other users can skip to :ref:`tutorials`. + This section is specific to Arduino UNO Q users. -.. _gs-using-uno-q-with-ff-signup: - -Sign Up ----------- - -To begin using the FoundriesFactory™ Platform, start with `creating an account `_ with us. - -.. _gs-using-uno-q-with-ff-create-factory: - -Create Your Factory -------------------- - -The FoundriesFactory™ Community Edition is a Factory workspace which enables you to quickly build managed applications on your Linux-based device without needing to re-flash the OS. - -When your account is created, it is not associated with any factories. -The next step is to `create a Community Edition Factory for the Arduino UNO Q`_. - -.. _gs-using-uno-q-with-ff-install-client: - -Install the OTA Client ----------------------- - -The OTA update client that performs container-only management is called `Fioup`_ and it supports both Arm64 and x86 systems. - -Please follow the complete instructions for setting up `Fioup`_. They include steps for installing, registering your device, performing an update and configuring `Fioup`_ to run automatically. +The Arduino UNO Q ships with a Debian base image. +It is supported by the Container-only Factory solution. +Follow the :ref:`ref-gs-container-only` guide to get started. .. note:: To make sure your UNO Q has the latest base OS installed, checking the `Flashing a New Image to the UNO Q`_ documentation. -.. _gs-using-uno-q-with-ff-next-steps: - -Next Steps ----------- - -Once the OTA update client is registered with your Factory, proceed with :ref:`gs-install-fioctl` and then continue on to :ref:`gs-building-deploying-app`. - .. _Arduino UNO Q: https://docs.arduino.cc/hardware/uno-q/ -.. _signup: https://app.foundries.io/signup -.. _create a Community Edition Factory for the Arduino UNO Q: https://app.foundries.io/factories/+/arduino-uno-q -.. _Fioup: https://github.com/foundriesio/fioup/blob/main/docs/README.md -.. _GitHub Release: https://github.com/foundriesio/fioup/releases .. _Flashing a New Image to the UNO Q: https://docs.arduino.cc/tutorials/uno-q/update-image/ diff --git a/source/getting-started/ci-selection.rst b/source/getting-started/ci-selection.rst new file mode 100644 index 00000000..9c01d274 --- /dev/null +++ b/source/getting-started/ci-selection.rst @@ -0,0 +1,24 @@ +Choosing Your CI Solution +========================= + +FoundriesFactories supports two different modes for building Targets. + +FoundriesFactory Managed +------------------------ + +Every Factory includes a ``containers.git`` hosted at ``source.foundries.io``. +This works out of the box and changes pushed here will be built automatically by our CI system and produce Targets that can be deployed to your device(s). + +To get started with the Foundries.io managed solution you will need to: + +- :ref:`Install Fioctl ` in order to work with ``source.foundries.io``. +- :ref:`Build and deploy ` your first application. + +Self-Hosted +----------- + +The self-hosted option works well for people wanting more control of their workflows. +It works great with products like GitHub. +There is a one-time setup that takes about 30 minutes. + +To get started with the self-hosted option, follow the steps outlined in the :ref:`Custom CI ` guide. diff --git a/source/getting-started/fioup-registration/index.rst b/source/getting-started/fioup-registration/index.rst new file mode 100644 index 00000000..93a91ccc --- /dev/null +++ b/source/getting-started/fioup-registration/index.rst @@ -0,0 +1,14 @@ +Registering Your Device with Fioup +================================== + +Fioup_ is an OTA update client that peforms container-only management on devices. +It supports both Arm64 and x86 systems. + +Please follow the complete instructions for setting up Fioup. +They include steps for installing_, registering_, and updating_ your device. + +.. _Fioup: https://github.com/foundriesio/fioup/blob/main/docs/README.md +.. _installing: https://github.com/foundriesio/fioup/blob/main/docs/install.md +.. _registering: https://github.com/foundriesio/fioup/blob/main/docs/register-device.md +.. _updating: https://github.com/foundriesio/fioup/blob/main/docs/update-device.md + diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst new file mode 100644 index 00000000..e6fa1875 --- /dev/null +++ b/source/getting-started/gs-container-only.rst @@ -0,0 +1,33 @@ +.. _ref-gs-container-only: + +Getting Started With Container-Only Factories +============================================= + +Container-only Factories lets you experience a Factory without having to run the Linux microPlatform on your device. +Container-only Factories can be done on any Arm64 or x86 platform. +A Debian package archive_ is included with statically linked binaries for Debian/Ubuntu users. +There are few differences between the Container-only Factory and the LmP-based Factory: + +- OS updates are not built into the offering. + It is possible, but not integrated the same way OSTree updates are built into LmP based Factories. +- The Fioup_ update agent is used instead of :ref:`Aktualizr-Lite `. + They share the same configuration format and files, but Fioup is focused on container-only updates. +- No TUF_ validation. The Factory includes TUF signed metadata, + however, it is not verfied by Fioup in the Community Edition. + This can be enabled for paid versions of the product as you get ready to move from evaluation to production. + +.. _archive: https://github.com/foundriesio/fioup/blob/main/docs/install.md +.. _Fioup: https://github.com/foundriesio/fioup/blob/main/docs/README.md +.. _TUF: https://theupdateframework.com/ + + +.. toctree:: + + signup-container-only/index + ci-selection + fioup-registration/index + +Additional Resources +-------------------- +- :ref:`ref-container-only-arch` architecture +- :ref:`ref-compose-apps` diff --git a/source/getting-started/gs-lmp.rst b/source/getting-started/gs-lmp.rst new file mode 100644 index 00000000..c41e2a6c --- /dev/null +++ b/source/getting-started/gs-lmp.rst @@ -0,0 +1,16 @@ +.. _ref-gs-lmp: + +Getting Started with the LmP +============================ + +LmP based Factories are available if you want to use the Yocto Project and OSTree. +These Factories produce immutable OS images as well as all the features of a container-only Factory. +A paid subscription allows you to customize the base image and perform other advanced operations such as firmware updates and secure boot tooling. + +.. toctree:: + + signup-lmp/index + flash-device/index + register-device/index + install-fioctl/index + building-deploying-app/index diff --git a/source/getting-started/index.rst b/source/getting-started/index.rst index 0dc61da6..ac6bc2cc 100644 --- a/source/getting-started/index.rst +++ b/source/getting-started/index.rst @@ -1,11 +1,13 @@ Getting Started =============== +FoundriesFactory includes two ways of getting started. +Most people, such as :ref:`gs-arduino-uno-q` users, will be using a container-only Factory and can follow the steps outlined in the :ref:`ref-gs-container-only` guide. +Other users will be creating a Factory based on the Linux microPlatform and call follow the steps outlined in the :ref:`ref-gs-lmp` guide. + .. toctree:: + :maxdepth: 1 - signup/index - flash-device/index - register-device/index - install-fioctl/index - building-deploying-app/index arduino-uno-q/index + gs-container-only + gs-lmp diff --git a/source/getting-started/signup-container-only/index.rst b/source/getting-started/signup-container-only/index.rst new file mode 100644 index 00000000..63ba426c --- /dev/null +++ b/source/getting-started/signup-container-only/index.rst @@ -0,0 +1,69 @@ +.. _gs-signup-co: + +Signing Up +========== + +To begin using the FoundriesFactory™ Platform, start with `creating an account `_ with us. + +.. figure:: /_static/getting-started/signup/signup.png + :width: 380 + :align: center + :target: signup_ + :alt: signup form + + This is the beginning of your journey. + +.. _signup: https://app.foundries.io/signup + +Once the signup process is complete, you can proceed with creating a Factory. + +Creating Your Factory +===================== + +:ref:`ref-factory` is the start of your embedded OS, tailored specifically for your product. +When your account is created, it is not associated with any factories. +Create one by clicking :guilabel:`New Factory`. + +.. figure:: /_static/getting-started/signup/no-factories.png + :width: 900 + :align: center + :alt: no Factories screen + + Your journey begins empty handed + +.. _gs-select-platform-co: + +Selecting Your Container-Only Platform +###################################### + +Choose a hardware platform from the dropdown menu in the **Create Factory** wizard and continue. +Click :guilabel:`Create Factory` once your details are entered. + +.. warning:: + + Once a Factory is created, the chosen platform/machine and Factory name cannot be changed. + Create a new Factory or `contact support `_ if a mistake is made. + +The dropdown menu includes a range of choices. You must choose one of these options to create a container-only Factory: + +- Community Edition Arm64 +- Community Edition x86 +- Arduino UNO Q + +The Initial Target +################## + +Factory creation takes 30-60 seconds to complete. +Once created, your Factory will show an initial "Target" and you will receive an email. + +.. figure:: /_static/getting-started/signup/build.png + :width: 900 + :align: center + :alt: Targets view showing prebuilt target + + FoundriesFactory Targets + +A Target is a reference to the specific version of applications. +When developers push code, FoundriesFactory produces a new :term:`Target`. +Registered devices then update and install Targets. +The initial Target for a new Factory does not include any applications. diff --git a/source/getting-started/signup/index.rst b/source/getting-started/signup-lmp/index.rst similarity index 100% rename from source/getting-started/signup/index.rst rename to source/getting-started/signup-lmp/index.rst diff --git a/source/reference-manual/factory/container-only-architecture.rst b/source/reference-manual/factory/container-only-architecture.rst new file mode 100644 index 00000000..82e5b07c --- /dev/null +++ b/source/reference-manual/factory/container-only-architecture.rst @@ -0,0 +1,53 @@ +.. _ref-container-only-arch: + +Container-Only Factories +======================== + +Container-only Factories provide a way for you to manage fleets of Arm64 or x86 devices that do not run the LmP. + +Components +---------- + +1. **App Developer**: An individual or team that creates and maintains containerized applications using Docker Compose. +2. **containers.git**: The Foundries.io provided Git repository where application developers push their Docker Compose files and related resources. +3. **CI Job**: The Foundries.io provided CI job that is triggered when changes are pushed to the ``containers.git`` repository. + This job builds the container images, packages the application, and publishes it to the Container Registry and OTA Service. +4. **Container Registry**: A storage service where built container images are stored and made available for devices to download. +5. **OTA Service**: The Over-The-Air service that manages application metadata, including available versions and update information. + It interacts with devices to facilitate updates. +6. **Database**: A storage system used by the OTA Service to persist application metadata and device status information. +7. **Device Gateway**: A communication endpoint that devices use to check for updates and report their status. + It acts as an intermediary between devices and the OTA Service. +8. **fioup**: The OTA update client running on the device. + It checks for updates, downloads necessary container images from the Container Registry, and uses ``composeapp`` to manage the application lifecycle on the device. + +App Creation And Publishing Flow +-------------------------------- +.. mermaid:: + + flowchart LR + n1("App developer") -- push --> n2["contaners.git"] + n2 -- trigger --> n3["CI Job"] + n3 -- publish app and its images --> n4["Container Registry"] + n3 -- publish metadata about app --> n5["OTA Service"] + n5 -- store app metadata --> n6[("Database")] + +1. An application developer pushes a new compose app to the ``containers.git`` repository. +2. This triggers the Foundries.io CI job that builds app's container images, packages the app, and publishes them to Container Registry. +3. The CI job also generates and publishes metadata about the built and published app to the OTA Service. +4. The OTA Service stores the app metadata in its database. + +Device Update Flow +------------------ +.. mermaid:: + + flowchart LR + n1("fioup
<device>") <-- check for updates
upload device status --> n2["Device Gateway"] + n1 <-- fetch app blobs --> n3["Container Registry"] + n2 <-- get list of available apps
persist device status --> n4["OTA Service"] + +1. The ``fioup`` client on the device checks for updates by communicating with the Device Gateway. +2. If there are updates available, ``fioup`` can start updating apps to the specified version. +3. The app update involves fetching the necessary container images from the Container Registry, and then using ``composeapp`` to orchestrate the update process. +4. Once the update is complete, ``fioup`` uploads the device status back to the Device Gateway, which in turn persists this information in the OTA Service. + diff --git a/source/reference-manual/factory/factory.rst b/source/reference-manual/factory/factory.rst index d11e849e..09f01bd1 100644 --- a/source/reference-manual/factory/factory.rst +++ b/source/reference-manual/factory/factory.rst @@ -26,8 +26,9 @@ The FoundriesFactory :ref:`sbom` (SBOM) feature can assist with for license comp ci-webhooks event-queues data-retention + container-only-architecture .. seealso:: :ref:`account-management` covers managing a FoundriesFactory subscription and access control settings. - + :ref:`lmp-customization` explores ways of customizing the LmP platform. diff --git a/source/user-guide/custom-ci/custom-ci-for-apps.rst b/source/user-guide/custom-ci/custom-ci-for-apps.rst index 58ecce5e..d35b587a 100644 --- a/source/user-guide/custom-ci/custom-ci-for-apps.rst +++ b/source/user-guide/custom-ci/custom-ci-for-apps.rst @@ -1,19 +1,11 @@ .. _ug-custom-ci-for-apps: -Custom CI To Build Compose App Targets -====================================== - -The FoundriesFactory™ Platform includes all you need to build a containerized application and securely deploy it on devices. -This includes: - -* a git repository -* a CI service that handles the steps to build and delivery apps leveraging the :term:`TUF` compliant OTA service. - -Learn more through this :ref:`tutorial ` on compose apps. +Custom CI for Containers +======================== FoundriesFactory consists of well integrated but loosely coupled services. This allows for using the OTA framework without also using the FoundriesFactory git repos or CI service. -This means you can host your source code anywhere or build your App through any framework, while still leveraging the rest of FoundriesFactory. +You can host your source code anywhere or build your App through any framework, while still leveraging the rest of FoundriesFactory. This section guides you through the steps of creating a custom CI pipeline in GitHub that: @@ -25,24 +17,24 @@ This section guides you through the steps of creating a custom CI pipeline in Gi Prerequisites ------------- -* A successful platform build for the corresponding tag (``custom-ci-devel`` in the example), and the hardware ID (machine) of a device for following along +* A successful platform build for the corresponding tag (``main`` in the example), and the hardware ID (machine) of a device for following along * GitHub repo with source code, Dockerfiles, and a Docker compose file. The prerequisites will look like: -1. A Factory (``lmp-demo``) with a built Target. It has the tag ``custom-ci-devel`` and the hardware ID ``raspberrypi4-64``. +1. A Factory (``lmp-demo``) with a built Target. It has the tag ``main`` and the hardware ID ``arm64-linux``. .. code-block:: console $fioctl targets show 1 -f lmp-demo - + APP HASH --- ---- - ## Target: raspberrypi4-64-lmp-1 + ## Target: arm64-linux-1 Created: 2022-11-30T00:20:31Z - Tags: custom-ci-devel - OSTree Hash: fe15cf8ad5e09136725ef996c93299d70fa0d20bfa2f10651437b8860b9edcdb + Tags: main + OSTree Hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 2. `The GitHub repo`_ that contains a working App implementation. @@ -112,18 +104,7 @@ Use the Fioctl® command ``fioctl targets add`` to do so. Check the Workflow Result ------------------------- -Use ``fioctl targets list`` and ``fioctl targets show`` to check whether the new Targets are registered in the FoundriesFactory OTA service, and whether their content is correct. - -.. note:: - - What if you may want to keep your App source code in a private repo, yet still use the FoundriesFactory CI service? - In this case, check out the following two approaches: - - 1. :ref:`Git Mirroring ` - 2. :ref:`Git Submodules ` - -.. seealso:: - :ref:`ug-custom-ci-for-rootfs` +You can view your Factory Targets in the UI to check whether the new Targets were created, and if their content is correct. .. _FoundriesFactory Registry: https://hub.foundries.io