From 65ca60bf11c591d6c29073e9d69d44805d07963d Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 12:04:01 -0500 Subject: [PATCH 01/13] gs: Rename signup to signup-lmp We are going to introduce the notion of signing up for container-only systems which requires a different signup flow. Signed-off-by: Andy Doan --- source/getting-started/index.rst | 2 +- source/getting-started/{signup => signup-lmp}/index.rst | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename source/getting-started/{signup => signup-lmp}/index.rst (100%) diff --git a/source/getting-started/index.rst b/source/getting-started/index.rst index 0dc61da6..a91c1a5a 100644 --- a/source/getting-started/index.rst +++ b/source/getting-started/index.rst @@ -3,7 +3,7 @@ Getting Started .. toctree:: - signup/index + signup-lmp/index flash-device/index register-device/index install-fioctl/index 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 From 3088cffc899c235fe3679038e1c22b2c5cf512c6 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 12:28:19 -0500 Subject: [PATCH 02/13] gs: Stub out new paths for container-only vs LmP This splits our getting-started logic into a choice between: * Container only factories - the new way for most people * LmP based factories - legacy Signed-off-by: Andy Doan --- source/getting-started/gs-container-only.rst | 6 ++++++ source/getting-started/gs-lmp.rst | 12 ++++++++++++ source/getting-started/index.rst | 12 +++++++----- 3 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 source/getting-started/gs-container-only.rst create mode 100644 source/getting-started/gs-lmp.rst diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst new file mode 100644 index 00000000..b77f0059 --- /dev/null +++ b/source/getting-started/gs-container-only.rst @@ -0,0 +1,6 @@ +.. _ref-gs-container-only: + +Getting Started with Container-only Factories +============================================= + +TODO diff --git a/source/getting-started/gs-lmp.rst b/source/getting-started/gs-lmp.rst new file mode 100644 index 00000000..0031acf8 --- /dev/null +++ b/source/getting-started/gs-lmp.rst @@ -0,0 +1,12 @@ +.. _ref-gs-lmp: + +Getting Started with the LmP +============================ + +.. 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 a91c1a5a..f581d9dc 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-lmp/index - flash-device/index - register-device/index - install-fioctl/index - building-deploying-app/index arduino-uno-q/index + gs-container-only + gs-lmp From 5177853df8cf6f8c41cc2b1f1a77b563160de5c4 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 12:57:55 -0500 Subject: [PATCH 03/13] gs: Add signup instructions for container-only Signed-off-by: Andy Doan --- source/getting-started/gs-container-only.rst | 4 +- .../signup-container-only/index.rst | 67 +++++++++++++++++++ 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 source/getting-started/signup-container-only/index.rst diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst index b77f0059..5fab3272 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -3,4 +3,6 @@ Getting Started with Container-only Factories ============================================= -TODO +.. toctree:: + + signup-container-only/index 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..764099a6 --- /dev/null +++ b/source/getting-started/signup-container-only/index.rst @@ -0,0 +1,67 @@ +.. _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 + +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. From a3cddabb6645f3fb723d3a9d844072cdfd86ff61 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 14:56:04 -0500 Subject: [PATCH 04/13] gs: Add fioup directions Signed-off-by: Andy Doan --- .../getting-started/fioup-registration/index.rst | 14 ++++++++++++++ source/getting-started/gs-container-only.rst | 1 + 2 files changed, 15 insertions(+) create mode 100644 source/getting-started/fioup-registration/index.rst 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 index 5fab3272..af101cdc 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -6,3 +6,4 @@ Getting Started with Container-only Factories .. toctree:: signup-container-only/index + fioup-registration/index From f61e69da8c9c5e1982e89e65c044343f40b6b130 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 15:25:01 -0500 Subject: [PATCH 05/13] gs: Add CI selection choice doc Signed-off-by: Andy Doan --- source/getting-started/ci-selection.rst | 24 ++++++++++++++++++++ source/getting-started/gs-container-only.rst | 1 + 2 files changed, 25 insertions(+) create mode 100644 source/getting-started/ci-selection.rst diff --git a/source/getting-started/ci-selection.rst b/source/getting-started/ci-selection.rst new file mode 100644 index 00000000..9d0e60a4 --- /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 Foundriesio managed solution you'll 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, you'll need to follow the steps outlined in the :ref:`Custom CI ` guide. diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst index af101cdc..c596826b 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -6,4 +6,5 @@ Getting Started with Container-only Factories .. toctree:: signup-container-only/index + ci-selection fioup-registration/index From 211acf83a26127e3866b7d9d1dcdc0c34e23f78f Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 15:46:32 -0500 Subject: [PATCH 06/13] gs: Remove redundant information from Arduino guide Signed-off-by: Andy Doan --- .../getting-started/arduino-uno-q/index.rst | 41 ++----------------- 1 file changed, 4 insertions(+), 37 deletions(-) diff --git a/source/getting-started/arduino-uno-q/index.rst b/source/getting-started/arduino-uno-q/index.rst index cf76a31c..6be37c9d 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/ From 188b5b5761ce9aa883071242d2990f667d93c97b Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 16:00:00 -0500 Subject: [PATCH 07/13] ug: Update Custom CI for containers This PR makes several changes to this doc to make it less verbose and more inlined with how we are pitching this to users. Notable changes: * Title change. People are coming here to "build containers", this doc will help them understand they are building a compose app. * Changing of the Target example to be on `main` and for a hwid of `amd64-linux` to match the Arduino experience. * Dropping references to Fioctl in favor of the UI in order to try and make a path for evaluting the product without needing Fioctl. * Dropping the "sea also" - the "CI for rootfs" is already showing up at the bottom of the page and we don't want to highlight this any more than necessary for now. * Dropping references to git mirroring and submodules. Let's encourage custom CI over that moving forward. Signed-off-by: Andy Doan --- .../custom-ci/custom-ci-for-apps.rst | 39 +++++-------------- 1 file changed, 10 insertions(+), 29 deletions(-) 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..b7719f2e 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 ``amd64-linux``. .. code-block:: console $fioctl targets show 1 -f lmp-demo - + APP HASH --- ---- - ## Target: raspberrypi4-64-lmp-1 + ## Target: amd64-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 From 17bc5d3b5f016a6ebf625e5b42206b7fb0eb3c68 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Wed, 15 Oct 2025 16:43:56 -0500 Subject: [PATCH 08/13] Add a container-only architecture document Signed-off-by: Andy Doan --- requirements.txt | 3 +- source/conf.py | 1 + source/getting-started/gs-container-only.rst | 5 ++ .../factory/container-only-architecture.rst | 49 +++++++++++++++++++ source/reference-manual/factory/factory.rst | 3 +- 5 files changed, 59 insertions(+), 2 deletions(-) create mode 100644 source/reference-manual/factory/container-only-architecture.rst 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/gs-container-only.rst b/source/getting-started/gs-container-only.rst index c596826b..af6aae13 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -8,3 +8,8 @@ Getting Started with Container-only Factories 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/reference-manual/factory/container-only-architecture.rst b/source/reference-manual/factory/container-only-architecture.rst new file mode 100644 index 00000000..40ed2106 --- /dev/null +++ b/source/reference-manual/factory/container-only-architecture.rst @@ -0,0 +1,49 @@ +.. _ref-container-only-arch: + +Container-only Factories +======================== + +Container-only Factories provide a way for people to manage fleets of Arm64 or x86 devices that don't 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 provided Git repository where application developers push their Docker Compose files and related resources. +3. **CI Job**: The Foundries 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 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 app 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. From c98458e454773e0feef46989498316c3e35bfa62 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Thu, 16 Oct 2025 08:59:15 -0500 Subject: [PATCH 09/13] fixup! ug: Update Custom CI for containers --- source/user-guide/custom-ci/custom-ci-for-apps.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 b7719f2e..4a6af954 100644 --- a/source/user-guide/custom-ci/custom-ci-for-apps.rst +++ b/source/user-guide/custom-ci/custom-ci-for-apps.rst @@ -23,7 +23,7 @@ Prerequisites The prerequisites will look like: -1. A Factory (``lmp-demo``) with a built Target. It has the tag ``main`` and the hardware ID ``amd64-linux``. +1. A Factory (``lmp-demo``) with a built Target. It has the tag ``main`` and the hardware ID ``arm64-linux``. .. code-block:: console @@ -31,7 +31,7 @@ The prerequisites will look like: APP HASH --- ---- - ## Target: amd64-linux-1 + ## Target: arm64-linux-1 Created: 2022-11-30T00:20:31Z Tags: main OSTree Hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 From 24b22d5a893e242d03e268e2c1c1fbf60540047d Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Thu, 16 Oct 2025 09:28:50 -0500 Subject: [PATCH 10/13] gs: Add a little blurb to indicate the signup needs to complete Signed-off-by: Andy Doan --- source/getting-started/signup-container-only/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/getting-started/signup-container-only/index.rst b/source/getting-started/signup-container-only/index.rst index 764099a6..dd37efb5 100644 --- a/source/getting-started/signup-container-only/index.rst +++ b/source/getting-started/signup-container-only/index.rst @@ -15,6 +15,8 @@ To begin using the FoundriesFactory™ Platform, start with `creating an account .. _signup: https://app.foundries.io/signup +Once the signup process is complete, you can proceed with creating a Factory. + Creating Your Factory ===================== From 5066cdebf01d3def1cf1eb3c4a860139947914a4 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Thu, 16 Oct 2025 11:00:45 -0500 Subject: [PATCH 11/13] gs: Add descriptions about LmP and container-only factories Signed-off-by: Andy Doan --- source/getting-started/gs-container-only.rst | 16 ++++++++++++++++ source/getting-started/gs-lmp.rst | 4 ++++ 2 files changed, 20 insertions(+) diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst index af6aae13..5b739cea 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -3,6 +3,22 @@ Getting Started with Container-only Factories ============================================= +Container-only Factories allow users to experience a FoundriesFactory without having to run the Linux microPlatform on their 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's 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, its 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 diff --git a/source/getting-started/gs-lmp.rst b/source/getting-started/gs-lmp.rst index 0031acf8..8836c7a9 100644 --- a/source/getting-started/gs-lmp.rst +++ b/source/getting-started/gs-lmp.rst @@ -3,6 +3,10 @@ Getting Started with the LmP ============================ +LmP based Factories are available for people wanting to use Yocto and OSTree. +These Factories produce immutable OS images as well as all the features of a container-only Factory. +Paid subscriptions allow users to customize this base image and perform other advanced operations such as firmware updates and secure boot tooling. + .. toctree:: signup-lmp/index From b78a496c86b779d3475418577822e62232e13f93 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Tue, 21 Oct 2025 11:10:37 -0500 Subject: [PATCH 12/13] Apply suggestion from @kprosise Co-authored-by: Katrina Prosise --- .../getting-started/arduino-uno-q/index.rst | 2 +- source/getting-started/ci-selection.rst | 10 +++---- source/getting-started/gs-container-only.rst | 14 +++++---- source/getting-started/gs-lmp.rst | 4 +-- source/getting-started/index.rst | 4 +-- .../signup-container-only/index.rst | 2 +- .../factory/container-only-architecture.rst | 30 +++++++++++-------- .../custom-ci/custom-ci-for-apps.rst | 2 +- 8 files changed, 37 insertions(+), 31 deletions(-) diff --git a/source/getting-started/arduino-uno-q/index.rst b/source/getting-started/arduino-uno-q/index.rst index 6be37c9d..ca026891 100644 --- a/source/getting-started/arduino-uno-q/index.rst +++ b/source/getting-started/arduino-uno-q/index.rst @@ -27,7 +27,7 @@ Using the Arduino UNO Q with FoundriesFactory This section is specific to Arduino UNO Q users. The Arduino UNO Q ships with a Debian base image. -It is supported by the "Container-only Factory" solution. +It is supported by the Container-only Factory solution. Follow the :ref:`ref-gs-container-only` guide to get started. .. note:: diff --git a/source/getting-started/ci-selection.rst b/source/getting-started/ci-selection.rst index 9d0e60a4..9c01d274 100644 --- a/source/getting-started/ci-selection.rst +++ b/source/getting-started/ci-selection.rst @@ -6,19 +6,19 @@ FoundriesFactories supports two different modes for building Targets. FoundriesFactory Managed ------------------------ -Every Factory includes a `containers.git` hosted at source.foundries.io. +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 Foundriesio managed solution you'll need to: +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:`Install Fioctl ` in order to work with ``source.foundries.io``. - :ref:`Build and deploy ` your first application. -Self-hosted +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, you'll need to follow the steps outlined in the :ref:`Custom CI ` guide. +To get started with the self-hosted option, follow the steps outlined in the :ref:`Custom CI ` guide. diff --git a/source/getting-started/gs-container-only.rst b/source/getting-started/gs-container-only.rst index 5b739cea..e6fa1875 100644 --- a/source/getting-started/gs-container-only.rst +++ b/source/getting-started/gs-container-only.rst @@ -1,17 +1,19 @@ .. _ref-gs-container-only: -Getting Started with Container-only Factories +Getting Started With Container-Only Factories ============================================= -Container-only Factories allow users to experience a FoundriesFactory without having to run the Linux microPlatform on their device. +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's 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, its not verfied by Fioup in the Community Edition. +- 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 diff --git a/source/getting-started/gs-lmp.rst b/source/getting-started/gs-lmp.rst index 8836c7a9..09019cbc 100644 --- a/source/getting-started/gs-lmp.rst +++ b/source/getting-started/gs-lmp.rst @@ -3,9 +3,9 @@ Getting Started with the LmP ============================ -LmP based Factories are available for people wanting to use Yocto and OSTree. +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. -Paid subscriptions allow users to customize this base image and perform other advanced operations such as firmware updates and secure boot tooling. + A paid subscription allows you to customize the base image and perform other advanced operations such as firmware updates and secure boot tooling. .. toctree:: diff --git a/source/getting-started/index.rst b/source/getting-started/index.rst index f581d9dc..ac6bc2cc 100644 --- a/source/getting-started/index.rst +++ b/source/getting-started/index.rst @@ -2,8 +2,8 @@ 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. +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 diff --git a/source/getting-started/signup-container-only/index.rst b/source/getting-started/signup-container-only/index.rst index dd37efb5..63ba426c 100644 --- a/source/getting-started/signup-container-only/index.rst +++ b/source/getting-started/signup-container-only/index.rst @@ -33,7 +33,7 @@ Create one by clicking :guilabel:`New Factory`. .. _gs-select-platform-co: -Selecting Your Container-only Platform +Selecting Your Container-Only Platform ###################################### Choose a hardware platform from the dropdown menu in the **Create Factory** wizard and continue. diff --git a/source/reference-manual/factory/container-only-architecture.rst b/source/reference-manual/factory/container-only-architecture.rst index 40ed2106..82e5b07c 100644 --- a/source/reference-manual/factory/container-only-architecture.rst +++ b/source/reference-manual/factory/container-only-architecture.rst @@ -1,21 +1,25 @@ .. _ref-container-only-arch: -Container-only Factories +Container-Only Factories ======================== -Container-only Factories provide a way for people to manage fleets of Arm64 or x86 devices that don't run the LmP. +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 provided Git repository where application developers push their Docker Compose files and related resources. -3. **CI Job**: The Foundries 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. +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. +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. +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 -------------------------------- @@ -28,8 +32,8 @@ App Creation And Publishing Flow 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 CI job that builds app's container images, packages the app, and publishes them to Container Registry. +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. @@ -42,8 +46,8 @@ Device Update Flow 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 app 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. +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/user-guide/custom-ci/custom-ci-for-apps.rst b/source/user-guide/custom-ci/custom-ci-for-apps.rst index 4a6af954..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,6 +1,6 @@ .. _ug-custom-ci-for-apps: -Custom CI For Containers +Custom CI for Containers ======================== FoundriesFactory consists of well integrated but loosely coupled services. From c1b99dca4fc2f6ba17c000b6ae2ce77deac8e047 Mon Sep 17 00:00:00 2001 From: Andy Doan Date: Tue, 28 Oct 2025 08:12:59 -0500 Subject: [PATCH 13/13] Update source/getting-started/gs-lmp.rst Co-authored-by: Katrina Prosise --- source/getting-started/gs-lmp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/getting-started/gs-lmp.rst b/source/getting-started/gs-lmp.rst index 09019cbc..c41e2a6c 100644 --- a/source/getting-started/gs-lmp.rst +++ b/source/getting-started/gs-lmp.rst @@ -5,7 +5,7 @@ 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. +A paid subscription allows you to customize the base image and perform other advanced operations such as firmware updates and secure boot tooling. .. toctree::