Merge pull request #125 from advancedtelematic/bugfix/PRO-1371-polish-manual-install-guide

PRO-1371 Add info about the certificates file, events socket, and github repo

1 files changed, 9 insertions, 1 deletions

diff --git a/docs/client-guide.adoc b/docs/client-guide.adoc
index b5dab43..5968573 100644
--- a/docs/client-guide.adoc
+++ b/docs/client-guide.adoc
@@ -3,6 +3,12 @@
 :toc: left
 :toclevels: 3
 
+== Introduction
+
+The SOTA client is fully open source. If you wish, you can download and build the absolute latest version directly from https://github.com/advancedtelematic/rvi_sota_client[its GitHub repo]. However, ATS recommends using the provided binaries or building from the `stable` branch, as the latest master may not always be fully compatible with ATS Garage.
+
+This document describes link:#_starting_the_sota_client[how to manually install and set up the SOTA client], provides link:#_sota_client_config_file_guide[a line-by-line guide to the config file], and then describes link:#_api_documentation[the UNIX Domain Sockets API] for the SOTA client to communicate with the software loading manager.
+
 == Starting the SOTA client
 
 The SOTA client should be run at startup, as a service. We provide a systemd service file below as an example, but systemd is not a requirement. You can also, of course, run it from the command line to test. Setting the `RUST_LOG` environment variable will let you configure how much debug info you receive.
@@ -74,7 +80,7 @@ certificates_path = "/tmp/sota_certificates" <7>
 <4> The frequency, in seconds, with which the SOTA client should poll the server for updates.
 <5> The location SOTA Client should use for temporary package storage until they are processed by the software loading manager.
 <6> The software loading manager backend to use. Possible values are `deb`, `rpm`, and `off`. If an external software loading manager is in use, this should be set to `off`.
-<7> The certificate authorities SOTA Client trusts. Defaults taken from Mozilla Servo.
+<7> The certificate authorities SOTA Client trusts. The recommended defaults are taken from Mozilla Servo, and the default certificates file can be downloaded from https://raw.githubusercontent.com/advancedtelematic/rvi_sota_client/master/run/sota_certificates[the SOTA client repo]. You may also use your own CA file or the operating system's default trusted certificates file, but ATS recommends using the provided certificate file.
 
 === [network]
 
@@ -155,6 +161,8 @@ Currently, only the core functionality of making software updates available and
 
 To communicate with the SOTA Client over unix domain sockets, `socket = true` must be defined in the `[gateway]` section of the config file. Additionally, the names of the two sockets are configurable in the link:#__network[[network]] section.
 
+The SOTA Client will create the commands socket, but the software loading manager must create the events socket. Note that it must be readable and writable by root, and be at the location configured in `sota.toml`.
+
 ==== DownloadComplete
 
 Once the SOTA client has successfully downloaded an update ordered by an ATS Garage user, it will send a DownloadComplete event on the events socket with the following body: