Update headings to have a clean page-level TOC

explanation/application-streaming.md

@@ -41,11 +41,11 @@ The following illustration shows how the streaming stack components interact wit
 
 While streaming an application, session creation can happen in two ways as illustrated in the diagram above. Until the 1.22.0 release, a session had to be first created on the stream gateway to be able to create Anbox Cloud instances that can be streamed. Once the session was created, the instance creation will be triggered as detailed in the process below:
 
-### 1. Creating the session
+### Session creation
 
 A session is created by calling the gateway API at `POST /1.0/sessions`. The returned object contains information about the created session as well as a web socket `url` that is necessary to start the signalling process.
 
-### 2. Starting the signalling process
+### Signalling process
 
 Using the session information, the signalling process between the client and the instance starts:
 
@@ -58,13 +58,13 @@ Using the session information, the signalling process between the client and the
 
 Details about messages exchanged between the client and the instance are not covered in this guide, but you can find more information on [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling).
 
-### 3. Establishing the stream
+### Establishing the stream
 
 When optimal ICE candidates have been selected and codec capabilities have been agreed upon, the actual tracks are sent. These tracks can be either video, audio or binary. The binary data channel can be useful to send arbitrary data-like controls.
 
 The streams can then be consumed to display the final content.
 
-## Streaming an application by creating a stream-enabled instance
+## Stream-enabled instances
 
 Starting from 1.22.0, Anbox Cloud offers a much simpler way to create instances that can be streamed. This is the alternative implementation depicted in the streaming stack diagram.
 

explanation/clustering.md

@@ -3,24 +3,22 @@
 
 While it is possible to install Anbox Cloud on a single machine, Anbox Cloud Appliance does not support multi-node setups. If you intend to distribute the load across multiple machines in a cluster, it is recommended to use Anbox Cloud for full deployments instead.
 
-## Clustering for full Anbox Cloud deployments
-
 In a clustering setup for a full Anbox Cloud deployment, one node is dedicated as the management node to host the Anbox Management Service (AMS). If you use the Streaming Stack, two additional nodes are dedicated to host the extra services required for streaming. All other nodes are used as worker nodes.
 
 Each worker node runs [LXD](https://ubuntu.com/lxd) in [clustering mode](https://documentation.ubuntu.com/lxd/en/latest/clustering/), and this LXD cluster is used to host the Android containers.
 
-### Cluster capacity
+## Cluster capacity
 
 Anbox Cloud is optimised to provide instances at high density per host. To determine how many cluster nodes you need and what resources they should have, you must estimate the capacity that you require for your use case. See {ref}`exp-capacity-planning` for more information.
 
 (sec-lxd-auto-scaling)=
-### LXD auto scaling
+## LXD auto scaling
 
 Different use cases for Anbox Cloud require elasticity of the LXD cluster to deal with dynamic user demand throughout a certain time period. This involves increasing the number of nodes of the LXD cluster when demand increases and reducing the number of nodes when demand decreases. As Anbox Cloud provides fine-grained capacity management to have tight control over how many users/instances are running on a single node, the driving factor for an auto scaling implementation cannot be deduced from CPU, memory or GPU load but from the planned capacity of the currently available nodes in the cluster.
 
 The current release of Anbox Cloud has no built-in auto scaling implementation but comes with all needed primitives to build one. In a future version, Anbox Cloud will provide an auto scaling framework that will simplify various aspects of an implementation.
 
-#### Guidelines for auto scaling
+### Guidelines for auto scaling
 
 The following guidelines are both recommended and must-have aspects of an auto scaling implementation. Make sure that your auto scaling implementation follows these to stay within a supported and tested scope.
 
@@ -31,7 +29,7 @@ The following guidelines are both recommended and must-have aspects of an auto s
 1. Scaling down **MUST** strictly happen in a sequential order with no other scaling operations (for example, scale up) running in parallel.
 1. Before removing a LXD node from the cluster you **MUST** delete all instances on it.
 
-### Scaling up or down the cluster
+## Scaling up or down
 
 The decision of when to scale a cluster up or down is not simple and is different for each use case. The traditional approach to measure CPU, memory or GPU load does not apply for Anbox Cloud as capacity is well-planned and the number of instances per node is configured ahead of time. Furthermore, user patterns are hard to predict and will be different in each case. Hence, custom logic is required to take a decision when a cluster should be scaled up or down.
 

explanation/images.md

@@ -3,7 +3,7 @@
 
 An image represents the Anbox Cloud image available in the AMS node. An image is the base for an instance, which contains all necessary components like Anbox or the Android root file system. The image type can be container or virtual machine.
 
-# Possible image statuses
+## Possible image statuses
 
 The following table lists the different statuses that an image can have depending on its state and what each status means:
 

explanation/instances.md

@@ -6,7 +6,7 @@ Instances are the centre piece of the Anbox Cloud stack. Every time you launch a
 All instances in Anbox Cloud are ephemeral, which means that as soon as an instance is stopped, all of its data is deleted. Anbox Cloud **DOES NOT** back up any data from the Android or the outer Ubuntu instance. Backup and restore of data must be implemented separately through addons. See {ref}`howto-backup-restore-example` for information on how to do this.
 
 (sec-regular-base-instances)=
-## Regular instances vs. base instances
+## Regular vs. base instances
 
 Anbox Cloud differentiates between two types of instances: regular and base. The instance type is visible in the output of the `amc ls` command.
 
@@ -17,7 +17,7 @@ Base instances are temporary containers or virtual machines that are used when b
 When we refer to instances in this documentation without specifying the instance type, we mean regular instances.
 
 (sec-application-raw-instances)=
-## Application instances vs. raw instances
+## Application vs. raw instances
 
 Instances are based on either {ref}`exp-applications` or {ref}`Images <ref-provided-images>`. So if you launch an application or an image, Anbox Management Service (AMS) automatically creates an instance for it.
 

howto/aar/configure.md

@@ -1,7 +1,7 @@
 (howto-configure-aar)=
 # How to configure an AAR
 
-The Anbox Application Registry (AAR) uses a certificate-based authentication system that uses TLS server and client certificates to establish a trusted connection between the AAR and AMS.
+The Anbox Application Registry (AAR) uses a certificate-based authentication system that uses TLS server and client certificates to establish a trusted connection between the AAR and the Anbox Management Service (AMS).
 
 AAR and AMS must exchange certificates to set up a trust relation. The recommended way to do this is with Juju. If you are using the Anbox Cloud Appliance, however, you must register the clients manually.
 
@@ -41,7 +41,7 @@ If you are running the Anbox Cloud Appliance, you must register the clients manu
 
 Adding clients manually requires access to the machines hosting AMS and the AAR.
 
-### Configure AMS
+### Import AAR certificate
 
 The first step is to import the AAR certificate into every AMS instance that should have access to the AAR. You can find the AAR certificate at `/var/snap/aar/common/certs/server.crt` on the machine hosting the AAR. Copy the certificate to the AMS machine and import it with the following command:
 
@@ -51,9 +51,9 @@ Use the following command to verify that the new certificate is listed in the AM
 
     amc config trust list
 
-### Configure AMS to use the AAR
+### Configure AMS-AAR sync
 
-To configure AMS to pull or push applications and new application versions to or from the AAR, you must tell AMS about the registry endpoint first:
+To configure AMS to sync applications and new application versions with the AAR, you must tell AMS about the registry endpoint first:
 
     amc config set registry.url https://192.168.178.45:3000
 
@@ -65,25 +65,25 @@ Set the certificate fingerprint with the following command:
 
     amc config set registry.fingerprint <fingerprint>
 
-Finally, set the interval in which AMS will check for new applications to push or pull to or from the AAR. By default, the interval is set to one hour. You can set it to a smaller interval of five minutes with the following command:
+Finally, set the interval in which AMS will check for new applications to sync with the AAR. By default, the interval is set to one hour. You can set it to a smaller interval of five minutes with the following command:
 
     amc config set registry.update_interval 5m
 
-AMS will now check every five minutes if any updates need to be pushed or pulled to or from the AAR.
+AMS will now check every five minutes if any updates need to be synced with the AAR.
 
-### Configure AMS to push applications to the AAR
+### Configure AMS to push
 
-To tell AMS to push any local applications to the AAR, set the `registry.mode` configuration item to `push`:
+To configure AMS to push any local applications to the AAR, set the `registry.mode` configuration item to `push`:
 
     amc config set registry.mode push
 
 All existing and future applications and updates are now automatically pushed to the AAR.
 
 Keep in mind that only published application versions are pushed to the AAR. If you don't publish a version, it will not be pushed.
 
-### Configure AMS to pull applications from the AAR
+### Configure AMS to pull
 
-To tell AMS to pull applications from the AAR, set the `registry.mode` configuration item to `pull`:
+To configure AMS to pull applications from the AAR, set the `registry.mode` configuration item to `pull`:
 
     amc config set registry.mode pull
 

howto/anbox/manage-images.md

@@ -29,7 +29,7 @@ You can see the synchronised images with the `amc image list` command:
 +----------------------+------------------------+--------+----------+--------------+---------+
 ```
 
-## Default image
+## Set default image
 
 The first image that is synchronised (usually the newest image) is marked as the default image.
 The default image is used when you create an application without the `image` field or launch a raw instance without specifying any ID.
@@ -66,7 +66,7 @@ The following command removes version `1` of the image with the name `image-name
 
     amc image delete image-name --version=1
 
-## Use a specific release of an image
+## Use a specific release
 
 With every new Anbox Cloud release, updated images are published. By default, the latest image release is pulled by AMS, but you can request a specific release with the following syntax:
 

howto/anbox/tls-for-appliance.md

@@ -3,21 +3,25 @@
 
 The Anbox Cloud Appliance uses a self-signed certificate to provide HTTPS services. If you want to serve the appliance over HTTPS using a valid SSL/TLS certificate, follow the steps in this document to generate and install a valid SSL/TLS certificate on the Anbox Cloud Appliance.
 
-```{note}
-This document assumes you have the Anbox Cloud Appliance installed. If you haven't, follow the {ref}`tut-installing-appliance` tutorial to do so.
-```
-
 If you run the appliance on AWS, you can choose to use the AWS Certificate Manager. Otherwise, you must manage the certificate yourself manually.
 
-## Manage the certificate yourself
+## Prerequisites
+
+Before you start, make sure the following requirements are met:
+
+- The Anbox Cloud Appliance is installed and initialised. See {ref}`howto-install-appliance-aws` and {ref}`sec-initialise-appliance` for instructions.
+
+- If you want to use the AWS certificate manager, you should have a domain name for use with the Anbox Cloud Appliance registered, either through Amazon Route 53 (see [Register a new domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) in the Amazon Route 53 documentation) or  through another domain provider.
 
-To generate and install a certificate yourself, complete the following steps.
+## Manage the certificate manually
 
-### 1. Add a DNS record
+To generate and install a certificate yourself, complete the following steps:
+
+### Add a DNS record
 
 Setting up DNS redirection depends on your DNS provider. Refer to the documentation of your provider to create a DNS record pointing to the IP/DNS of the AWS instance where the Anbox Cloud Appliance is running.
 
-### 2. Configure the location
+### Configure the location
 
 Configure the location for the appliance using the created DNS name:
 
@@ -27,7 +31,7 @@ Configure the location for the appliance using the created DNS name:
 This option is experimental. It will be removed in a future release when a better replacement exists.
 ```
 
-### 3. Generate an SSL certificate
+### Generate an SSL certificate
 
 There are many ways to create a valid SSL certificate. One way is to use [Let's Encrypt](https://letsencrypt.org/) to generate a free SSL certificate.
 
@@ -54,7 +58,7 @@ These files will be updated when the certificate renews.
 Certbot has set up a scheduled task to automatically renew this certificate in the background.
 ```
 
-### 4. Install the SSL certificate
+### Install the SSL certificate
 
 Copy the generated certificate to the `/var/snap/anbox-cloud-appliance/common/traefik/tls` directory:
 
@@ -103,19 +107,12 @@ The appliance will face a short downtime during the renewal of the SSL certifica
 
 If you run the Anbox Cloud Appliance on AWS, you can use the [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) to provision and manage your TLS certificate.
 
-Before you start, make sure the following requirements are met:
-
-- You have a domain name for use with the Anbox Cloud Appliance registered, either through Amazon Route 53 (see [Register a new domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) in the Amazon Route 53 documentation) or  through another domain provider.
-
-  ```{note}
+```{note}
   The screenshots in the following instructions use an example domain name that is not owned or controlled by Canonical. Replace it with your own domain name when following the setup instructions.
   ```
-- The Anbox Cloud Appliance is installed and initialised. See {ref}`howto-install-appliance-aws` and {ref}`sec-initialise-appliance` for instructions.
-
-Then complete the following steps.
 
 (sec-configure-routing-info-name-servers)=
-### 1. Configure routing information and name servers
+### Configure routing information and name servers
 
 ```{note}
 You can skip this step if you registered your domain name through Amazon Route 53.
@@ -142,7 +139,7 @@ In the case of the Anbox Cloud Appliance, we want the traffic routed to the AWS
 
    ![Configure custom name servers for your domain with your domain provider](https://assets.ubuntu.com/v1/433fdfd9-manage_tls_enter-nameservers.png)
 
-### 2. Create a public certificate
+### Create a public certificate
 
 To create a public certificate using the AWS Certificate Manager, you must first request a certificate and then validate that you own the domain that the certificate applies to.
 
@@ -159,7 +156,7 @@ DNS propagation usually takes a while. When it completes and the validation is s
 
 ![Valid certificate in AWS Certification Manager](https://assets.ubuntu.com/v1/b95943aa-manage_tls_certificate-status.png)
 
-### 3. Create a load balancer
+### Create a load balancer
 
 To use the Anbox Cloud Appliance through your domain name, AWS must route the HTTPS traffic for your domain to the Anbox Cloud Appliance. To ensure this, you must create a load balancer that listens for traffic and routes it to the appliance.
 
@@ -193,7 +190,7 @@ To use the Anbox Cloud Appliance through your domain name, AWS must route the HT
    ![Listener settings](https://assets.ubuntu.com/v1/3308aa3a-manage_tls_listener-settings.png)
 1. Check the **Summary**, and if everything looks correct, click **Create load balancer**.
 
-### 4. Direct traffic from your domain to the load balancer
+### Direct traffic from your domain to the load balancer
 
 When the load balancer is created, AWS assigns it an automatic DNS name. The following example shows where to find it:
 
@@ -220,7 +217,7 @@ The following example shows the DNS record with type `A` for the example domain:
 
 ![DNS records for the public hosted zone](https://assets.ubuntu.com/v1/5a4986bd-manage_tls_dns-records.png)
 
-### 5. Configure the appliance to use the domain name
+### Configure the appliance to use the domain name
 
 Finally, configure the Anbox Cloud Appliance to use the domain name that you prepared.
 

howto/android/create-virtual-device.md

@@ -28,7 +28,7 @@ resources:
   gpu-slots: 3
 ```
 
-## Optionally extend the application
+## (Optional) extend the application
 
 If you want to install additional applications that you want to offer as part of the default virtual device, you can extend the application with {ref}`ref-hooks`. For example, you could replace the standard Android launcher with a custom one or change the system locale.
 

howto/application/extend-application.md

@@ -29,7 +29,7 @@ You must then add the hook file to your application, either as an application ho
 
 The following sections give some examples for hooks.
 
-### Create a hook for changing the Android system locale
+### Change the Android system locale
 
 Complete the following steps to create a hook that changes the Android system locale to Korean:
 <!-- wokeignore:rule=master -->
@@ -65,7 +65,7 @@ Complete the following steps to create a hook that changes the Android system lo
 
         cd .. && chmod +x hooks/*
 
-### Create a hook to replace the standard Android launcher
+### Replace the standard Android launcher
 
 Complete the following steps to create a hook that replaces the standard Android launcher with the custom launcher [Lawnchair](https://lawnchair.app/):
 

howto/application/update-application.md

@@ -111,7 +111,7 @@ Each version takes up space on the LXD nodes. To free up space and remove old an
 The command will ask for your approval before the version is removed as it might affect your users. If you want to bypass the check, you can add the `--yes` flag to the command.
 
 (sec-configure-automatic-app-updates)=
-## Configure automatic application updates
+## Configure automatic updates
 
 AMS automatically updates an application whenever any of its dependencies (parent image, addons, global configuration) changes. This produces a new version for the application, which is automatically published if the `application.auto_publish` configuration item is enabled.
 
@@ -131,7 +131,7 @@ When automatic updates are disabled, applications must be manually updated for a
 
 This will initiate the update process and create a new application version.
 
-## Change image an application is based on
+## Change base image
 
 The image an application is based on can be changed with the following command:
 

howto/dashboard/landing.md

@@ -6,7 +6,7 @@ The Anbox Cloud Dashboard offers a web GUI that users can use to create, manage
 
 Before you can log into the dashboard, you must register your Ubuntu One account with the dashboard to authenticate.
 
-### Register an Ubuntu One account in Anbox Cloud
+### Register in Anbox Cloud
 
 On a regular Anbox Cloud deployment, use the following Juju action to register an Ubuntu One account:
 
@@ -28,7 +28,7 @@ unit-anbox-cloud-dashboard-0:
     started: 2021-02-10 14:04:44 +0000 UTC
 ```
 (sec-register-ubuntu-one-appliance)=
-### Register an Ubuntu One account in Anbox Cloud Appliance
+### Register in the appliance
 
 If you followed the instructions in the {ref}`tut-installing-appliance` tutorial, you already registered your Ubuntu One account.