Update platform guide splitting out details

Make the platform guide more high-level, splitting out details into a new
workflow guide which will be reworked in a later commit.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

content/architecture/workflow-guide.md

++++
+title = "The Apertis Workflow: From Sources to Deployment"
+weight = 100
+
+date = "2021-04-29"
++++
+
+Apertis is built on top of Debian `deb` packages for their high quality and
+modularity.  All package source code is stored in
+[GitLab](https://gitlab.apertis.org/), where they are grouped into the
+following categories:
+
+- `target`: packages intended for use in product images
+- `development`: additional packages needed to build `target` and development
+  tools
+- `hmi`: packages for the current reference HMI on top of `target`
+- `sdk`: packages to build the SDK virtual machine recommended for development
+
+In case of common interests new packages can easily be introduce in the
+relevant GitLab groups. It is also possible to create additional projects in
+GitLab for e.g.  product specific software packages or product specific
+modifications that build on top of the common baselines but aren't suitable for
+more general inclusion.
+
+Automation implemented via GitLab CI/CD pipelines is provided to perform sanity
+check builds of the packages. CI/CD pipelines are also implemented to upload
+changes to the
+[Open Build Service -(OBS) instance](https://build.collabora.com) provided by
+Collabora.
+
+OBS takes care of automatically building the package sources for all the
+configured architectures (`x86_64`, `armv7l`, `aarch64`) and publishes the
+results as signed APT repositories. Each package is built in a closed,
+well-defined environment where OBS automatically installs all the build tools
+and resolves dependencies from a clean state using the packages it has built
+already: if any dependency is missing the build fails and the developer is
+notified. Build failures are reported back into the relevant GitLab pipeline.
+
+Most of the package sources get automatically updated from the latest Debian
+Stable release or have been manually picked from a later Debian release or
+straight from the project upstream when more up-to-date versions have been
+deemed beneficial (notably Apertis includes the
+[latest Linux LTS kernel]({{< ref "release-flow.md#linux-kernel-release-flow" >}})
+available when an Apertis release is made). This allows Apertis to share
+bug fixes and security fixes with the efforts done by the wider Debian
+community.
+
+After OBS has finished building a package, the results get published in a
+Debian package repository. The open-source packages from Apertis can be found
+in the public
+[Apertis Debian repositories](https://repositories.apertis.org/apertis/).
+
+The packages in these repositories can then be used to build images suitable
+for deployment onto a variety of targets, e.g. hardware boards (reference or
+product specific), virtual machines (e.g. for development), container images
+etc etc.
+
+The overall strategy for building these deployments is to separate it in
+various stages starting with early common stages (e.g. a common rootfs) and
+then further specializing in hardware or deployment specific additions (e.g.
+kernel and bootloader for a specific board). 
+
+Each stage is represented by a [Debos](https://github.com/go-debos/debos)
+recipes, and in particular the main stages in the
+[current image building pipeline](https://gitlab.apertis.org/infrastructure/apertis-image-recipes)
+are:
+
+- `ospack`: prepares the set of user space binary packages that are not
+  specific to a particular SoC/platform or deployment method, producing
+  tarballs
+- deployment method: applies the transformations needed to make updates
+  available through OSTree or with the
+  [`ade sysroot`]( {{< ref "ade.md" >}} ) tool
+- platform: contains the hardware-specific packages for a particular
+  SoC/platform, like bootloader, kernel, codecs, GL stack, etc., producing the
+  images meant to be booted on devices
+
+The reason for this split is that it allows the creation of just one SoC,
+platform or even board specific recipe which can be combined with a
+selection of ospacks. Typically Apertis has a `target` ospack with only the
+software meant to go into the final product and a `minimal` ospack which
+contains an even smaller subset, targeting headless systems.
+
+For instance the `target` and `minimal` ospacks for `arm64` could be combined
+with the U-Boot and Raspberry Pi recipes to generate four possible combinations
+of flashable images, targeting either the Renesas R-Car or Raspberry Pi
+platforms
+
+Generating images does not involve rebuilding all the packages from source and
+can thus be done quite quickly and flexibly.
+
+The whole pipeline is controlled through YAML files: configuring partitions,
+bootloaders; determining which packages gets installed, which overlays is to be
+applied; and arbitrary customization shell scripts to be run over the rootfs in
+a QEMU-based virtualized environment.
+
+This process is usually automatically run by GitLab CI/CD pipeline, but during
+development can be run on developers machines as well, fetching packages from
+the same OBS binary repositories.
+
+Once images are generated, the GitLab CI/CD pipeline will schedule a batch of tests on
+the [LAVA instance hosted by Collabora](https://lava.collabora.co.uk) which
+will take care of deploying the freshly generated images on actual target
+devices running in the Collabora device farm, and of controlling them over
+serial connections to run the defined test cases and gather the results.
+
+![](/images/apertis-functional-view.svg)
+
+# The workflow
+
+The key points in the workflow for Apertis components are thus:
+
+- the [VirtualBox-based Apertis SDK]( {{< ref "virtualbox.md" >}} ) is used for
+  development
+- sources are stored on the
+  [GitLab code hosting service](https://gitlab.apertis.org) with
+  [Debian-compatible](https://www.debian.org/doc/debian-policy/) packaging
+  instructions
+- GitLab is used for code review, with every branch automatically build tested
+  to provide quick feedback to the developer
+- the implemented GitLab CI/CD pipelines push new releases on release branches
+  to OBS
+- [OBS](https://build.collabora.co.uk) builds source packages and generates
+  binary packages in controlled environments
+- every night GitLab CI/CD pipelines generate ospacks from the repositories
+  built by OBS
+- the generated ospacks are combined with other recipes by GitLab CI/CD
+  pipelines to produce deployable images
+- on success, the pipeline triggers on-device tests on
+  [LAVA](https://lava.collabora.co.uk) to check the produced images
+- [Phabricator](https://phabricator.apertis.org) is used for project management
+
+## Software components packaging (deb)
+
+For all the software components meant to be included in the images Apertis uses
+the [`deb` packaging format](https://wiki.debian.org/Packaging) used by Debian.
+
+To package a component from scratch, Debian provides [a short guide to get
+started](https://wiki.debian.org/Packaging/Intro).
+
+The VirtualBox-based
+[Apertis SDK virtual machine images]( {{< ref "virtualbox.md" >}} ) ship with
+all the needed tools installed, providing a reliable, self-contained
+environment ready to be used.
+
+Once the component has been packaged, its sources can be uploaded to GitLab in
+a personal project, such that the developer is free to experiment and iterate
+until the component is ready to be submitted to the appropriate GitLab project.
+
+## Open Build Service (OBS)
+
+Open Build Service is the backbone of the package building infrastructure in
+Apertis.  It stores source packages and builds them in controlled environments
+for all the configured CPU architectures.
+
+The source packages, as uploaded by the GitLab CI/CD pipelines, are grouped in
+projects that can be stacked such that each stacked project will automatically
+share the packages in the underlying projects with all the other projects
+stacked on top of them.
+
+This provides a lot of flexibility to handle different groups working on
+different products with different schedules while still sharing a common core.
+
+## Code hosting and review process
+
+Apertis heavily [relies on GitLab](https://gitlab.apertis.org) for the
+[development of components]( {{< ref "development_process.md" >}} ),
+with source code hosted on Apertis GitLab server being automatically submitted
+to OBS when releases are made.
+
+Each merge request should be
+[reviewed on GitLab]( {{< ref "contributions.md#review" >}} ) before it can
+land in one of the git repository release branches and thus on OBS.
+
+## GitLab CI/CD automation
+
+Automated tasks in Apertis are orchestrated by the CI/CD functionality provided
+by the [Apertis GitLab instance](https://gitlab.apertis.org/):
+
+- build-testing commits pushed to git branches
+- submitting release commits to OBS
+- running the pipeline to generate ospacks and deployable images
+- triggering tests on the devices attached to LAVA
+
+## 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.
+
+Ospacks and how they should be processed to generate images are defined through
+YAML files.
+
+This is an example configuration for an ARMv7 image, `image-armhf.yaml`:
+
+```
+architecture: armhf
+actions:
+  - action: unpack
+    file: ospack-armhf.tar.gz
+    compression: gz
+
+  - action: apt
+    description: Install hardware support packages
+    recommends: false
+    packages:
+      - linux-image-4.9.0-0.bpo.2-armmp-unsigned
+      - u-boot-common
+
+  - action: image-partition
+    imagename: "apertis-armhf.img"
+    imagesize: 4G
+    partitiontype: gpt
+    mountpoints:
+      - mountpoint: /
+        partition: root
+        flags: [ boot ]
+    partitions:
+      - name: root
+        fs: ext4
+        start: 0%
+        end: 100%
+
+  - action: filesystem-deploy
+    description: Deploy the filesystem onto the image
+
+  - action: run
+    chroot: true
+    command: update-u-boot
+
+  - action: run
+    description: Create bmap file
+    postprocess: true
+    command: bmaptool create apertis-armhf.img > apertis-armhf.img.bmap
+
+  - action: run
+    description: Compress image file
+    postprocess: true
+    command: gzip -f apertis-armhf.img
+```
+
+And this is the `ospack-armhf.yaml` configuration for the ARMv7 ospack:
+
+```
+architecture: armhf
+
+actions:
+  - action: debootstrap
+    suite: "17.06"
+    keyring-package: apertis-archive-keyring
+    components:
+      - target
+    mirror: https://repositories.apertis.org/apertis
+    variant: minbase
+
+  - action: apt
+    description: Install basic packages
+    packages: [ procps, sudo, openssh-server, adduser ]
+
+  - action: run
+    description: Setup user account
+    chroot: true
+    script: setup-user.sh
+
+  - action: run
+    description: Configure the hostname
+    chroot: true
+    command: echo apertis > /etc/hostname
+
+  - action: overlay
+    description: Overlay systemd-networkd configuration
+    source: networkd
+
+  - action: run
+    description: Configure network services
+    chroot: true
+    script: setup-networking.sh
+
+  - action: pack
+    compression: gz
+    file: ospack-armhf.tar.gz
+```
+
+Additionally at this stage customizations can be applied by using overlays.
+This process allows the default content of 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 or default package configuration.
+
+As an example of this mechanism, the following section is used to customize the
+behaviour of `dpkg`
+
+```
+  - action: overlay
+    source: overlays/dpkg-exclusions
+```
+
+Thanks to this action, the contents of the `overlays/dpkg-exclusions`
+directory will be applied to the image, which in this case consist of
+the file:
+
+    etc/dpkg/dpkg.cfg.d/apertis-exclusions
+
+This file will be added to the rootfs, which in this instance will change
+the default behaviour of dpkg to suit the needs of the image
+
+Collections of images are built every night and published on the
+[deployable image hosting website](https://images.apertis.org), such that
+developers can always download the latest image to deploy it to a target device
+and start using it immediately.
+
+## Automated testing with LAVA
+
+To ensure the continued quality of the generated images, a set of automated
+on-device tests is run for every image so issues can be found early if they arise
+and handled in a timely fashion by developers.
+
+# Key technologies
+
+Apertis makes heavy use of some technologies for its purposes:
+
+- Debian packages
+- systemd for application life cycle tracking
+- AppArmor for policy enforcement
+- OSTree/Flatpak for safe and efficient deployments
+- D-Bus for privilege separation
+- Wayland for graphics
+- GStreamer for multimedia playback
+
+## OTA update strategies
+
+Apertis currently uses [OSTree]({{< ref "guides/ostree.md" >}}) for OTA
+updates. This solution:
+
+* works in containers
+* works on flash-specific file systems like UBIFS
+* results in small downloads
+
+## Application framework
+
+Apertis ships an
+[application framework]({{< ref "application-framework.md" >}}) that provides
+flexibility and modularity post-deployment:
+
+- deploying applications can be done independently from full system updates
+- network access, inter-process communications and file access policies are
+  enforced through AppArmor
+- failed application deployments are safely rolled back
+- works both on targets, virtual machines and containers
+- Flatpak-based application bundle file format
+- the `ade` command-line tool simplifies the generation of application bundles
+
+## Domain separation
+
+Apertis is designed to work in setups where tasks are split over different
+domains, which can be connected SoCs, virtual machines or containers, for
+instance on setups where a privileged domain has no direct Internet access but
+relies on a separated, more constrained domain to access network services and
+validate any communication.

dictionary.aspell

-personal_ws-1.1 en 72 utf-8
+personal_ws-1.1 en 83 utf-8
 ARMv
 ATF
 Apertis
 AppArmor
 CPUs
 Collabora
+CVE
+CVEs
 DAC
 Debos
 Flatpak
@@ -22,6 +24,8 @@ LFS
 LXC
 MAC
 MX
+OSTree
+OTA
 OpenSSL
 PDF
 PDFs
@@ -61,6 +65,7 @@ cryptographic
 decrypt
 deduplicate
 deduplicated
+deliverables
 deployable
 devkit
 dockerized