diff --git a/content/designs/image-build-infrastructure.md b/content/architecture/image-build-infrastructure.md
similarity index 96%
rename from content/designs/image-build-infrastructure.md
rename to content/architecture/image-build-infrastructure.md
index 6be6535c5defdb2ba79527834da030d0fdef67e4..1ae86b62b8bacc3dd52b713966faac0c44bc284d 100644
--- a/content/designs/image-build-infrastructure.md
+++ b/content/architecture/image-build-infrastructure.md
@@ -20,13 +20,13 @@ development cycle. Refer to the documentation in the
project for information about the current pipeline.
{{% /notice %}}
-## Introduction
+# Introduction
The Apertis infrastructure supports continuous building of reference images,
hwpacks and ospacks. This document explains the infrastructure setup,
configuration and concepts.
-## Technology overview
+# Technology overview
To build the various packs (hardware, os) as well as images, Apertis uses
[Debos](https://github.com/go-debos/debos), a flexible tool to configure the
@@ -53,7 +53,7 @@ The second job defines the build steps for the various ospacks, hardware packs a
images which are run in the Docker image build by the previous job; it also
uploads the results to images.apertis.org.
-## Jenkins master setup
+# Jenkins master setup
Instructions to install Jenkins can be can be found on the
[Jenkins download page](https://jenkins.io/download/). Using the Long-Term
@@ -63,7 +63,7 @@ Jenkins master is being run on Debian 9.3 (stretch).
The plugins that are installed on the master can be found in the [plugins
appendix][Appendix: List of plugins installed on the Jenkins master]
-## Jenkins slave setup
+# Jenkins slave setup
Each Jenkins slave should be installed on a separate machine (or VM) in line
with the Jenkins best practices. As the image build environment is contained in
@@ -90,7 +90,7 @@ configured as part of the `docker` group.
Documentation on how to setup Jenkins slaves can be found as part of the
[Jenkins documentation](https://wiki.jenkins.io/display/JENKINS/Distributed+builds).
-## Docker registry setup
+# Docker registry setup
To avoid building Docker images for every image build round and to make it
easier for Jenkins and developers to share the same Docker environment for
@@ -98,7 +98,7 @@ build testing, it is recommended to run a Docker registry. The
[Docker registry documentation](https://docs.docker.com/registry/deploying/)
contains information on how to setup a registry.
-## Docker images for the build environment
+# Docker images for the build environment
The Docker images defining the environment for building the images can be found
in the
@@ -113,7 +113,7 @@ authenticated upload channel `auth.docker-registry.apertis.org`.
For Apertis derivatives this file should be adjusted to upload the Docker image
to the Docker registry of the derivative.
-## Image building process
+# Image building process
The image recipes and configuration can be found in the
[apertis-image-recipes git repository](https://gitlab.apertis.org/infrastructure/apertis-image-recipes).
@@ -125,7 +125,7 @@ The various recipes provide the configuration for debos, documentation about
the available actions can be found in the
[Debos documentation](https://godoc.org/github.com/go-debos/debos/actions).
-## Jenkins jobs instantiation
+# Jenkins jobs instantiation
Jenkins needs to be pointed to the repositories hosting the Jenkinsfiles by
creating matching jobs on the master instance. This can be done either manually
@@ -137,13 +137,13 @@ For that purpose Apertis uses a set of job templates hosted in the
[`apertis-jenkins-jobs`](https://gitlab.apertis.org/infrastructure/apertis-jenkins-jobs)
repository.
-## OSTree support (server side)
+# OSTree support (server side)
The image build jobs prepare OSTree repository to be installed server side. In
order to properly support OSTree server side, `ostree-push` package must be
installed in the OSTree repository server.
-## Appendix: List of plugins installed on the Jenkins master
+# Appendix: List of plugins installed on the Jenkins master
At the time of this writing the following plugins are installed on the Apertis
Jenkins master:
diff --git a/content/designs/software-distribution-and-updates.md b/content/architecture/software-distribution-and-updates.md
similarity index 95%
rename from content/designs/software-distribution-and-updates.md
rename to content/architecture/software-distribution-and-updates.md
index 4422433cafe083f4a086868dc79d0b3870869544..c57cd40746aafeb857af2bf3e48d31975d8fc445 100644
--- a/content/designs/software-distribution-and-updates.md
+++ b/content/architecture/software-distribution-and-updates.md
@@ -12,19 +12,15 @@ outputs = [ "html", "pdf-in",]
date = "2019-02-13"
+++
-# Software distribution and updates
-
-## Introduction
-
Apertis is a mature platform that is compatible with modern and flexible
solutions for software distribution and software update. This document describes
user-driven and operator-driven use cases, explores the challenges of each use
case to extract requirements, and finally propose building blocks for software
distribution and software update.
-## Terminology
+# Terminology
-### Application and services
+## Application and services
Application and services are loosely defined terms that indicate single
functional entities from the perspective of end users. However each application
@@ -39,7 +35,7 @@ applications and services can be deployed as part of the base operating system
or separately as
[bundles]( {{< ref "glossary.md#application-bundle" >}} ).
-### Base operating system
+## Base operating system
The base operating system is the core component of the software stack. It
includes the kernel, and basic userspace tools and libraries such as process
@@ -47,7 +43,7 @@ manager, connectivity services, and update manager. Additional components like
an application manager may be part of the base OS, depending on the intended
usage.
-### Bundles
+## Bundles
A bundle or "application bundle" refers to a unit that represent all the
components of an Application or service. Comparing to mobile phones a bundle is
@@ -66,7 +62,7 @@ configurable run time permissions for user data and system resources.
Docker images, Flatpak bundles, and Snaps are all examples of application bundles.
-### Software distribution
+## Software distribution
Software distribution is the process of delivering software to users and
devices. It usually refers to the distribution of binaries of software to be
@@ -74,14 +70,14 @@ installed or updated. However software distribution is more than a transport
layer for packages an it can include authorization, inventory, and deployment
management.
-### Software updates
+## Software updates
The most common goals of an update are fixing bugs, removing security
vulnerabilities, and adding new features to already installed software. Updating
a software component may also involve updating the chain of dependencies of that
software component.
-## Operator-driven use cases
+# Operator-driven use cases
The operator is an entity with the responsibility of ensuring that the devices
operate within pre-defined specifications. A device can have more than one
@@ -89,7 +85,7 @@ operator such as the manufacturer and the owner of the devices, and the
operators, and not the device user, have powers to install, remove and update
software on the devices.
-### Building access control devices
+## Building access control devices
Access control is used to restrict access to a particular place, building,
room, or resource. To gain access an individual generally needs to be given
@@ -131,7 +127,7 @@ specific customer. Delivering the custom features requires conditional
deployment capabilities based on business rules such as device owner and service
level.
-### Robotic lawn mower
+## Robotic lawn mower
A robotic lawn mower is an electric autonomous robot that cuts lawn grass in a
pre-determined area. Common features of robotic lawn mowers include finding the
@@ -148,7 +144,7 @@ Connected robotic lawn mowers receive over-the-air updates that are installed
when the mower is not in use, respecting the schedule that was configured by the
operator.
-## User-driven use cases
+# User-driven use cases
There are two categories of user-driven use cases. The first one is built on
top of operator-driven use cases. In this category the device allow users to
@@ -156,7 +152,7 @@ install and remove optional applications, but keeps the operator in control of
system updates and system applications. In the second category the device is
left under full control of the user, without any operator involvement.
-### Infotainment system
+## Infotainment system
An infotainment system is usually an interface between users and a vehicle
showing information about the vehicle and allowing the user to configure
@@ -218,7 +214,7 @@ systems. Users should not be able to render the device inoperative, or make the
device to operate outside its design specifications by continuous use, by
changing configurations, or by installing/uninstalling applications.
-### Power and measuring tools
+## Power and measuring tools
Power tools are electrically driven tools such as drills and grinders, with most
models being powered by batteries. Measuring tools are electronic devices for
@@ -231,7 +227,7 @@ convenient interface for the user to adjust operating parameters and to see the
device status. The user can choose between a web interface and a mobile phone
application to interact with power and measuring tools.
-## Non-use-cases
+# Non-use-cases
* Product development: during product development developers need to privilege
flexibility over robustness. However robustness is of primary importance in
production environment, and as such flexibility to ease development is not a
@@ -240,9 +236,9 @@ application to interact with power and measuring tools.
* Workstations: while the mechanism described here are valuable on
workstations as well, they are not the focus of this document.
-## Requirements
+# Requirements
-### Conditional software deployment based on business rules
+## Conditional software deployment based on business rules
It should be possible to restrict the selection of software components that
users and operators can install, remove and update based on business rules such
@@ -252,48 +248,48 @@ It should also be possible for the operator to configure the deployment to
adhere to business rules such as available time slots for maintenance, and to
split complex deployments in batches.
-### Configurable access rights to user data and system resources
+## Configurable access rights to user data and system resources
Applications should have limited and configurable access to system resources and
user data. For example, applications should not be capable of taking screen
shots, and the music player should have access to only specific files and
folders.
-### Consistent state across devices
+## Consistent state across devices
Maintaining a large fleet of devices requires the software stack of each device
to be in a known state. Devices in unknown state are challenging to maintain and
may present reliability and security issues.
-### Independent release and update of application domains
+## Independent release and update of application domains
It should be possible to release and update application domains independently
from the base operating system.
-### Operator-driven software distribution and updates
+## Operator-driven software distribution and updates
On operator-driven use cases, the operator should be capable of controlling the
software distribution and update of large fleets of devices.
-### Protecting the fleet from software deployment issues
+## Protecting the fleet from software deployment issues
There should be mechanisms in place to prevent software distribution and
software update issues, such as an update that renders the devices unusable, to
affect the entire fleet of devices.
-### Resilience to distribution and update failures
+## Resilience to distribution and update failures
Minor problems such as an update failure due to download problem caused by a
network issue on the device side should not render the device inoperative and
should recover automatically without intervention.
-### Resilience to user operation
+## Resilience to user operation
User actions including installing and removing optional applications should not
render the device inoperative, or make the device to operate outside its design
specifications.
-### Software inventory
+## Software inventory
Operators require software inventory information such as installed software, and
software version to make decisions about how and when to do software deployment.
@@ -301,13 +297,13 @@ As an example when a security vulnerability is discovered, having an overview
of how many devices are affected is important to determine the severity of the
vulnerability, and to plan a response.
-### Tampering protection
+## Tampering protection
Mission critical devices and devices subject to regulation require protection
against unauthorized modification. Users should not be allowed to modify the
devices to operate outside its design specifications.
-### Unwanted changes to the software stack
+## Unwanted changes to the software stack
A common method of attacking a device consists in changing software that is
installed or installing malicious components. Preventing unwanted changes
@@ -315,17 +311,17 @@ on the software stack, and preventing non-authorized software to be installed
eliminates an important attack vector: attacks that require changes to the
software stack.
-### Updates rollback
+## Updates rollback
Software updates should be reversible, and allow to rollback to a previous
working state. This requirement applies to system software and applications.
-### User-driven software distribution
+## User-driven software distribution
The user should be capable of installing and removing software components on
user-driven use cases.
-## High level features
+# High level features
Before describing existing solutions it is necessary to group the requirements
in features that are implemented by these solutions. One requirement may be
@@ -333,7 +329,7 @@ related to more than one feature such as the requirement *Consistent state
across devices* being related to the features *Immutable software stack* and
*Atomic updates*.
-### Immutable software stack
+## Immutable software stack
* Related requirements: *Consistent state across devices*, *Resilience to user
operation*, *Tampering protection*, *Unwanted changes to the software stack*
@@ -341,7 +337,7 @@ across devices* being related to the features *Immutable software stack* and
One solution to address these requirements is to make the base operating system
and the application domains immutable.
-### Atomic updates
+## Atomic updates
* Related requirements: *Consistent state across devices*, *Protecting the fleet
from software deployment issues*, *Resilience to distribution and update
@@ -363,7 +359,7 @@ However the benefits of reliable rollbacks are limited to changes made to the
filesystem. Changes that are not file operations, such as updating the
bootloader are not guaranteed to rollback gracefully.
-### Separation between system and application domains
+## Separation between system and application domains
* Related requirements: *Conditional software deployment based on business
rules*, *Configurable access rights to user data and system resource*,
@@ -379,7 +375,7 @@ Separating base operating system from application domains allow product teams to
develop their products with greater independence, and offers more flexibility on
how application domains are deployed, updated and executed.
-### Deployment management
+## Deployment management
* Related requirements: *Conditional software deployment based on business
rules*, *Consistent state across devices*, *Operator-driven software
@@ -405,9 +401,9 @@ infrastructure that interfaces with agents running one the devices. A common
goal to deployment management is to offer easy and flexible rollout of software
with monitoring of progress which is essential for large fleets.
-## Existing systems
+# Existing systems
-### OSTree for base operating system
+## OSTree for base operating system
OSTree implements for the base operating system *Immutable software stack* and
*Atomic updates*. It also offers the underlying framework to allow *Separation
@@ -436,7 +432,7 @@ However OSTree does not directly address the needs of application domains. For
software distribution and update of application domains we recommend using
either Flatpak or Docker.
-### Flatpak and Docker for applications
+## Flatpak and Docker for applications
Both Flatpak and Docker implement for applications *Immutable software stack*,
*Atomic updates*, and *Separation between system and application domains*. One
@@ -470,7 +466,7 @@ Flatpak is better suited for the applications the user can install and remove.
For the building access control devices Docker is a better fit for headless
applications that collect identity data and controls locking mechanisms.
-### Eclipse hawkBit
+## Eclipse hawkBit
Eclipse hawkBit implements *Deployment management*.
@@ -480,7 +476,7 @@ agnostic about the kind of applications used. A preliminary investigation of the
feasibility of the integration of the hawkBit-based Bosch Software Innovations
IoT management suite with Apertis has been done with positive outcome.
-### Microsoft Azure IoT Edge
+## Microsoft Azure IoT Edge
Eclipse hawkBit implements *Deployment management*.
@@ -492,7 +488,7 @@ A preliminary Apertis image with support for Docker containers has been
evaluated to explore the feasibility of using Apertis with Microsoft Azure IoT
Edge.
-## Appstore
+# Appstore
An appstore should meet the requirements: *Conditional software deployment
based on business rules*, *Independent release and update of application
@@ -520,7 +516,7 @@ devices, and an appstore may not be part of the use case. Instead the operator
uses an interface to change device configuration and to control deployment of
updates and new features.
-### Curridge
+## Curridge
Curridge is a custom non-upstream solution based on the Magento web commerce
framework. At the moment Curridge has only been part of demonstrations done by
@@ -536,7 +532,7 @@ such as Flathub and hawkBit. This interfacing could allow Curridge to focus on
the appstore user, and offload other tasks such as deployment management and
bundle compatibility to dedicated components.
-### Flathub
+## Flathub
Flathub is the upstream appstore for applications distributed via
Flatpak.
@@ -551,7 +547,7 @@ applications for app management, such as GNOME Software or KDE Discover.
Flathub does not support payments at the moment, even though there's upstream
interest in the feature. It does not provide any remote management solution.
-## Summary of recommendations
+# Summary of recommendations
* Use OSTree for the base operating system for *Immutable software stack*,
*Atomic updates*, and *Updates rollback*.
@@ -572,7 +568,7 @@ interest in the feature. It does not provide any remote management solution.
Flatpak for the on-device user interface
* Open point: Should Curridge be adapted to interface with Flathub?
-## Reference: System updates and rollback
+# Reference: System updates and rollback
The [System updates and
rollback]( {{< ref "system-updates-and-rollback.md" >}} )
diff --git a/content/designs/web-engine.md b/content/architecture/web-engine.md
similarity index 95%
rename from content/designs/web-engine.md
rename to content/architecture/web-engine.md
index a8602f70e41435eaed3b9d09d5afe7d8bc7c6032..342235a909c7ccf619c7995e8fc20a9f5b2d3749 100644
--- a/content/designs/web-engine.md
+++ b/content/architecture/web-engine.md
@@ -12,15 +12,11 @@ outputs = [ "html", "pdf-in",]
date = "2019-03-14"
+++
-# Web engine
-
-## Introduction
-
Apertis provides the GTK port of WebKit as its web engine. To
ensure low maintenance effort, no changes are made to the downstream
branch, any improvements should go to the upstream project.
-### Security maintenance
+## Security maintenance
Like all other major browser engines, the GTK port does not provide long
term support, so security maintenance comes down to staying up to date.
@@ -29,14 +25,14 @@ The general approach Apertis takes is to follow whatever Debian provides.
The project may also importing a new upstream release that has not been
made available in Debian yet if an important fix is available.
-### Customization
+## Customization
Apertis has made a decision to not perform customizations to the engine
with the goal of keeping maintenance efforts to a minimum. Whenever a
feature is desired, it should be proposed and contributed directly
upstream.
-#### White-listing and black-listing
+### White-listing and black-listing
There has been interest in maintaining a black-list of web applications
(or pages) that misbehaved. That would be for the case in which the
@@ -59,7 +55,7 @@ infrastructure in what could be considered a false positive. A
white-list can easily be implemented, keeping a list of applications
that are allowed to go over the limits should be enough.
-#### Rendering of non-web documents
+### Rendering of non-web documents
Several kinds of documents that are not strictly web documents are
available on web sites for viewing and download. Some of these types of
@@ -73,9 +69,9 @@ can also embed different widget alongside the WebView if they would like
to allow viewing PDFs and other kinds of documents on the same user
interface.
-## Scheduled and potential future work
+# Scheduled and potential future work
-### Web runtime
+## Web runtime
There is interest in providing developers with a way to write
applications using web technologies for Apertis. While this is out of
diff --git a/content/designs/testcase-dependencies.md b/content/concepts/testcase-dependencies.md
similarity index 100%
rename from content/designs/testcase-dependencies.md
rename to content/concepts/testcase-dependencies.md
diff --git a/content/designs/lava-external-devices.md b/content/guides/lava-external-devices.md
similarity index 99%
rename from content/designs/lava-external-devices.md
rename to content/guides/lava-external-devices.md
index 5bebd47cd790b80c278facae01b228629d42770c..7cee4842cec417a0d4eb08e4c185263256cd902f 100644
--- a/content/designs/lava-external-devices.md
+++ b/content/guides/lava-external-devices.md
@@ -11,8 +11,6 @@ outputs = [ "html", "pdf-in",]
date = "2019-09-11"
+++
-# LAVA External Device Monitoring
-
This document describes how to execute automated LAVA tests controlling resources
external to the DUT across a network implementing a LAVA parallel pipeline job.
diff --git a/content/designs/release-flow.md b/content/policies/release-flow.md
similarity index 99%
rename from content/designs/release-flow.md
rename to content/policies/release-flow.md
index 407f95eebca28402ef08e3c1fd1b57dccde9dfd2..5110e1f724c5a12db96586e47e6b5a5e8006ad51 100644
--- a/content/designs/release-flow.md
+++ b/content/policies/release-flow.md
@@ -11,8 +11,6 @@ outputs = [ "html", "pdf-in",]
date = "2019-09-13"
+++
-# Introduction
-
Apertis and its direct downstreams are intended as baseline distributions for further
product development, as such it's important to have a clear definition of what
downstreams further down the chain can expect in terms of releases and support cycles
@@ -362,7 +360,7 @@ final product release for further testing and validation by downstreams. As such
a preview release should achieve a high level of stability: this means that
during a preview release cycle only non-disruptive software or infrastructure
updates will be allowed. Similarly, new features can only be introduced if they
-posw a low risk on existing functionality and do not have an impact on the overall
+pose a low risk on existing functionality and do not have an impact on the overall
platform stability.
During the preparation of a preview release extra focus should be given to
@@ -548,7 +546,7 @@ planned to start. After production has started the guidelines for
post-production support should be taken into account.
For the initial development phase there are two main options:
-* follow the development reasonable of Apertis or its direct downstreams;
+* follow the development releases of Apertis or its direct downstreams;
* follow the product releases of Apertis or its direct downstreams (switching at the preview stage).
The first option allows the product development to use the very latest Apertis