foundriesio · kprosise · Oct 28, 2025 · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025
diff --git 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
@@ -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
@@ -24,48 +24,15 @@
 
 .. 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 <signup_>`_ 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
@@ -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 <gs-install-fioctl>` in order to work with ``source.foundries.io``.
+- :ref:`Build and deploy <gs-building-deploying-app>` 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 <ug-custom-ci-for-apps>` guide.
diff --git a/source/getting-started/fioup-registration/index.rst 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
@@ -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 <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
@@ -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
@@ -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
@@ -0,0 +1,69 @@
+.. _gs-signup-co:
+
+Signing Up
+==========
+
+To begin using the FoundriesFactory™ Platform, start with `creating an account <signup_>`_ 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 <https://support.foundries.io>`_ 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 → source/getting-started/signup-lmp/index.rst b/source/getting-started/signup/index.rst → 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
@@ -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<br>&lt;device&gt;") <-- check for updates<br>upload device status --> n2["Device Gateway"]
+      n1 <-- fetch app blobs --> n3["Container Registry"]
+      n2 <-- get list of available apps</br>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
@@ -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
@@ -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 <tutorial-compose-app>` 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 <ug-mirror-action>`
-    2. :ref:`Git Submodules <ug-submodule>`
-
-.. 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