content/architecture/platform-guide.md

@@ -317,6 +317,18 @@ by the [Apertis GitLab instance](https://gitlab.apertis.org/):
 
 ## Image creation
 
+Image creation is the point where a set of standard packages are combined to
+build a solution for a specific use case. This goal is accomplish thanks to
+[Debos](https://github.com/go-debos/debos), a flexible tool to configure the
+build of Debian-based operating systems. Debos uses tools like `debootstrap`
+already present in the environment and relies on virtualisation to securely do
+privileged operations without requiring root access.
+
+Additionally at this stage customizations can be applied by using overlays.
+This process allows the default content of the packages to be combined with
+custom modifications to provide the desired solution. A common case is to apply overlays to
+change some default system settings found in `/etc` such as default hostname.
+
 Ospacks and how they should be processed to generate images are defined through
 YAML files.
 

content/concepts/preparing-hawkbit-for-production.md

@@ -12,7 +12,9 @@ outputs = ["html", "pdf-in"]
 The Apertis project has been experimenting with the use of
 [Eclipse hawkBit](https://www.eclipse.org/hawkbit/) as a mechanism for the
 deployment of system updates and applications to target devices in the field.
-The current emphasis being placed on system updates.
+The current emphasis is being placed on system updates, though hawkBit can also
+be used to address different software distribution use cases such as to
+distribute system software, updates and even apps from an app store.
 
 Apertis has recently deployed a [hawkBit instance](https://hawkbit.apertis.org)
 into which the
@@ -24,11 +26,14 @@ can be used to
 [deploy updates to an Apertis target]({{< ref "deployment-management.md" >}}).
 
 The current instance is proving valuable for gaining insight into how hawkBit
-can be used as part of the broader Apertis project, however more work is
-required to reach the point where this infrastructure (or an equivalent
-deployment elsewhere) would be ready for production use. In this document we
-will describe the steps we feel that need to be taken to provide a reference
-deployment that could be more readily suitable for production.
+can be used as part of the broader Apertis project. hawkBit is already in use
+elsewhere, notably by
+[Bosch as part of its IoT infrastructure](https://docs.bosch-iot-rollouts.com/documentation/index.html),
+however more work is required to reach the point where the Apertis
+infrastructure (or a deployment based on the Apertis infrastructure) would be
+ready for production use. In this document we will describe the steps we feel
+that need to be taken to provide a reference deployment that could be more
+readily suitable for production.
 
 # Evaluation Report
 

content/designs/system-updates-and-rollback.md

@@ -148,6 +148,14 @@ be customizable. For instance, some products may chose to only roll back the
 base OS and keep applications untouched, some other products may choose to roll
 applications back as well.
 
+Apertis recommends rollbacks to be allowed only after a system upgrade and before
+confirming that the new version works as expected. Enabling rollbacks in general
+could be a potential security issue, since a rollback could be used to install
+a previous release with vulnerabilities. By taking this approach it also
+simplifies how applications have to deal with base OS rollbacks, since
+applications should only upgrade their configuration accordingly when the new
+version is confirmed and there is no possible rollback.
+
 ### Reset to clean state
 
 The user must be able to restore his device to a clean state, destroying
@@ -158,6 +166,14 @@ all user data and all device-specific system configuration.
 An interface must be provided by the updates and rollback mechanism to allow
 HMI to query the current update status, and trigger updates and rollback.
 
+### Handling settings and data
+
+System upgrades should keep both settings and data safe and intact as this
+process should be as transparent as possible to the end user. As described in
+[preferences and persistence]( {{< ref "preferences-and-persistence.md" >}} )
+settings have a default value, which can change on upgrade, this results in
+the required solution being more complex than it might initially seem.
+
 ## Existing system update mechanisms
 
 ### Debian tools
@@ -173,6 +189,28 @@ management is not required for final users of Apertis. For example:
   way. This can be an error prone manual process and might not be accomplished
   cleanly.
 
+In relation to system settings as defined in
+[preferences and persistence]( {{< ref "preferences-and-persistence.md" >}} ),
+Debian tools use a very simple approach. On package upgrades the `dpkg`
+will perform a check taking into account
+- current version default configuration file
+- new version default configuration file
+- current configuration file
+
+Different scenarios arise depending on whether user has applied changes to the
+configuration file. If current default configuration file is the same as
+current, then the user hadn't change it, which implies that it can be safely
+upgraded (if it is required).
+
+However, if the current default configuration file is different from current
+the user had applied some changes, so it can't be upgraded silently. In this
+case `dpkg` asks the user to choose the version to use. This approach is not
+suitable for automated upgrades where there is no user interaction.
+
+To overcome some of these limitations modern systems tend to use overlays
+to have a read-only partition with default values and an upper layer with
+custom values.
+
 ### ChromeOS
 
 ChromeOS uses an A/B parallel partition approach. Instead of upgrading the system
@@ -740,6 +778,36 @@ image for decompression.
 The content of the update file is extracted into the temporary directory
 and the signature is checked for the extracted commit tree.
 
+### Settings
+
+As described in
+[preferences and persistence]( {{< ref "preferences-and-persistence.md" >}} )
+there are different types of settings which should be preserved across updates.
+The setting should either be kept intact or updated to reflect new logic of the
+application.
+
+When using `OSTree`, most of the file system is read-only. Since system
+settings need write support, the `/etc` and `/var` partitions
+are configured to be read-write. This also applies to the `/home`
+partition, with it being configured as read-write so user data and
+settings can be preserved.
+
+During an `OSTree` upgrade, a new commit is applied on the `OSTree` repo,
+this provides the new content that will be used for the read-only portions of
+the rootfs, but does not modify the read-write parts.
+To handle the upgrade of system settings stored in `/etc`, a copy of its
+default values are kept in `/usr/etc` which is updated with the new commit.
+default values is kept in `/usr/etc` which is updated with the new commit.
+Thanks to this information `OSTree` can detect the files that have been changed
+and apply a 3-way merge, to update the `/etc`.
+
+This process allows to update settings to new defaults for files that were not
+modified and keep intact those that were.
+
+Applications are encouraged to handle settings adaptation to new version
+following the guidelines described in [user and user data management]( {{< ref "#user-and-user-data-management" >}} )
+and [preference and persistence]( {{< ref preferences-and-persistence.md >}} ).
+
 ### Error handling
 
 If for any reason the update process fails to complete, the update will

content/release/v2021pre/releasenotes.md

@@ -207,7 +207,7 @@ seen some of the attention it deserve, with plenty of cleanups and fixes.
 
 ### Improved image download page
 
-The new [download page]({{{< ref "download.md" >}}) provides a streamlined way
+The new [download page]({{< ref "download.md" >}}) provides a streamlined way
 for users to find the right download matching their needs, addressing some
 challenges with the raw indexing of all the release artifacts.